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.
For example, if you're rendering a tree-view control, you may want to render a collection view with a model and template so that it will show a parent child with children in the tree.
You can specify a modelView
to use for the model. If you don't
specify one, it will default to the Marionette.ItemView
.
var CompositeView = Marionette.CompositeView.extend({
template: "#leaf-branch-template"
});
new CompositeView({
model: someModel,
collection: someCollection
});
For more examples, see my blog post on using the composite view.
template
childView
childViewContainer
attachHtml
template
When a CompositeView
is rendered, the model
will be rendered
with the template
that the view is configured with. You can
override the template by passing it in as a constructor option:
new MyComp({
template: "#some-template"
});
The collection
option is not passed to the template context by
default. If your template
needs access to the collection, you'll
need to pass it via templateHelpers
:
new MyComp({
template: "#some-template",
templateHelpers: function() {
return { items: this.collection.toJSON() };
}
})
childView
Each childView will be rendered using the childView
's template. The CompositeView
's
template is rendered and the childView's templates are added to this.
var ChildView = Marionette.ItemView.extend({});
var CompView = Marionette.CompositeView.extend({
childView: ChildView
});
childViewContainer
By default the composite view uses the same attachHtml
method that the
collection view provides. This means the view will call jQuery's .append
to move the HTML contents from the child view instance in to the collection
view's el
.
This is typically not very useful as a composite view will usually render a container DOM element in which the child views should be placed.
For example, if you are building a table view, and want to append each
child from the collection in to the <tbody>
of the table, you might
do this with a template:
<script id="row-template" type="text/html">
<td><%= someData %></td>
<td><%= moreData %></td>
<td><%= stuff %></td>
</script>
<script id="table-template" type="text/html"></script>
To get your childView instances to render within the <tbody>
of this
table structure, specify an childViewContainer
in your composite view,
like this:
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"
});
This will put all of the childView
instances into the <tbody>
tag of
the composite view's rendered template, correctly producing the table
structure.
Alternatively, you can specify a function as the childViewContainer
. This
function needs to return a jQuery selector string, or a jQuery selector
object.
var TableView = Marionette.CompositeView.extend({
// ...
childViewContainer: function(){
return "#my-tbody"
}
});
Using a function allows for logic to be used for the selector. However, only one value can be returned. Upon returning the first value, it will be cached and that value will be used for the remainder of that view instance' lifecycle.
Alternatively, the childViewContainer
can be supplied in the constructor
function options:
var myComp = new Marionette.CompositeView({
// ...,
childViewContainer: "#my-tbody"
});
attachHtml
Sometimes the childViewContainer
configuration is insufficient for
specifying where the childView
instance should be placed. If this is the
case, you can override the attachHtml
method with your own implementation.
For more information on this method, see the CollectionView's documentation.
childView
container selectionThe getChildViewContainer
method is passed a second childView
parameter which, when overridden, allows for a finer tuned container selection by being able to access the childView
which is about to be appended to the containerView
returned by getChildViewContainer
.
The default rendering mode for a CompositeView
assumes a
hierarchical, recursive structure. If you configure a composite
view without specifying an childView
, you'll get the same
composite view class rendered for each child in the collection.
The model and collection for the composite view will re-render themselves under the following conditions:
As with item view instances, the composite view instance is passed as the
third argument to the Renderer
object's render
method, which is
useful in custom Renderer
implementations.
As with CollectionView, CompositeView will maintain the sort order of its child views from the collection. It should be noted that the full view will re-render and not just the children, this is to cater for the use case where no childViewContainer
is used.
During the course of rendering a composite, several events will be triggered. These events are triggered with the Marionette.triggerMethod function, which calls a corresponding "on{EventName}" method on the view.
onBeforeRenderTemplate
- before the model
has been renderedonRenderTemplate
- after the model
has been renderedonBeforeRenderCollection
- before the collection of models is renderedonRenderCollection
- after the collection of models has been renderedonBeforeRender
- before anything has been renderedonRender
- after everything has been renderedAdditionally, after the composite view has been rendered, an
onRender
method will be called. You can implement this in
your view to provide custom code for dealing with the view's
el
after it has been rendered:
Marionette.CompositeView.extend({
onRender: function(){
// do stuff here
}
});
Similar to ItemView, you can organize the UI elements inside the
CompositeView by specifying them in the UI
hash. It should be
noted that the elements that can be accessed via this hash are
the elements that are directly rendered by the composite view
template, not those belonging to the collection.
The UI elements will be accessible as soon as the composite view
template is rendered (and before the collection is rendered),
which means you can even access them in the onBeforeRender
method.
CompositeViews can bind directly to model events and collection events in a declarative manner:
Marionette.CompositeView.extend({
modelEvents: {
"change": "modelChanged"
},
collectionEvents: {
"add": "modelAdded"
}
});
For more information, see the Marionette.View documentation.