confusing example for can.Control template data passing

[shcarrico]

In the documentation for can.Control, we use sugary syntax to render the template, ie self.element.html('todos.ejs', new Todo.List({}) ) and self.element.html( self.options.view, todos ).

While this is more terse, it is confusing for beginners to the framework. For one, it appears we are passing a data object to what is (in most cases) $().html(), which would indicate we have changed the API to this library method. Secondly, it is hard to understand that the data object is being provided to the template via can.view, not to the HTML rendering method.

I propose we modify these examples to show the template passing through can.view, and add an additional syntax guide for templates used in a steal context. This would result in the following modifications of the above items
self.element.html( can.view( 'todos.ejs', new Todo.List([]) )
self element.html( can.view( self.options.template, todos) )

for steal, we should show a steal wrapper pulling a .mustache file, and resulting in 'template' being passed, ie

steal('./template.mustache',function(template){
  return can.Control.extend({
    init : function(){
      self.element.html( template() )
    }
  });
});

We can provide an example of the shortened syntax as well, but as an optimization rather than the default example.

[imjoshdean]

👍

By all accounts, I have always done can.view(template, options) and occasionally have done templateFunction(options). Also when I've done training, I also show the former more often. If this is how we normally go about things (without steal) then it should probably be the showing it in the examples, especially since it is the first way people learn how to use can.view.

It's a few more lines of code, but less confusing with can.view documentation as supplemental.

[daffl]

self.element.html('todos.ejs', new Todo.List({}) ) works only with the jQuery modifiers plugin and therefore indeed shouldn't be shown in the can.Control documentation. I bet this is a remainder from JMVC 3.2 where it was included by default.

[shcarrico]

I am curious if this plugin is being included by default again.. My project is allowing this syntax without explicitly pulling the plugin (we just steal can/util/jquery)

[justinbmeyer]

When you steal "can", you get what's in can/can.js:

steal('can/util', 'can/control/route', 'can/model', 
    'can/view/mustache', 'can/component', function(can) {
    return can;
});

So most likely something in your app is stealing the modifiers plugin.

[daffl]

Closed via #746