Merge branch 'octane' into kategengler-patch-1

Author: rwjblue

config/environment.js

@@ -56,9 +56,13 @@ module.exports = function(environment) {
         }
       },
     ],
-    survey: {
-      link: 'https://emberjs.com/ember-community-survey-2019/',
-      title: '2019 Ember Community Survey'
+    infoBanner: {
+      content: `Thanks for taking the Octane preview for a test drive! Visit
+<a href="https://emberjs.com" target="_blank" rel="noopener">emberjs.com/octane</a>
+for more info and ways you can help out.
+These preview guides URLs are subject to change, so point your bookmarks at that landing page.
+If you are looking for the latest stable release of Ember, please instead visit
+<a href="https://guides.emberjs.com" target="_blank" rel="noopener">guides.emberjs.com</a>.`
     },
   };
 

guides/release/pages.yml

@@ -1,5 +1,8 @@
-- title: "What Is Ember"
-  url: "what-is-ember"
+- title: "Introduction"
+  url: 'index'
+  pages:
+    - title: "What Is Ember"
+      url: ""
 - title: "Getting Started"
   url: 'getting-started'
   pages:

guides/release/state-management/index.md

@@ -203,8 +203,7 @@ the application does. However, they are _more_ controlled than globals like
 `window` because:
 
 1. They can _only_ be injected into other Ember objects, not custom classes.
-2. They can _only_ be used in places where they are injected. Random functions
-   can't access a service for a one of change.
+2. They can _only_ be used in places where they are injected.
 
 This means that you can narrow down changes to state in services to a number of
 locations, and generally control the data flow more easily.

guides/release/templates/actions.md

@@ -8,64 +8,70 @@ the context of the template:
 
 ```javascript {data-filename=app/components/post/component.js}
 import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
 import { action } from '@ember/object';
 
 export default class Post extends Component {
+  @tracked isShowingBody;
+
   @action
   toggleBody() {
-    this.toggleProperty('isShowingBody');
+    this.isShowingBody = !this.isShowingBody;
   }
 }
 ```
 
-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`:
+You can then add this action to an element using the
+[`{{action}}`](https://api.emberjs.com/ember/release/classes/Ember.Templates.helpers/methods/action?anchor=action)
+helper:
 
 ```handlebars {data-filename=app/components/post/template.hbs}
 <h3>
-  <button onclick={{this.toggleBody}}>{{this.title}}</button>
+  <button {{action this.toggleBody}}>{{@title}}</button>
 </h3>
 
 {{#if this.isShowingBody}}
-  <p>{{this.body}}</p>
+  <p>{{@body}}</p>
 {{/if}}
 ```
 
-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/post/component.js}
-import Component from '@glimmer/component';
-import { action } from '@ember/object';
-
-export default class Post extends Component {
-  @action
-  toggleBody(event) {
-    event.preventDefault();
-    event.stopPropagation();
-    this.toggleProperty('isShowingBody');
-  }
-}
-```
-
+The `{{action}}` helper calls your action function when the element is
+clicked.
 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.
+yourself with the basics on this page first.
+
+Templates rendered for your application's routes are backed by controllers, so
+you may also see actions defined on a controller using the same `@action`
+decorator.
+
+<div class="cta">
+  <div class="cta-note">
+    <div class="cta-note-body">
+      <div class="cta-note-heading">Zoey says...</div>
+      <div class="cta-note-message">
+If this doesn't seem familiar you might be looking for documentation
+about Ember components and controller that use the older <code>.extend({</code> syntax.
+In those files you define actions in an object on the class then reference
+the action name with a string in the template.
+For more examples of that syntax see <a href="https://guides.emberjs.com/v3.6.0/templates/actions/">previous version of this Guide entry</a>.
+      </div>
+    </div>
+    <img src="/images/mascots/zoey.png" role="presentation" alt="Ember Mascot">
+  </div>
+</div>
 
 ## Action Parameters
 
-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)
+You can optionally pass arguments to the action
 helper. For example, if the `post` argument was passed:
 
 ```handlebars {data-filename=app/components/post/template.hbs}
 <p>
-  <button onclick={{action this.select this.post}}>
+  <button {{action this.select @post}}>
     ✓
   </button>
-  {{this.post.title}}
+  {{this.selectedPost.title}}
 </p>
 ```
 
@@ -87,71 +93,37 @@ export default class Post extends Component {
 }
 ```
 
-If you pass arguments like this, the event will be the _last_ argument that is
-passed to the handler:
+## Attaching Actions to Other Events
+
+Actions don't need to be triggered on click, in fact they can be attached
+to any event Ember is already listening to. For example this form will
+call the `updateText` action when submitted, but prevent the default
+form submission logic in the browser from running:
+
+```handlebars {data-filename=app/components/post/template.hbs}
+<form {{action this.createPost on="submit" preventDefault=true}}>
+  Post title: <Input @value={{this.title}} />
+</form>
+```
 
 ```javascript {data-filename=app/components/post/component.js}
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
 import { action } from '@ember/object';
 
 export default class Post extends Component {
-  @tracked selectedPost;
+  @tracked title;
 
   @action
-  select(post, event) {
-    event.preventDefault();
-    event.stopPropagation();
-    this.selectedPost = post;
-  }
-}
-```
-
-## Modifying the action's first parameter
-
-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={{this.bandDidChange}}
-/>
-```
-
-Let's assume we have an action handler that prints its first parameter:
-
-```javascript
-actions: {
-  bandDidChange(newValue) {
-    console.log(newValue);
+  createPost() {
+    // Do something with `this.title`
   }
 }
 ```
 
-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 {}`.
-
-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 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')
+Read about which events Ember is already listening to in
+[Handling Events: Event
+Names](../../components/handling-events/#toc_event-names).
 
 ## Attaching Actions to Non-Clickable Elements
 

guides/release/templates/binding-element-attributes.md

@@ -38,39 +38,41 @@ If `isAdministrator` is `false`, Handlebars will produce the following:
 <input type="checkbox">
 ```
 
-### Adding Other Attributes (Including Data Attributes)
+### Adding Attributes to Component Invocations
 
-By default, components only accept a limited number of HTML attributes.
-This means that some uncommon but perfectly valid attributes, such as `lang` or
-custom `data-*` attributes must be specifically enabled. For example, this template:
+Components in Ember can also accept attributes to be placed on an element
+which they render. A common use for this might be `lang` or `data-*`
+attributes. For example, this template passes those two attributes to
+a link component:
 
 ```handlebars
-{{#link-to "photos" data-toggle="dropdown" lang="es"}}Fotos{{/link-to}}
+<LinkTo @route="photos" data-toggle="dropdown" lang="es">
+  Fotos
+</LinkTo>
 ```
 
-Will render the following HTML:
+Which will render render the following HTML:
 
 ```html
-<a id="ember239" class="ember-view" href="#/photos">Fotos</a>
+<a href="/photos" data-toggle="dropdown" lang="es" id="ember239" class="ember-view">
+  Fotos
+</a>
 ```
 
-To enable support for these attributes, an attribute binding must be
-added for each specific attribute on the component.
-To do this, you can extend the appropriate components
-in your application. For example, for `link-to` you would create your own version
-of this component by extending
-[`Ember.LinkComponent`](https://www.emberjs.com/api/ember/release/classes/LinkComponent)
-
-```javascript {data-filename="app/components/link-to/component.js"}
-import LinkComponent from '@ember/routing/link-component';
-
-export default LinkComponent.extend({
-  attributeBindings: ['data-toggle', 'lang']
-});
-```
-
-Now the same template above renders the following HTML:
-
-```html
-<a id="ember239" class="ember-view" href="#/photos" data-toggle="dropdown" lang="es">Fotos</a>
-```
+Components can control which of their elements receive attributes.
+[Read more about how to customize a component's element](../../components/customizing-a-components-element/).
+
+<div class="cta">
+  <div class="cta-note">
+    <div class="cta-note-body">
+      <div class="cta-note-heading">Zoey says...</div>
+      <div class="cta-note-message">
+This API uses a recent and new feature in Ember: Angle bracket invocation
+syntax of an Ember component. If this doesn't look familiar you may be
+working with classic component invocation syntax (for example <code>{{link-to}}</code>).
+For more examples of ways to use components in a template, see the <a href="../../reference/syntax-conversion-guide">Syntax Conversion Guide</a> or the <a href="https://guides.emberjs.com/v3.6.0/templates/binding-element-attributes/">previous version of this Guide entry</a>.
+      </div>
+    </div>
+    <img src="/images/mascots/zoey.png" role="presentation" alt="Ember Mascot">
+  </div>
+</div>

guides/release/templates/built-in-helpers.md

@@ -1,4 +1,4 @@
-In the last section you learned how to write a helper. A helper is usually a
+A helper is usually a
 simple function that can be used in any template. Ember comes with a few helpers
 that can make developing your templates a bit easier. These helpers can allow
 you to be more dynamic in passing data to another helper or component.
@@ -168,10 +168,10 @@ when the `debugger;` breakpoint is hit, you can attempt to retrieve this value:
 {{/each}}
 ```
 
-You'll be able to get values from the current item:
+You'll be able to get the value of the current item:
 
 ```javascript
-> get('this.item.name')
+> get('item.name')
 ```
 
 You can also access the context of the view to make sure it is the object that

guides/release/templates/displaying-the-keys-in-an-object.md

@@ -2,18 +2,16 @@ If you need to display all of the keys or values of a JavaScript object in your
 you can use the [`{{#each-in}}`](https://www.emberjs.com/api/ember/release/classes/Ember.Templates.helpers/methods/if?anchor=each-in) helper:
 
 ```javascript {data-filename=/app/components/store-categories.js}
-import Component from '@ember/component';
+import Component from '@glimmer/component';
 
-export default Component.extend({
-  willRender() {
-    // Set the "categories" property to a JavaScript object
-    // with the category name as the key and the value a list
-    // of products.
-    this.set('categories', {
-      'Bourbons': ['Bulleit', 'Four Roses', 'Woodford Reserve'],
-      'Ryes': ['WhistlePig', 'High West']
-    });
-  }
+export default class extends Component {
+  // Set the "categories" property to a JavaScript object
+  // with the category name as the key and the value a list
+  // of products.
+  categories = {
+    'Bourbons': ['Bulleit', 'Four Roses', 'Woodford Reserve'],
+    'Ryes': ['WhistlePig', 'High West']
+  };
 });
 ```
 

guides/release/templates/handlebars-basics.md

@@ -129,9 +129,9 @@ about it! -->
 <!-- One way to use a component within a template -->
 <MyComponent />
 
-{{! Example of a comment that will be invisible, even
-if it contains things in {{curlyBraces}} }}
-
+{{! A Handlebars comment. These comments, unlike, HTML
+    comments, are not rendered in the DOM. They are
+    removed when the template is compiled. }}
 ```
 
 Component example:
@@ -150,7 +150,7 @@ A method named `plantATree` is called when the button is
 clicked. `plantATree` comes from the JavaScript file
 associated with the template, like a Component or
 Controller -->
-<button onclick={{action 'plantATree'}}>
+<button {{action 'plantATree'}}>
   More trees!
 <button>