From 4dbfdd997cdbdb922ac5c905433c38f1d640a973 Mon Sep 17 00:00:00 2001 From: Mike Harris Date: Tue, 19 Mar 2013 16:38:40 -0400 Subject: [PATCH 1/3] First cut at a Templates/RenderingHelpers page in the Guides. Huge thanks to darthdeus, author of this post: http://darthdeus.github.com/blog/2013/02/10/render-control-partial-view/ --- data/guides.yml | 2 + source/guides/templates/rendering-helpers.md | 93 ++++++++++++++++++++ 2 files changed, 95 insertions(+) create mode 100644 source/guides/templates/rendering-helpers.md diff --git a/data/guides.yml b/data/guides.yml index ee32d9e48d..62951679af 100644 --- a/data/guides.yml +++ b/data/guides.yml @@ -39,6 +39,8 @@ Templates: url: "templates/links" - title: "Actions" url: "templates/actions" + - title: "Rendering Helpers" + url: "templates/rendering-helpers" #- title: "Keywords" #url: "templates/keywords" - title: "Writing Helpers" diff --git a/source/guides/templates/rendering-helpers.md b/source/guides/templates/rendering-helpers.md new file mode 100644 index 0000000000..58a41cec85 --- /dev/null +++ b/source/guides/templates/rendering-helpers.md @@ -0,0 +1,93 @@ +## Rendering Helpers + +Ember provides several helpers that allow you to render other views and templates in different ways. + +### The `{{partial}}` Helper + +`{{partial}}` takes the template to be rendered as an argument, and renders that template in place. + +`{{partial}}` does not change context or scope. It simply drops the given template into place with the current scope. + +```handlebars + + + +``` + +Note: in cases where you may have used `{{template}}` in the past, you should likely use `{{partial}}` instead. + +### The `{{view}}` Helper + +This helper works like the partial helper, except instead of providing a template to be rendered within the current template, you provide a view class. The view controls what template is rendered. + +```handlebars + + + +``` + +For more information, see [Inserting Views in Templates](/guides/views/inserting-views-in-templates) + +### The `{{render}}` Helper + +`{{render}}` takes two parameters: + +* The first parameter describes the context to be setup +* The optional second parameter is a model, which will be passed to the controller if provided + +`{{render}}` does several things: + +* Gets the singleton instance of the corresponding controller +* Renders the named template using this controller +* Sets the model of the corresponding controller + +Modifying the post / author example slightly: + +```handlebars + + + +``` + +```javascript +App.AuthorController = Ember.ObjectController.extend({ + postCount: function() { + // some logic + }.property("model") +}) +``` + +In this example, render will: + +* Gets an instance of App.AuthorView if that class exists, otherwise uses a default generated view +* Use the corresponding template (in this case the default of "author") +* Get (or generate) the singleton instance of AuthorController +* Set the AuthorController's model to the 2nd argument passed to render, here the author field on the post +* Render the template in place, with the context created in the previous steps. + +Note: `{{render}}` cannot be called multiple times for the same route. For that you'll need `{{control}}`. + +### The `{{control}}` Helper + +`{{control}}` works like render, except it uses a new controller instance for every call, instead of reusing the singleton controller. + +This helper is currently under heavy development, and will likely change soon. \ No newline at end of file From 4eef6f31bd7a82595b1ec47232c85d111bd56630 Mon Sep 17 00:00:00 2001 From: Mike Harris Date: Mon, 25 Mar 2013 12:36:09 -0400 Subject: [PATCH 2/3] Made some changes and additions for Guides/Templates/RenderingHelpers. I made some of the changes recommended by fivetanley. I added some more example code. I hesitate to add too much, as at some point it turns from a guide into an example app. Added some more notes about {{render}}, including a brief comparison of {{outlet}} and {{render}}, which I hope is not confusing. Added a comparison table of the three main rendering helpers. --- source/guides/templates/rendering-helpers.md | 134 ++++++++++++++++++- 1 file changed, 129 insertions(+), 5 deletions(-) diff --git a/source/guides/templates/rendering-helpers.md b/source/guides/templates/rendering-helpers.md index 58a41cec85..b2d7d2538b 100644 --- a/source/guides/templates/rendering-helpers.md +++ b/source/guides/templates/rendering-helpers.md @@ -20,24 +20,63 @@ Ember provides several helpers that allow you to render other views and template ``` +```html +
+

Why You Should Use Ember.JS

+
Because it's awesome!
+ Written by Yehuda Katz +
+``` + Note: in cases where you may have used `{{template}}` in the past, you should likely use `{{partial}}` instead. ### The `{{view}}` Helper This helper works like the partial helper, except instead of providing a template to be rendered within the current template, you provide a view class. The view controls what template is rendered. +```javascript +App.AuthorView = Ember.View.extend({ + // We are setting templateName manually here to the default value + templateName: "author", + + // A fullName property should probably go on App.Author, + // but we're doing it here for the example + fullName: (function() { + return this.get("author").get("firstName") + " " + this.get("author").get("lastName"); + }).property("firstName","lastName") +}) +``` + ```handlebars ``` +```html +
+

Why You Should Use Ember.JS

+
Because it's awesome!
+ Written by Yehuda Katz +
+``` + +When using `{{partial "author"}}`: + +* No instance of App.AuthorView will be created +* The given template will be rendered + +When using `{{view App.AuthorView}}`: + +* An instance of App.AuthorView will be created +* It will be rendered here, using the template associated with that view (the default template being "author") + For more information, see [Inserting Views in Templates](/guides/views/inserting-views-in-templates) ### The `{{render}}` Helper @@ -71,8 +110,8 @@ Modifying the post / author example slightly: ```javascript App.AuthorController = Ember.ObjectController.extend({ postCount: function() { - // some logic - }.property("model") + return App.Post.countForAuthor(this.get("model")); + }.property("model","App.Post.@each.author") }) ``` @@ -84,10 +123,95 @@ In this example, render will: * Set the AuthorController's model to the 2nd argument passed to render, here the author field on the post * Render the template in place, with the context created in the previous steps. +`{{render}}` does not require the presence of a matching route. + +`{{render}}` is similar to `{{outlet}}`. Both tell Ember to devote this portion of the page to something. + +`{{outlet}}`: The router determines the route and sets up the appropriate controllers/views/models. +`{{render}}`: You specify (directly and indirectly) the appropriate controllers/views/models. + + + Note: `{{render}}` cannot be called multiple times for the same route. For that you'll need `{{control}}`. ### The `{{control}}` Helper `{{control}}` works like render, except it uses a new controller instance for every call, instead of reusing the singleton controller. -This helper is currently under heavy development, and will likely change soon. \ No newline at end of file +This helper is currently under heavy development, and will likely change soon. + +### Comparison Table + +#### General + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HelperTemplateModelViewController
{{partial}}Specified TemplateCurrent ModelCurrent ViewCurrent Controller
{{view}}View's TemplateCurrent ModelSpecified ViewCurrent Controller
{{render}}View's TemplateSpecified ModelSpecified ViewSpecified Controller
+ +#### Specific + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HelperTemplateModelViewController
{{partial author}}author.hbsPostApp.PostViewApp.PostController
{{view App.AuthorView}}author.hbsPostApp.AuthorViewApp.PostController
{{render author author}}author.hbsAuthorApp.AuthorViewApp.AuthorController
\ No newline at end of file From 6eaa14eaf4bcebb04298d2befdd38c35013ffaff Mon Sep 17 00:00:00 2001 From: Mike Harris Date: Sat, 13 Apr 2013 15:31:41 -0400 Subject: [PATCH 3/3] Renamed templates/rendering-helpers to rendering-with-helpers --- data/guides.yml | 4 ++-- .../{rendering-helpers.md => rendering-with-helpers.md} | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) rename source/guides/templates/{rendering-helpers.md => rendering-with-helpers.md} (99%) diff --git a/data/guides.yml b/data/guides.yml index 62951679af..a56b1e3db9 100644 --- a/data/guides.yml +++ b/data/guides.yml @@ -39,8 +39,8 @@ Templates: url: "templates/links" - title: "Actions" url: "templates/actions" - - title: "Rendering Helpers" - url: "templates/rendering-helpers" + - title: "Rendering with Helpers" + url: "templates/rendering-with-helpers" #- title: "Keywords" #url: "templates/keywords" - title: "Writing Helpers" diff --git a/source/guides/templates/rendering-helpers.md b/source/guides/templates/rendering-with-helpers.md similarity index 99% rename from source/guides/templates/rendering-helpers.md rename to source/guides/templates/rendering-with-helpers.md index b2d7d2538b..c0e19ea2e2 100644 --- a/source/guides/templates/rendering-helpers.md +++ b/source/guides/templates/rendering-with-helpers.md @@ -1,4 +1,4 @@ -## Rendering Helpers +## Rendering with Helpers Ember provides several helpers that allow you to render other views and templates in different ways.