viewModel

Use

can.Component's viewModel property is used to define an object, typically an instance of a can.Map, that will be used to render the component's template. This is most easily understood with an example. The following component shows the current page number based off a limit and offset value:

can.Component.extend({
  tag: "my-paginate",
  viewModel: {
    offset: 0,
    limit: 20,
    page: function(){
      return Math.floor(this.attr('offset') / this.attr('limit')) + 1;
    }
  },
  template: "Page {{page}}."
})

If this component HTML was inserted into the page like:

var template = can.mustache("<my-paginate></my-paginate>")
$("body").append(template())

It would result in:

<my-paginate>Page 1</my-paginate>

This is because the provided viewModel object is used to extend a can.Map like:

CustomMap = can.Map.extend({
  offset: 0,
  limit: 20,
  page: function(){
    return Math.floor(this.attr('offset') / this.attr('limit')) + 1;
  }
})

Any primitives found on a can.Map's prototype (ex: offset: 0) are used as default values.

Next, a new instance of CustomMap is created with the attribute data within <my-paginate> (in this case there is none) like:

componentData = new CustomMap(attrs);

And finally, that data is added to the parentviewModel of the component, used to render the component's template, and inserted into the element:

var newviewModel = parentviewModel.add(componentData),
    result = can.mustache("Page {{page}}.")(newviewModel);
$(element).html(result);

Values passed from attributes

Values can be "passed" into the viewModel of a component, similar to passing arguments into a function. By default, custom tag attributes (other than class and id) are looked up in the parent viewModel and set as observable values on the can.Map instance.

Values passed in this way are passed similar to function arguments that are "pass by reference" because they are crossbound to the property in the parent viewModel. Changes in the parent viewModel property that is passed in trigger changes in this component's viewModel property, and likewise, changes in the component's viewModel property trigger a change in the parent viewModel property.

As mentioned in the deprecation warning above, using can.stache, values are passed into components like this:

<my-paginate offset='{index}' limit='{size}'></my-paginate>

But using can.mustache, values are passed like this:

<my-paginate offset='index' limit='size'></my-paginate>

The rest of the examples in this section show can.mustache syntax (which will change to match can.stache in 3.0).

Note that using double brackets would instead render the string version of the value, and pass by value rather than by reference:

<my-paginate offset='{{index}}' limit='{{size}}'></my-paginate>

The above would create an offset and limit property on the component that are initialized to whatever index and size are, NOT cross-bind the offset and limit properties to the index and size.

The following component requires an offset and limit:

can.Component.extend({
  tag: "my-paginate",
  viewModel: {
    page: function(){
      return Math.floor(this.attr('offset') / this.attr('limit')) + 1;
    }
  },
  template: "Page {{page}}."
});

If <my-paginate>'s source html is rendered like:

var template = can.mustache("<my-paginate offset='index' limit='size'></my-paginate>");

var pageInfo = new can.Map({
  index: 0,
  size: 20
});

$("body").append( template( pageInfo ) );

... pageInfo's index and size are set as the component's offset and limit attributes. If we were to change the value of pageInfo's index like:

pageInfo.attr("index",20)

... the component's offset value will change and its template will update to:

<my-paginate>Page 1</my-paginate>

Using attribute values

You can also pass a literal string value of the attribute instead of the attribute's value looked up in the parent viewModel (similar to pass by value).

To do this in can.stache, simply pass any value not wrapped in single brackets, and the viewModel property will be initialized to this string value:

<my-tag title="hello"></my-tag>

The above will create a title property in the component's viewModel, which has a string hello. If instead hello was wrapped with brackets like {hello}, a hello property would be looked up in the parent's viewModel.

To do this in can.mustache, pass a value like in can.stache, and set the corresponding viewModel property in the component to @. For example:

can.Component.extend({
  tag: "my-tag",
  viewModel: {
    title: "@"
  },
  template: "<h1>{{title}}</h1>"
});

With source HTML like:

<my-tag title="hello"></my-tag>

Results in:

<my-tag><h1>hello</h1></my-tag>

In 3.0, can.mustache syntax (requiring "@") will change to can.stache's (not requiring "@").

If the tag's title attribute is changed, it updates the viewModel property automatically. This can be seen in the following example:

Clicking the Change title button sets a <panel> element's title attribute like:

$("#out").on("click", "button", function(){
  $("panel:first").attr("title", "Users")
  $(this).remove();
});

Calling methods on viewModel from events within the template

Using html attributes like can-EVENT-METHOD, you can directly call a viewModel method from a template. For example, we can make <my-paginate> elements include a next button that calls the viewModel's next method like:

can.Component.extend({
  tag: "my-paginate",
  viewModel: {
    offset: 0,
    limit: 20,
    next: function(context, el, ev){
      this.attr("offset", this.offset + this.limit);
    },
    page: function(){
      return Math.floor(this.attr('offset') / this.attr('limit')) + 1;
    }
  },
  template: "Page {{page}} <button can-click='next'>Next</button>"
})

viewModel methods get called back with the current context, the element that you are listening to and the event that triggered the callback.