New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

confusing example for can.Control template data passing #713

Closed
shcarrico opened this Issue Feb 4, 2014 · 5 comments

Comments

Projects
None yet
4 participants
@shcarrico
Contributor

shcarrico commented Feb 4, 2014

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

This comment has been minimized.

Show comment
Hide comment
@imjoshdean

imjoshdean Feb 4, 2014

Contributor

👍

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.

Contributor

imjoshdean commented Feb 4, 2014

👍

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

This comment has been minimized.

Show comment
Hide comment
@daffl

daffl Feb 4, 2014

Contributor

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.

Contributor

daffl commented Feb 4, 2014

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

This comment has been minimized.

Show comment
Hide comment
@shcarrico

shcarrico Feb 4, 2014

Contributor

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)

Contributor

shcarrico commented Feb 4, 2014

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

This comment has been minimized.

Show comment
Hide comment
@justinbmeyer

justinbmeyer Feb 4, 2014

Contributor

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.

Contributor

justinbmeyer commented Feb 4, 2014

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 daffl added this to the 2.0.6 milestone Feb 10, 2014

@shcarrico shcarrico self-assigned this Feb 19, 2014

daffl added a commit that referenced this issue Feb 25, 2014

Merge pull request #746 from bitovi/713/controlDocs
#713 cleanup can.Control, fixup contributing guide
@daffl

This comment has been minimized.

Show comment
Hide comment
@daffl

daffl Feb 25, 2014

Contributor

Closed via #746

Contributor

daffl commented Feb 25, 2014

Closed via #746

@daffl daffl closed this Feb 25, 2014

@shcarrico shcarrico removed their assignment Dec 10, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment