Merge pull request ember-learn#574 from ember-learn/feat/octane/templates

[OCTANE][FEAT] Templates

Author: MelSumner

guides/release/pages.yml

@@ -19,8 +19,6 @@
   pages:
     - title: "Templating Basics"
       url: "handlebars-basics"
-    - title: "Built-in Helpers"
-      url: "built-in-helpers"
     - title: "Conditionals"
       url: "conditionals"
     - title: "Displaying a List of Items"
@@ -29,15 +27,10 @@
       url: "displaying-the-keys-in-an-object"
     - title: "Binding Element Attributes"
       url: "binding-element-attributes"
-    - title: "Links"
-      url: "links"
     - title: "Actions"
       url: "actions"
-    - title: "Input Helpers"
-      url: "input-helpers"
-    - title: "Development Helpers"
-      url: "development-helpers"
-      isAdvanced: true
+    - title: "Built-in Helpers"
+      url: "built-in-helpers"
     - title: "Writing Helpers"
       url: "writing-helpers"
       isAdvanced: true

guides/release/templates/actions.md

@@ -1,129 +1,126 @@
-Your app will often need a way to let users interact with controls that
-change application state. For example, imagine that you have a template
-that shows a blog title, and supports expanding the post to show the body.
+Your app will often need a way to let users interact with controls that change
+application state. For example, imagine that you have a template that shows a
+blog title, and supports expanding the post to show the body. This can be done
+with _actions_.
+
+Actions are methods that have been decorated with the `@action` decorator in
+the context of the template:
+
+```javascript {data-filename=app/components/post/component.js}
+import Component from '@glimmer/component';
+import { action } from '@ember/object';
+
+export default class Post extends Component {
+  @action
+  toggleBody() {
+    this.toggleProperty('isShowingBody');
+  }
+}
+```
 
-If you add the
-[`{{action}}`](https://www.emberjs.com/api/ember/release/classes/Ember.Templates.helpers/methods/action?anchor=action)
-helper to any HTML DOM element, when a user clicks the element, the named event
-will be sent to the template's corresponding component or controller.
+You can then add this action directly to an [_event handler
+property_](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers)
+on an element, like `onclick` or `onmouseenter`:
+
+```handlebars {data-filename=app/components/post/template.hbs}
+<h3>
+  <button onclick={{this.toggleBody}}>{{this.title}}</button>
+</h3>
 
-```handlebars {data-filename=app/templates/components/single-post.hbs}
-<h3><button {{action "toggleBody"}}>{{this.title}}</button></h3>
 {{#if this.isShowingBody}}
   <p>{{this.body}}</p>
 {{/if}}
 ```
 
-In the component or controller, you can then define what the action does within
-the `actions` hook:
+This assigns the action to the standard browser event handler for that function.
+It'll receive the event as its first parameter, and you can handle it like any
+standard JavaScript event:
 
-```javascript {data-filename=app/components/single-post.js}
-import Component from '@ember/component';
+```javascript {data-filename=app/components/post/component.js}
+import Component from '@glimmer/component';
+import { action } from '@ember/object';
 
-export default Component.extend({
-  actions: {
-    toggleBody() {
-      this.toggleProperty('isShowingBody');
-    }
+export default class Post extends Component {
+  @action
+  toggleBody(event) {
+    event.preventDefault();
+    event.stopPropagation();
+    this.toggleProperty('isShowingBody');
   }
-});
+}
 ```
 
-You will learn about more advanced usages in the Component's [Triggering Changes With Actions](../../components/triggering-changes-with-actions/) guide,
-but you should familiarize yourself with the following basics first.
+You will learn about more advanced usages in the Component's [Actions and
+Events](../../components/actions-and-events/) guide, but you should familiarize
+yourself with the following basics first.
 
 ## Action Parameters
 
-You can optionally pass arguments to the action handler. Any values
-passed to the `{{action}}` helper after the action name will be passed to
-the handler as arguments.
-
-For example, if the `post` argument was passed:
-
-```handlebars
-<p><button {{action "select" this.post}}>✓</button> {{this.post.title}}</p>
-```
-
-The `select` action handler would be called with a single argument
-containing the post model:
-
-```javascript {data-filename=app/components/single-post.js}
-import Component from '@ember/component';
-
-export default Component.extend({
-  actions: {
-    select(post) {
-      console.log(post.get('title'));
-    }
-  }
-});
-```
-
-## Specifying the Type of Event
-
-By default, the
+You can optionally pass arguments to the action with the
 [`{{action}}`](https://www.emberjs.com/api/ember/release/classes/Ember.Templates.helpers/methods/action?anchor=action)
-helper listens for click events and triggers the action when the user clicks
-on the element.
+helper. For example, if the `post` argument was passed:
 
-You can specify an alternative event by using the `on` option.
-
-```handlebars
+```handlebars {data-filename=app/components/post/template.hbs}
 <p>
-  <button {{action "select" this.post on="mouseUp"}}>✓</button>
+  <button onclick={{action this.select this.post}}>
+    ✓
+  </button>
   {{this.post.title}}
 </p>
 ```
 
-You should use the <code>camelCased</code> event names, so two-word names like `keypress`
-become `keyPress`.
+The `select` action handler would be called with a single argument
+containing the post model:
 
-## Allowing Modifier Keys
+```javascript {data-filename=app/components/post/component.js}
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { action } from '@ember/object';
 
-By default, the `{{action}}` helper will ignore click events with
-pressed modifier keys. You can supply an `allowedKeys` option
-to specify which keys should not be ignored.
+export default class Post extends Component {
+  @tracked selectedPost;
 
-```handlebars
-<button {{action "anActionName" allowedKeys="alt"}}>
-  click me
-</button>
+  @action
+  select(post) {
+    this.selectedPost = post;
+  }
+}
 ```
 
-This way the `{{action}}` will fire when clicking with the alt key
-pressed down.
-
-## Allowing Default Browser Action
+If you pass arguments like this, the event will be the _last_ argument that is
+passed to the handler:
 
-By default, the `{{action}}` helper prevents the default browser action of the
-DOM event. If you want to allow the browser action, you can stop Ember from
-preventing it.
+```javascript {data-filename=app/components/post/component.js}
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { action } from '@ember/object';
 
-For example, if you have a normal link tag and want the link to bring the user
-to another page in addition to triggering an ember action when clicked, you can
-use `preventDefault=false`:
+export default class Post extends Component {
+  @tracked selectedPost;
 
-```handlebars
-<a href="newPage.htm" {{action "logClick" preventDefault=false}}>Go</a>
+  @action
+  select(post, event) {
+    event.preventDefault();
+    event.stopPropagation();
+    this.selectedPost = post;
+  }
+}
 ```
 
-With `preventDefault=false` omitted, if the user clicked on the link, Ember.js
-will trigger the action, but the user will remain on the current page.
-
-With `preventDefault=false` present, if the user clicked on the link, Ember.js
-will trigger the action *and* the user will be directed to the new page.
-
 ## Modifying the action's first parameter
 
-If a `value` option for the
-[`{{action}}`](https://www.emberjs.com/api/ember/release/classes/Ember.Templates.helpers/methods/action?anchor=action)
-helper is specified, its value will be considered a property path that will
-be read off of the first parameter of the action. This comes very handy with
-event listeners and enables to work with one-way bindings.
+If a `value` option for the `{{action}}` helper is specified, its value will be
+considered a property path that will be read off of the first parameter of the
+action. This comes very handy with event listeners and enables to work with
+one-way bindings.
 
 ```handlebars
 <label>What's your favorite band?</label>
-<input type="text" value={{this.favoriteBand}} onblur={{action "bandDidChange"}} />
+<input
+  type="text"
+  value={{this.favoriteBand}}
+  onblur={{this.bandDidChange}}
+/>
 ```
 
 Let's assume we have an action handler that prints its first parameter:
@@ -137,38 +134,42 @@ actions: {
 ```
 
 By default, the action handler receives the first parameter of the event
-listener, the event object the browser passes to the handler, so
-`bandDidChange` prints `Event {}`.
+listener, the event object the browser passes to the handler, so `bandDidChange`
+prints `Event {}`.
 
 Using the `value` option modifies that behavior by extracting that property from
 the event object:
 
 ```handlebars
 <label>What's your favorite band?</label>
-<input type="text" value={{this.favoriteBand}} onblur={{action "bandDidChange" value="target.value"}} />
+<input
+  type="text"
+  value={{this.favoriteBand}}
+  onblur={{action this.bandDidChange value="target.value"}}
+/>
 ```
 
 The `newValue` parameter thus becomes the `target.value` property of the event
-object, which is the value of the input field the user typed. (e.g 'Foo Fighters')
+object, which is the value of the input field the user typed. (e.g 'Foo
+Fighters')
 
 ## Attaching Actions to Non-Clickable Elements
 
-Note that actions may be attached to any element of the DOM, but not all
-respond to the `click` event. For example, if an action is attached to an `a`
-link without an `href` attribute, or to a `div`, some browsers won't execute
-the associated function. If it's really needed to define actions over such
-elements, a CSS workaround exists to make them clickable, `cursor: pointer`.
-For example:
+Note that actions may be attached to any element of the DOM, but not all respond
+to the `click` event. For example, if an action is attached to an `a` link
+without an `href` attribute, or to a `div`, some browsers won't execute the
+associated function. If it's really needed to define actions over such elements,
+a CSS workaround exists to make them clickable, `cursor: pointer`. For example:
 
 ```css
 [data-ember-action]:not(:disabled) {
   cursor: pointer;
 }
 ```
 
-Keep in mind that even with this workaround in place, the `click` event will
-not automatically trigger via keyboard driven `click` equivalents (such as
-the `enter` key when focused). Browsers will trigger this on clickable
-elements only by default. This also doesn't make an element accessible to
-users of assistive technology. You will need to add additional things like
-`role` and/or `tabindex` to make this accessible for your users.
+Keep in mind that even with this workaround in place, the `click` event will not
+automatically trigger via keyboard driven `click` equivalents (such as the
+`enter` key when focused). Browsers will trigger this on clickable elements only
+by default. This also doesn't make an element accessible to users of assistive
+technology. You will need to add additional things like `role` and/or `tabindex`
+to make this accessible for your users.