Marionette.CompositeView

A CompositeView extends from CollectionView to be used as a composite view for scenarios where it should represent both a branch and leaf in a tree structure, or for scenarios where a collection needs to be rendered within a wrapper template. By default the CompositeView will maintain a sorted collection's order in the DOM. This behavior can be disabled by specifying {sort: false} on initialize.

Please see the Marionette.CollectionView documentation for more information on available features and functionality.

Additionally, interactions with Marionette.Region will provide features such as onShow callbacks, etc. Please see the Region documentation for more information.

Пример использования: Деревовидный вид

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

Вы можете указать modelView для использования с моделью. Если вы не укажете, по умолчанию будет использоваться Marionette.ItemView.

var CompositeView = Marionette.CompositeView.extend({
  template: "#leaf-branch-template"
});

new CompositeView({
  model: someModel,
  collection: someCollection
});

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

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

• Модель составного представления template
• %%CODE_BLOCK_9%%% составного представления
• %%CODE_BLOCK_10%%% составного представления
• %%CODE_BLOCK_11%%% составного представления
• Рекурсивный по умолчанию
• Отображение модели и коллекции
• События и обратные вызовы
• Организация элементов пользовательского интерфейса
• modelEvents и collectionEvents

Модель составного представления template

При отрисовке CompositeView, model будет отрисовано с template, с которым настроено представление. Вы можете переопределить шаблон, передав его в качестве параметра конструктора:

new MyComp({
  template: "#some-template"
});

Параметр collection по умолчанию не передается в контекст шаблона. Если вашей template нужен доступ к коллекции, вам нужно передать ее через templateHelpers:

new MyComp({
  template: "#some-template",
  templateHelpers: function() {
    return { items: this.collection.toJSON() };
  }
})

%%CODE_BLOCK_21%%% составного представления

Каждый childView будет отрисовываться с помощью шаблона childView. Шаблон CompositeView отрисовывается, а шаблоны childView добавляются к нему.

var ChildView = Marionette.ItemView.extend({});

var CompView = Marionette.CompositeView.extend({
  childView: ChildView
});

%%CODE_BLOCK_25%%% составного представления

По умолчанию составное представление использует тот же метод attachHtml, что и представление коллекции. Это означает, что представление будет вызывать метод jQuery .append, чтобы переместить содержимое HTML из экземпляра child view в el представления коллекции.

Это обычно не очень полезно, так как составное представление обычно отрисовывает контейнерный элемент DOM, в котором должны быть размещены child view.

Например, если вы создаете представление таблицы и хотите добавить каждый элемент из коллекции в <tbody> таблицы, вы можете сделать это с помощью шаблона:

<script id="row-template" type="text/html">
  <td><%= someData %></td>
  <td><%= moreData %></td>
  <td><%= stuff %></td>
</script>

<script id="table-template" type="text/html">
  <table>
    <thead>
      <tr>
        <th>Some Column</th>
        <th>Another Column</th>
        <th>Still More</th>
      </tr>
    </thead>

    <!-- want to insert collection children, here -->
    <tbody></tbody>

    <tfoot>
      <tr>
        <td colspan="3">some footer information</td>
      </tr>
    </tfoot>
  </table>
</script>

Чтобы ваши childView-экземпляры отображались внутри <tbody> этой структуры таблицы, укажите childViewContainer в вашем представлении составного вида, как показано ниже:

var RowView = Marionette.ItemView.extend({
  tagName: "tr",
  template: "#row-template"
});

var TableView = Marionette.CompositeView.extend({
  childView: RowView,

  // specify a jQuery selector to put the `childView` instances into
  childViewContainer: "tbody",

  template: "#table-template"
});

Это поместит все childView экземпляры в тег <tbody> шаблона составного представления, правильно создавая структуру таблицы.

В качестве альтернативы вы можете указать функцию в качестве childViewContainer. Эта функция должна возвращать строку селектора jQuery или объект селектора jQuery.

var TableView = Marionette.CompositeView.extend({
  // ...

  childViewContainer: function(){
    return "#my-tbody"
  }
});

Использование функции позволяет использовать логику для селектора. Однако может быть возвращено только одно значение. После возврата первого значения оно будет кэшировано, и это значение будет использоваться на протяжении всего жизненного цикла этого экземпляра представления.

В качестве альтернативы, childViewContainer можно передать в опциях функции конструктора:

var myComp = new Marionette.CompositeView({
  // ...,

  childViewContainer: "#my-tbody"
});

%%CODE_BLOCK_40%%% составного представления

Иногда конфигурация childViewContainer недостаточна для указания места, где должен быть размещен экземпляр childView. В этом случае вы можете переопределить метод attachHtml своей реализацией.

Дополнительную информацию об этом методе см. в документации CollectionView.

Выбор контейнера childView составного представления

Метод getChildViewContainer получает второй параметр childView, который, при переопределении, позволяет точнее выбрать контейнер, предоставляя доступ к childView, который собирается быть добавлен в containerView возвращаемый getChildViewContainer.

Рекурсивный по умолчанию

Режим отображения по умолчанию для CompositeView предполагает иерархическую, рекурсивную структуру. Если вы настроили представление составного вида без указания childView, вы получите тот же класс представления составного вида для каждого элемента в коллекции.

Отображение модели и коллекции

Модель и коллекция представления составного вида будут перерисовываться в следующих случаях:

• При срабатывании события "reset" коллекции, она будет перерисована только внутри составного представления, а не шаблон обертки
• При добавлении модели в коллекцию (событие "add"), будет отрисовываться этот элемент в список
• При удалении модели из коллекции (событие "remove"), будет удален соответствующий элемент из отрисованного списка

Как и в случае с экземплярами представлений элементов, экземпляр составного представления передаётся в качестве третьего аргумента методу Renderer объекта render, что полезно при реализации пользовательских Renderer.

Как и в случае с CollectionView, CompositeView будет поддерживать порядок сортировки своих дочерних представлений из коллекции. Следует отметить, что всё представление будет перерисовываться, а не только дочерние элементы; это сделано для случаев, когда не используется childViewContainer.

События и обратные вызовы

В процессе отрисовки составного представления будут вызываться различные события. Эти события вызываются с помощью функции Marionette.triggerMethod, которая вызывает соответствующий метод "on{EventName}" в представлении.

• "before:render:template" / onBeforeRenderTemplate — перед отрисовкой model
• "render:template" / onRenderTemplate — после отрисовки model
• "before:render:collection" / onBeforeRenderCollection — перед отрисовкой коллекции моделей
• "render:collection" / onRenderCollection — после отрисовки коллекции моделей
• "before:render" / onBeforeRender — перед отрисовкой всего
• "render" / onRender — после отрисовки всего

Кроме того, после отрисовки составного представления будет вызван метод onRender. Вы можете реализовать его в своем представлении, чтобы обеспечить пользовательский код для обработки el представления после отрисовки:

Marionette.CompositeView.extend({
  onRender: function(){
    // do stuff here
  }
});

Организация элементов пользовательского интерфейса

Аналогично ItemView, вы можете организовать элементы пользовательского интерфейса внутри CompositeView, указав их в хеше UI. Следует отметить, что элементы, к которым можно получить доступ через этот хеш, — это элементы, которые напрямую отрисовываются шаблоном составного представления, а не те, которые принадлежат коллекции.

Элементы пользовательского интерфейса будут доступны сразу после отрисовки шаблона составного представления (и до отрисовки коллекции), что означает, что вы можете получить к ним доступ даже в методе onBeforeRender.

modelEvents и collectionEvents

CompositeViews могут напрямую подписываться на события моделей и коллекции декларативным способом:

Marionette.CompositeView.extend({
  modelEvents: {
    "change": "modelChanged"
  },

  collectionEvents: {
    "add": "modelAdded"
  }
});

Дополнительную информацию см. в документации Marionette.View.