Marionette.View

Marionette имеет базовый Marionette.View класс, от которого наследуются другие представления. Это базовое представление предоставляет некоторые общие и основные функции, которыми могут воспользоваться другие представления.

Примечание: Класс Marionette.View не предназначен для непосредственного использования. Он существует как базовое представление для расширения другими классами представлений и для предоставления общего места для поведения, используемого во всех представлениях.

Индекс документации

• Связывание с событиями представления
• Представление onShow
• Уничтожение представления
• Представление onBeforeDestroy
• Представление "attach" / событие onAttach
• Представление "before:attach" / событие onBeforeAttach
• Представление "dom:refresh" / событие onDomRefresh
• View.events
• View.triggers
• View.modelEvents и View.collectionEvents
• View.serializeModel
• View.bindUIElements
• View.mergeOptions
• View.getOption
• View.bindEntityEvents
• View.templateHelpers
  • Базовый пример
  • Доступ к данным в помощниках
  • Объект или функция в качестве templateHelpers
• Изменение шаблона, отображаемого для представления
• Интерполяция пользовательского интерфейса

Связывание с событиями представления

Marionette.View расширяет Backbone.View. Рекомендуется использовать метод listenTo для связывания событий модели, коллекции или других событий из объектов Backbone и Marionette.

var MyView = Marionette.ItemView.extend({
  initialize: function(){
    this.listenTo(this.model, "change:foo", this.modelChanged);
    this.listenTo(this.collection, "add", this.modelAdded);
  },

  modelChanged: function(model, value){
  },

  modelAdded: function(model){
  }
});

Контекст (this) будет автоматически задан в представлении. Вы можете дополнительно задать контекст, используя _.bind.

// Force the context of the "reconcileCollection" callback method to be the collection
// itself, for this event handler only (does not affect any other use of the
// "reconcileCollection" method)
this.listenTo(this.collection, "add", _.bind(this.reconcileCollection, this.collection));

Представление onShow

• "show" / onShow - Вызывается в экземпляре представления, когда представление было отображено и показано.

Это событие можно использовать для реакции на отображение представления через регион. Все views , которые наследуют от базового класса Marionette.View, имеют эту функциональность, в частности ItemView, CollectionView, CompositeView и LayoutView.

Marionette.ItemView.extend({
  onShow: function(){
    // react to when a view has been shown
  }
});

Распространенным случаем использования метода onShow является добавление дочерних представлений.

var LayoutView = Marionette.LayoutView.extend({
   regions: {
     Header: 'header',
     Section: 'section'
   },
   onShow: function() {
      this.showChildView('Header', new Header());
      this.showChildView('Section', new Section());
   }
});

Уничтожение представления

Представление реализует метод destroy, который автоматически вызывается менеджерами регионов. В рамках реализации выполняются следующие действия:

• вызов события onBeforeDestroy в представлении, если оно предоставлено
• вызов события onDestroy в представлении, если оно предоставлено
• отвязка всех пользовательских событий представления
• отвязка всех событий DOM
• удаление this.el из DOM
• отвязка всех событий listenTo
• возвращает представление.

Предоставив метод onDestroy в определении представления, вы можете выполнить пользовательский код для представления, который запускается после уничтожения и очистки представления. Метод onDestroy получит любые аргументы, с которыми был вызван destroy. Это позволяет обрабатывать любой дополнительный код очистки без необходимости переопределения метода destroy.

var MyView = Marionette.ItemView.extend({
  onDestroy: function(arg1, arg2){
    // custom cleanup or destroying code, here
  }
});

var v = new MyView();
v.destroy(arg1, arg2);

Представление onBeforeDestroy

При уничтожении представления метод onBeforeDestroy будет вызван, если он предоставлен, непосредственно перед уничтожением представления. Он получит любые аргументы, с которыми был вызван destroy.

Представление "attach" / событие onAttach

Каждое представление в Marionette имеет специальное событие "attach", которое срабатывает всякий раз, когда отображение представления в области вызывает его привязку к document. Как и другие события Marionette, оно также выполняет обратный вызов метода onAttach, если вы его указали. Событие "attach" отлично подходит для плагинов jQuery или другого логики, которая должна выполняться после привязки представления к document.

Событие attach срабатывает только тогда, когда представление становится дочерним элементом document. Если регион, в котором вы показываете представление, не является дочерним элементом document в момент вызова show, то событие attach не будет срабатывать, пока регион не станет дочерним элементом document.

Это событие уникально тем, что распространяется по дереву представлений. Например, при срабатывании события attach CollectionView, все его дочерние представления также получат событие attach. Кроме того, глубоко вложенные структуры представлений Layout View также получат событие attach в соответствующее время.

Подробнее об эффективных, глубоко вложенных структурах представлений см. в документации LayoutView.

Представление "before:attach" / событие onBeforeAttach

Это аналогично событию attach, описанному выше, но оно срабатывает непосредственно перед привязкой представления к документу.

Представление "dom:refresh" / событие onDomRefresh

Срабатывает после того, как представление было отрисовано, было показано в DOM через Marionette.Region и было переотрисовано.

Это событие/обратный вызов полезно для плагинов DOM-зависимых пользовательских интерфейсов, таких как jQueryUI или KendoUI.

Marionette.ItemView.extend({
  onDomRefresh: function(){
    // manipulate the `el` here. it's already
    // been rendered, and is full of the view's
    // HTML, ready to go.
  }
});

Дополнительную информацию об интеграции Marionette с KendoUI (также применимо к jQueryUI и другим наборам виджетов пользовательского интерфейса) см. в этой статье блога о KendoUI + Backbone.

View.events

Поскольку представления наследуются от класса представления Backbone, вы получаете преимущества от хеша событий.

На верху добавлен некоторый синтаксический сахар, чтобы добавить возможность использовать хэш ui.

var MyView = Marionette.ItemView.extend({
  // ...

  ui: {
    "cat": ".dog"
  },

  events: {
    "click @ui.cat": "bark" //is the same as "click .dog":
  }
});

View.triggers

Представления могут определять набор triggers в виде хеша, который преобразует событие DOM в вызов view.triggerMethod.

Левая часть хеша — это стандартная конфигурация события DOM Backbone.View, а правая часть хеша — это событие представления, которое вы хотите запустить из представления.

var MyView = Marionette.ItemView.extend({
  // ...

  triggers: {
    "click .do-something": "something:do:it"
  }
});

var view = new MyView();
view.render();

view.on("something:do:it", function(args){
  alert("I DID IT!");
});

// "click" the 'do-something' DOM element to
// demonstrate the DOM event conversion
view.$(".do-something").trigger("click");

В результате появляется всплывающее окно, которое говорит: "Я сделал это!" Триггеры также можно выполнить, используя атрибут 'on{EventName}'.

По умолчанию все триггеры останавливаются с помощью методов preventDefault и stopPropagation. Но вы можете вручную настроить триггеры, используя хеш вместо имени события. Пример ниже запускает событие и предотвращает стандартное поведение браузера с помощью метода preventDefault.

Marionette.CompositeView.extend({
  triggers: {
    "click .do-something": {
      event: "something:do:it",
      preventDefault: true, // this param is optional and will default to true
      stopPropagation: false
    }
  }
});

Вы также можете указать triggers как функцию, возвращающую хеш конфигураций триггеров

Marionette.CompositeView.extend({
  triggers: function(){
    return {
      "click .that-thing": "that:i:sent:you"
    };
  }
});

Ключи триггеров могут быть настроены для использования хэша ui.

Marionette.ItemView.extend({
  ui: {
     'monkey': '.guybrush'
  },
  triggers: {
    'click @ui.monkey': 'see:LeChuck' // equivalent of "click .guybrush"
  }
});

Триггеры работают со всеми классами представлений, которые наследуются от базового Marionette.View.

Аргументы обработчика триггеров

Обработчик события trigger получит единственный аргумент, который включает следующие элементы:

• view
• model
• collection

Эти свойства соответствуют свойствам view, model, и collection представления, которое сработало событие.

var MyView = Marionette.ItemView.extend({
  // ...

  triggers: {
    "click .do-something": "some:event"
  }
});

var view = new MyView();

view.on("some:event", function(args){
  args.view; // => the view instance that triggered the event
  args.model; // => the view.model, if one was set on the view
  args.collection; // => the view.collection, if one was set on the view
});

Доступ к этим свойствам позволяет повысить гибкость в обработке событий из нескольких представлений. Например, панель вкладок или виджет раскрытия/свертывания, такой как панель панелей, может запускать одно и то же событие из многих разных представлений и обрабатываться с помощью одной функции.

View.modelEvents и View.collectionEvents

Аналогично хешу events , представления могут указать конфигурационный хеш для коллекций и моделей. Левая сторона — событие модели или коллекции, а правая сторона — имя метода в представлении.

Marionette.CompositeView.extend({

  modelEvents: {
    "change:name": "nameChanged" // equivalent to view.listenTo(view.model, "change:name", view.nameChanged, view)
  },

  collectionEvents: {
    "add": "itemAdded" // equivalent to view.listenTo(view.collection, "add", view.itemAdded, view)
  },

  // ... event handler methods
  nameChanged: function(){ /* ... */ },
  itemAdded: function(){ /* ... */ },

})

Эти будут использовать безопасный для памяти listenTo, и будут устанавливать контекст (значение this) в обработчике в представлении. События привязываются во время создания экземпляра, и будет выброшено исключение, если обработчики в представлении не существуют.

modelEvents и collectionEvents будут привязываться и отвязываться с помощью вызовов методов delegateEvents и undelegateEvents Backbone.View. Это позволяет повторно использовать представление и повторно привязывать события модели и коллекции.

Несколько обратных вызовов

Несколько функций обратного вызова можно указать, разделив их пробелом.

Marionette.CompositeView.extend({

  modelEvents: {
    "change:name": "nameChanged thatThing"
  },

  nameChanged: function(){ },

  thatThing: function(){ },
});

Это работает как в modelEvents, так и в collectionEvents.

Обратные вызовы как функция

Одну функцию можно объявить непосредственно в строке вместо указания имени метода обратного вызова через строку.

Marionette.CompositeView.extend({

  modelEvents: {
    "change:name": function(){
      // handle the name changed event here
    }
  }

});

Это работает как в modelEvents, так и в collectionEvents.

Конфигурация события как функция

Функцию можно использовать для объявления конфигурации события, если эта функция возвращает хеш, соответствующий вышеуказанным параметрам конфигурации.

Marionette.CompositeView.extend({

  modelEvents: function(){
    return { "change:name": "someFunc" };
  }

});

Это работает как в modelEvents, так и в collectionEvents.

View.serializeModel

Метод serializeModel сериализует модель, переданную в качестве аргумента.

View.bindUIElements

В нескольких случаях вам нужно получить доступ к элементам пользовательского интерфейса внутри представления для извлечения их данных или манипулирования ими. Например, у вас есть определенный элемент div, который нужно показать/скрыть на основе некоторого состояния, или другой элемент пользовательского интерфейса, для которого вы хотите установить класс CSS. Вместо того, чтобы хранить селекторы jQuery в коде представления, вы можете определить хеш ui, который содержит отображение между именем элемента пользовательского интерфейса и его селектором jQuery. После этого вы можете получить к нему доступ с помощью this.ui.elementName. См. документацию ItemView для примеров.

Эта функциональность предоставляется с помощью метода bindUIElements. Поскольку представление не реализует метод render, то если вы напрямую наследуете от View, вам нужно вызвать этот метод из своего метода render. В ItemView и CompositeView это уже сделано.

View.mergeOptions

Предпочтительный способ управления параметрами представления — mergeOptions. Он принимает два аргумента: объект options и ключи для слияния непосредственно в экземпляр.

var ProfileView = Marionette.ItemView.extend({
  profileViewOptions: ['user', 'age'],

  initialize: function(options) {
    this.mergeOptions(options, this.profileViewOptions);

    console.log('The merged options are:', this.user, this.age);
  }
});

Дополнительная информация mergeOptions

View.getOption

Получите атрибут объекта напрямую из объекта или из this.options, при этом this.options имеет приоритет.

Дополнительная информация getOption

View.bindEntityEvents

Помогает привязать сущность backbone к методам целевого объекта. bindEntityEvents используется для поддержки modelEvents и collectionEvents.

Дополнительная информация bindEntityEvents

View.templateHelpers

Иногда шаблону представления требуется некоторая логика, и движок шаблонов не предоставляет удобного способа её реализации. Например, шаблоны Underscore не имеют механизма помощников, в то время как шаблоны Handlebars — имеют.

Атрибут templateHelpers может быть применён к любому объекту View, отображающему шаблон. При наличии этого атрибута его содержимое будет смешано с объектом данных, возвращаемым методом serializeData. Это позволит вам создавать вспомогательные методы, которые можно вызывать из ваших шаблонов. Это также хорошее место для добавления данных, которые не возвращаются из serializeData, таких как вычисленные значения.

Базовый пример

<script id="my-template" type="text/html">
  I <%= percent %>% think that <%= showMessage() %>
</script>

var MyView = Marionette.ItemView.extend({
  template: "#my-template",

  templateHelpers: function () {
    return {
      showMessage: function(){
        return this.name + " is the coolest!";
      },

      percent: this.model.get('decimal') * 100
    };
  }
});

var model = new Backbone.Model({
  name: "Marionette",
  decimal: 1
});
var view = new MyView({
  model: model
});

view.render(); //=> "I 100% think that Marionette is the coolest!";

Атрибут templateHelpers также может быть передан в качестве параметра конструктора для любого класса представления Marionette, поддерживающего помощники.

var MyView = Marionette.ItemView.extend({
  // ...
});

new MyView({
  templateHelpers: {
    doFoo: function(){ /* ... */ }
  }
});

Доступ к данным внутри помощников

Для доступа к данным из вспомогательных методов необходимо префикс данных, которые нужны, с this. Это даст вам все методы и атрибуты сериализованного объекта данных, включая другие вспомогательные методы.

templateHelpers: {
  something: function(){
    return "Do stuff with " + this.name + " because it's awesome.";
  }
}

Объект или функция как templateHelpers

Вы можете указать литерал объекта (как показано выше), ссылку на литерал объекта или функцию в качестве templateHelpers.

Если вы укажете функцию, функция будет вызвана с текущей инстанцией представления в качестве контекста функции. Функция должна вернуть объект, который можно смешать с данными для представления.

Marionette.ItemView.extend({
  templateHelpers: function(){
    return {
      foo: function(){ /* ... */ }
    }
  }
});

Изменение шаблона, отображаемого для представления

В некоторых случаях вам может потребоваться изменить шаблон, используемый для представления, на основе некоторой простой логики, например, значения определённого атрибута в модели представления. Для этого вы можете предоставить функцию getTemplate в своих представлениях и использовать её для возвращения необходимого шаблона.

var MyView = Marionette.ItemView.extend({
  getTemplate: function(){
    if (this.model.get("foo")){
      return "#some-template";
    } else {
      return "#a-different-template";
    }
  }
});

Это относится ко всем классам представлений.

Интерполяция UI

Marionette UI предоставляет удобный способ ссылки на элементы jQuery. Элементы UI также могут быть интерполированы в селекторы событий и областей.

В этом примере кнопка «Купить» ссылается на событие DOM, а раздел «Оформление заказа» — на селектор области.

var MyView = Marionette.ItemView.extend({

  ui: {
    buyButton: '.buy-button',
    checkoutSection: '.checkout-section'
  },

  events: {
    'click @ui.buyButton': 'onClickBuyButton'
  },

  regions: {
    checkoutSection: [email protected]'
  },

  onShow: function() {
    this.getRegion('checkoutSection').show(new CheckoutSection({
      model: this.checkoutModel
    }));
  }
});