scope

Use

can.Component's scope 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",
  scope: {
    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.view.mustache("<my-paginate></my-paginate>")
$("body").append(template())

It would result in:

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

This is because the provided scope 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 parentScope of the component, used to render the component's template, and inserted into the element:

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

Values passed from attributes

By default, custom tag attributes other than "class" and "id" are looked up in the parent scope and set as observable values on the can.Map instance.

For example, the following component requires an offset and limit:

can.Component.extend({
  tag: "my-paginate",
  scope: {
    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.view.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 it's template will update to:

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

Using attribute values

If you want the literal string value of the attribute instead of the attribute's value looked up in the parent scope, you can set scope properties to have values of "@". For example:

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

With source HTML like:

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

Results in:

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

Calling methods on scope from events within the template

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

can.Component.extend({
  tag: "my-paginate",
  scope: {
    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>"
})

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