Permalink
Browse files

Merge pull request #41 from dgeb/action-helpers

add "Handling Events with {{action}}" section
  • Loading branch information...
2 parents 697017a + a6aeac4 commit e1f816bdd103e0fcc465ecc1c6a1c79d49e0bae2 @ebryn ebryn committed Jan 28, 2012
Showing with 48 additions and 1 deletion.
  1. +48 −1 source/docs/handlebars.md
View
@@ -111,7 +111,10 @@ All of the features described in this guide are __bindings aware__. That means t
In order to know which part of your HTML to update when an underlying property changes, Handlebars will insert marker elements with a unique ID. If you look at your application while it's running, you might notice these extra elements:
```html
-My new car is <script id="metamorph-0-start" type="text/x-placeholder"></script>blue<script id="metamorph-0-end" type="text/x-placeholder"></script></span>.
+My new car is
+<script id="metamorph-0-start" type="text/x-placeholder"></script>
+blue
+<script id="metamorph-0-end" type="text/x-placeholder"></script>.
```
Because all Handlebars expressions are wrapped in these markers, make sure each HTML tag stays inside the same block. For example, you shouldn't do this:
@@ -308,6 +311,50 @@ dasherizing.
In this case, if the `isUrgent` property is true, the `urgent` class
will be added. If it is false, the `urgent` class will be removed.
+### Handling Events with {{action}}
+
+Use the `{{action}}` helper to attach a handler in your view class to an event triggered on an element.
+
+To attach an element's `click` event to the `edit()` handler in the current view:
+
+```javascript
+<a href="#" {{action "edit" on="click"}}>Edit</a>
+```
+
+Because the default event is `click`, this could be written more concisely as:
+
+```javascript
+<a href="#" {{action "edit"}}>Edit</a>
+```
+
+Although the view containing the `{{action}}` helper will be targeted by default, it is possible to target a different view:
+
+```javascript
+<a href="#" {{action "edit" target="parentView"}}>Edit</a>
+```
+
+The view's event handler can optionally accept an `eventObject`:
+
+```javascript
+App.ShowView = Ember.View.extend({
+ templateName: 'show',
+
+ edit: function(event) {
+ event.preventDefault();
+ this.set('isEditing', true);
+ }
+});
+```
+
+The template discussed above will produce an HTML element like this:
+
+```html
+<a href="#" data-ember-action="3">Edit</a>
+```
+
+Ember will delegate the event you specified to your target view's handler based upon the internally assigned `data-ember-action` id.
+
+
### Building a View Hierarchy
So far, we've discussed writing templates for a single view. However, as your application grows, you will often want to create a hierarchy of views to encapsulate different areas on the page. Each view is responsible for handling events and maintaining the properties needed to display it.

0 comments on commit e1f816b

Please sign in to comment.