From 7779a68857a59178fdc08a9b4d37112fca33bc3f Mon Sep 17 00:00:00 2001
From: Jen Weber
Date: Mon, 18 Feb 2019 17:25:37 -0500
Subject: [PATCH 01/14] Rough draft of new Templates intro
---
guides/release/templates/handlebars-basics.md | 192 ++++++++++++++----
1 file changed, 155 insertions(+), 37 deletions(-)
diff --git a/guides/release/templates/handlebars-basics.md b/guides/release/templates/handlebars-basics.md
index ca8ca43829..d5814985b3 100644
--- a/guides/release/templates/handlebars-basics.md
+++ b/guides/release/templates/handlebars-basics.md
@@ -1,85 +1,203 @@
-Ember uses a templating language based on [Handlebars templating library](http://www.handlebarsjs.com) to power your app's user interface.
-Ember templates contain static HTML and dynamic content inside Handlebars expressions, which are invoked with double curly braces: `{{}}`.
+Templates are the home for what the user sees, like forms, buttons, links, and headings.
+In this section of the Guides, you will learn about where to write HTML markup, plus how to add interaction, dynamically changing content, styling, and more. If you want to learn in a step-by-step way, you should begin your journey in the [Tutorial]() instead.
-### Displaying Properties
+## Writing plain HTML
-Templates are backed with a context. A context is an object from which
-Handlebars expressions read their properties. In Ember this is often a component. For templates rendered by a route (like `application.hbs`), the context is a controller.
+Ember templates have some superpowers, but let's start with regular HTML. For any file in an Ember app that has an extension ending in `.hbs`, you can write HTML markup in it as if it was an `.html` file. HTML is the language that browsers understand for laying out content on a web page. `.hbs` stands for Handlebars, the name of a tool that lets you write more than just HTML in your templates.
-For example, this `application.hbs` template will render a first and last name:
+For example, every Ember app has a file called `application.hbs`. You can write regular HTML markup there or in any other `hbs` file:
-```handlebars {data-filename=app/templates/application.hbs}
-Hello, {{this.firstName}} {{this.lastName}}!
+```hbs {data-filename=app/templates/application.hbs data-update=false}
+
Starting simple
+
+ This is regular html markup inside an hbs file
+
+```
+
+If you make a mistake like forgetting to close a tag or missing a quotation mark, you will see some errors when you run the app with `ember serve`. However, reading the error message on the page or in your browser's developer console will get you going again right away.
+
+## Types of Templates
+
+There are two main types of Templates: Route Templates and Component Templates.
+
+A Route Template determines what is shown when someone visits a particular url, like `https://guides.emberjs.com/some-route`. A Component Template has bits of content that can be reused in multiple places throughout the app, like buttons or forms.
+
+The best way to tell if a Template is part of a Route or Component is to look at the filepath. If you look at an existing app, you will see Templates in many different places in the app folder structure! This is to help the app stay organized as it grows from one to one hundred Templates.
+
+## Making new Templates
+
+New templates should be made using the [Ember CLI](https://cli.emberjs.com). It helps ensure that the files go in the right place in the app folder structure, and that they follow the right file naming conventions. If you have never used the Ember CLI before, it is recommended to do the [Tutorial]().
+
+For example, either of these commands will generate `.hbs` Template files (and other things!) in your app:
+
+```sh
+ember generate component my-component-name
+ember generate route my-route-name
+```
+
+## Template restrictions
+
+A typical, modern web app is made of dozens of files that have to all be combined together into something the browser can understand. Ember does this work for you with zero configuration, but as a result, there are some rules to follow when it comes to adding assets into your HTML.
+
+You cannot use script tags directly within a template, and should use [actions]() or [Route Lifecycle Hooks]() to make your app responsive to user interactions and new data. If you are working with a non-Ember JavaScript library and need to use a `js` file from it, see the Guide section [Addons and Dependencies]().
+
+Similarly, you should not add links to CSS Stylesheets within the `hbs` file. Style rules should go in the `app/styles` directory instead. `app/styles/app.css` is included in your app's build by default. For CSS files within the styles directory, you can create multiple stylesheets and use regular CSS APIs like `import` to link them together. If you want to incorporate CSS from an npm package or similar, see [Addons and Dependencies]() for instructions.
+
+## What is `index.html` for?
+
+If HTML markup goes in `hbs` Templates, what is `index.html` for?
+
+The `index.html` file is the entry point for an app. It is not a Template, but rather it is where all the Templates, stylesheets, and JavaScript come together into something the browser can understand.
+
+When you are first getting started in Ember, you will not need to make any changes to `index.html`. There's no need to add any links to other Ember app pages, stylesheets, or scripts in here by hand, since Ember's built-in tools do the work for you.
+
+The most common customizations developers make to `index.html` are when they use a CDN to load assets like fonts or stylesheets. Here's an example:
+
+```html {data-filename=app/index.html}
+
```
-The `firstName` and `lastName` properties are read from the
-context (the application controller in this case), and rendered inside the
-`` HTML tag.
+## Understanding a Template's context
-To provide a `firstName` and `lastName` to the above template, properties
-must be added to the application controller. If you are following along with
-an Ember CLI application, you may need to create this file:
+A Template only has access to the data it has been given. This is referred to as the Template's "context." For example, to display a property inside a Route's Template, it should be defined in a Controller:
```javascript {data-filename=app/controllers/application.js}
import Controller from '@ember/controller';
export default Controller.extend({
firstName: 'Trek',
- lastName: 'Glowacki'
+ lastName: 'Glowacki',
+ favoriteFramework: 'Ember'
});
```
+The attributes like `firstName` can be used in the template
+by putting them inside of curly braces, plus the word
+`this`:
+
+```handlebars {data-filename=app/templates/application.hbs}
+Hello, {{this.firstName}} {{this.lastName}}!
+```
+
The above template and controller render as the following HTML:
```html
Hello, Trek Glowacki!
```
-Remember that `{{this.firstName}}` and `{{this.lastName}}` are bound data. That means
-if the value of one of those properties changes, the DOM will be updated
-automatically.
+If you use JavaScript to change the values of `firstName` or `lastName` in the Controller, what the user sees will be automatically updated! In Ember, this is referred to as "data binding."
-As an application grows in size, it will have many templates backed by
-controllers and components.
+Here's another example using a Component.
+Components are usually made of two files, a JavaScript file `my-component.js` and a
+template file with the same name, `my-component.js`. Whatever attributes are defined
+in the Component's JavaScript are available for use in the Template:
-### Helpers
+```javascript {data-filename=app/components/my-component.js}
+import Component from '@ember/component';
-Ember Helpers are functions that can compute values and can be used in any template.
+export default Component.extend({
+ firstName: 'Jessica',
+ lastName: 'Jordan'
+});
+```
-Ember gives you the ability to [write your own helpers](../writing-helpers/), to bring a minimum of logic into Ember templating.
+```handlebars {data-filename=app/templates/components/my-component.hbs}
+Hello, {{this.firstName}} {{this.lastName}}!
+```
+
+This would render:
+
+```html
+Hello, Jessica Jordan!
+```
+
+## Things you might see in a Template
+
+A lot more than just HTML markup can go in Templates. In the other pages of this guide, we will cover the features one at a time. In general, special Ember functionality will appear inside curly braces, like this: `{{example}}`. Here are a few examples of Ember Handlebars in action:
+
+Route example:
+```hbs {data-filename=app/templates/application.hbs data-update=true}
+{{!-- Example of a comment that will be invisible --}}
+
+{{!-- outlet determines where a child route's content should render. Don't delete it until you know more about it! --}}
+
+ {{outlet}}
+
+
+{{!-- One way to use a component within a template. This is called "Angle Bracket Component syntax." --}}
+
+
+```
+
+Component example:
+```hbs {data-filename=app/components/templates/my-component.hbs data-update=true}
+{{!-- An attribute that is defined in a component's JavaScript file --}}
+{{this.numberOfSquirrels}}
+
+{{!-- Some data passed down from a parent component or controller --}}
+{{weatherStatus}}
+
+{{!-- This button uses Ember Actions to make it interactive. A method named `plantATree` is called when the button is clicked --}}
+
```
-If you make a mistake like forgetting to close a tag or missing a quotation mark, you will see some errors when you run the app with `ember serve`. However, reading the error message on the page or in your browser's developer console will get you going again right away.
+The compiler will help you catch some errors, such as forgetting to close a tag or missing a quotation mark. You might see these errors when you run the app with `ember serve`. Reading the error message on the page or in your browser's developer console will get you going again.
## Types of templates
From 11d1d5ba4a0f44a60ca024d2ae0f61a08745326a Mon Sep 17 00:00:00 2001
From: Jen Weber
Date: Tue, 5 Mar 2019 20:30:52 -0500
Subject: [PATCH 05/14] one template to one hundred templates
---
guides/release/templates/handlebars-basics.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/guides/release/templates/handlebars-basics.md b/guides/release/templates/handlebars-basics.md
index ebe0401696..7e2cdba32c 100644
--- a/guides/release/templates/handlebars-basics.md
+++ b/guides/release/templates/handlebars-basics.md
@@ -23,7 +23,7 @@ There are two main types of templates: Route templates and Component templates.
A Route template determines what is shown when someone visits a particular url, like `https://guides.emberjs.com/some-route`. A Component template has bits of content that can be reused in multiple places throughout the app, like buttons or forms.
-The best way to tell if a template is part of a Route or Component is to look at the filepath. If you look at an existing app, you will see templates in many different places in the app folder structure! This is to help the app stay organized as it grows from one to one hundred templates.
+The best way to tell if a template is part of a Route or Component is to look at the filepath. If you look at an existing app, you will see templates in many different places in the app folder structure! This is to help the app stay organized as it grows from one template to _one hundred_ templates.
## Making new templates
From 8d67b44c6c3e41eaa7c2144895d897fde901448f Mon Sep 17 00:00:00 2001
From: Jen Weber
Date: Tue, 5 Mar 2019 20:34:23 -0500
Subject: [PATCH 06/14] correct route lifecycle to components, add ember
generate command
---
guides/release/templates/handlebars-basics.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/guides/release/templates/handlebars-basics.md b/guides/release/templates/handlebars-basics.md
index 7e2cdba32c..caa053b4f9 100644
--- a/guides/release/templates/handlebars-basics.md
+++ b/guides/release/templates/handlebars-basics.md
@@ -27,7 +27,7 @@ The best way to tell if a template is part of a Route or Component is to look at
## Making new templates
-New templates should be made using the [Ember CLI](https://cli.emberjs.com). It helps ensure that the files go in the right place in the app folder structure, and that they follow the right file naming conventions. If you have never used the Ember CLI before, it is recommended to do the [Tutorial]().
+New templates should be made using [Ember CLI](https://cli.emberjs.com) commands such as `ember generate route`, `ember generate component`. The CLI helps ensure that the files go in the right place in the app folder structure, and that they follow the right file naming conventions. If you have never used the Ember CLI before, it is recommended to do the [Tutorial](../../tutorial/ember-cli).
For example, either of these commands will generate `.hbs` template files (and other things!) in your app:
@@ -40,7 +40,7 @@ ember generate route my-route-name
A typical, modern web app is made of dozens of files that have to all be combined together into something the browser can understand. Ember does this work for you with zero configuration, but as a result, there are some rules to follow when it comes to adding assets into your HTML.
-You cannot use script tags directly within a template, and should use [actions](../actions) or [Route Lifecycle Hooks](../../routing/specifying-a-routes-model) to make your app responsive to user interactions and new data. If you are working with a non-Ember JavaScript library and need to use a `js` file from it, see the Guide section [Addons and Dependencies]().
+You cannot use script tags directly within a template, and should use [actions](../actions) or [Component Lifecycle Hooks](../../components/the-component-lifecycle/specifying-a-routes-model) to make your app responsive to user interactions and new data. If you are working with a non-Ember JavaScript library and need to use a `js` file from it, see the Guide section [Addons and Dependencies]().
Similarly, you should not add links to CSS Stylesheets within the `hbs` file. Style rules should go in the `app/styles` directory instead. `app/styles/app.css` is included in your app's build by default. For CSS files within the styles directory, you can create multiple stylesheets and use regular CSS APIs like `import` to link them together. If you want to incorporate CSS from an npm package or similar, see [Addons and Dependencies]() for instructions.
From ef1cae5acc9e58b7fb14ecffb0e82b64302a4e23 Mon Sep 17 00:00:00 2001
From: Jen Weber
Date: Tue, 5 Mar 2019 20:52:28 -0500
Subject: [PATCH 07/14] md linting and small edits
---
guides/release/templates/handlebars-basics.md | 77 +++++++++++++------
1 file changed, 52 insertions(+), 25 deletions(-)
diff --git a/guides/release/templates/handlebars-basics.md b/guides/release/templates/handlebars-basics.md
index caa053b4f9..ba6494efb1 100644
--- a/guides/release/templates/handlebars-basics.md
+++ b/guides/release/templates/handlebars-basics.md
@@ -1,12 +1,17 @@
Templates are the home for what the user sees, like forms, buttons, links, and headings.
-In this section of the Guides, you will learn about where to write HTML markup, plus how to add interaction, dynamically changing content, styling, and more. If you want to learn in a step-by-step way, you should begin your journey in the [Tutorial](../../tutorial/ember-cli) instead.
+In this section of the Guides, you will learn about where to write HTML markup, plus how to add interaction, dynamically changing content, styling, and more.
+If you want to learn in a step-by-step way, you should begin your journey in the [Tutorial](../../tutorial/ember-cli) instead.
## Writing plain HTML
-Ember templates have some superpowers, but let's start with regular HTML. For any file in an Ember app that has an extension ending in `.hbs`, you can write HTML markup in it as if it was an `.html` file. HTML is the language that browsers understand for laying out content on a web page. `.hbs` stands for Handlebars, the name of a tool that lets you write more than just HTML in your templates.
+Ember templates have some superpowers, but let's start with regular HTML.
+For any file in an Ember app that has an extension ending in `.hbs`, you can write HTML markup in it as if it was an `.html` file.
+HTML is the language that browsers understand for laying out content on a web page.
+`.hbs` stands for Handlebars, the name of a tool that lets you write more than just HTML in your templates.
-For example, every Ember app has a file called `application.hbs`. You can write regular HTML markup there or in any other `hbs` file:
+For example, every Ember app has a file called `application.hbs`.
+You can write regular HTML markup there or in any other `hbs` file:
```hbs {data-filename=app/templates/application.hbs data-update=false}
Starting simple
@@ -15,19 +20,24 @@ For example, every Ember app has a file called `application.hbs`. You can write
```
-The compiler will help you catch some errors, such as forgetting to close a tag or missing a quotation mark. You might see these errors when you run the app with `ember serve`. Reading the error message on the page or in your browser's developer console will get you going again.
+When you start an app with `ember serve`, the compiler may help you catch some errors, such as forgetting to close a tag or missing a quotation mark.
+Reading the error message on the page or in your browser's developer console will get you back on track.
## Types of templates
There are two main types of templates: Route templates and Component templates.
-A Route template determines what is shown when someone visits a particular url, like `https://guides.emberjs.com/some-route`. A Component template has bits of content that can be reused in multiple places throughout the app, like buttons or forms.
+A Route template determines what is shown when someone visits a particular url, like `https://guides.emberjs.com/some-route`.
+A Component template has bits of content that can be reused in multiple places throughout the app, like buttons or forms.
-The best way to tell if a template is part of a Route or Component is to look at the filepath. If you look at an existing app, you will see templates in many different places in the app folder structure! This is to help the app stay organized as it grows from one template to _one hundred_ templates.
+If you look at an existing app, you will see templates in many different places in the app folder structure!
+This is to help the app stay organized as it grows from one template to _one hundred_ templates.
+The best way to tell if a template is part of a Route or Component is to look at the filepath.
## Making new templates
-New templates should be made using [Ember CLI](https://cli.emberjs.com) commands such as `ember generate route`, `ember generate component`. The CLI helps ensure that the files go in the right place in the app folder structure, and that they follow the right file naming conventions. If you have never used the Ember CLI before, it is recommended to do the [Tutorial](../../tutorial/ember-cli).
+New templates should be made using [Ember CLI](https://cli.emberjs.com) commands.
+The CLI helps ensure that the new files go in the right place in the app folder structure, and that they follow the essential file naming conventions.
For example, either of these commands will generate `.hbs` template files (and other things!) in your app:
@@ -38,21 +48,31 @@ ember generate route my-route-name
## Template restrictions
-A typical, modern web app is made of dozens of files that have to all be combined together into something the browser can understand. Ember does this work for you with zero configuration, but as a result, there are some rules to follow when it comes to adding assets into your HTML.
+A typical, modern web app is made of dozens of files that have to all be combined together into something the browser can understand.
+Ember does this work for you with zero configuration, but as a result, there are some rules to follow when it comes to adding assets into your HTML.
-You cannot use script tags directly within a template, and should use [actions](../actions) or [Component Lifecycle Hooks](../../components/the-component-lifecycle/specifying-a-routes-model) to make your app responsive to user interactions and new data. If you are working with a non-Ember JavaScript library and need to use a `js` file from it, see the Guide section [Addons and Dependencies]().
+You cannot use script tags directly within a template, and should use [actions](../actions) or [Component Lifecycle Hooks](../../components/the-component-lifecycle/specifying-a-routes-model) to make your app responsive to user interactions and new data.
+If you are working with a non-Ember JavaScript library and need to use a `js` file from it, see the Guide section [Addons and Dependencies](../../addons-and-dependencies).
-Similarly, you should not add links to CSS Stylesheets within the `hbs` file. Style rules should go in the `app/styles` directory instead. `app/styles/app.css` is included in your app's build by default. For CSS files within the styles directory, you can create multiple stylesheets and use regular CSS APIs like `import` to link them together. If you want to incorporate CSS from an npm package or similar, see [Addons and Dependencies]() for instructions.
+You should not add links to your own local CSS files within the `hbs` file.
+Style rules should go in the `app/styles` directory instead.
+`app/styles/app.css` is included in your app's build by default.
+For CSS files within the styles directory, you can create multiple stylesheets and use regular CSS APIs like `import` to link them together.
+If you want to incorporate CSS from an npm package or similar, see [Addons and Dependencies](../../addons-and-dependencies) for instructions.
+To load styles through a CDN, read the next section below.
## What is `index.html` for?
If HTML markup goes in `hbs` templates, what is `index.html` for?
-The `index.html` file is the entry point for an app. It is not a template, but rather it is where all the templates, stylesheets, and JavaScript come together into something the browser can understand.
+The `index.html` file is the entry point for an app.
+It is not a template, but rather it is where all the templates, stylesheets, and JavaScript come together into something the browser can understand.
-When you are first getting started in Ember, you will not need to make any changes to `index.html`. There's no need to add any links to other Ember app pages, stylesheets, or scripts in here by hand, since Ember's built-in tools do the work for you.
+When you are first getting started in Ember, you will not need to make any changes to `index.html`.
+There's no need to add any links to other Ember app pages, stylesheets, or scripts in here by hand, since Ember's built-in tools do the work for you.
-The most common customizations developers make to `index.html` are when they use a CDN to load assets like fonts or stylesheets. Here's an example:
+A common customization developers make to `index.html` is adding a link to a CDN that loads assets like fonts and stylesheets.
+Here's an example:
```html {data-filename=app/index.html}
@@ -60,7 +80,9 @@ The most common customizations developers make to `index.html` are when they use
## Understanding a Template's context
-A Template only has access to the data it has been given. This is referred to as the Template's "context." For example, to display a property inside a Route's Template, it should be defined in a Controller:
+A Template only has access to the data it has been given.
+This is referred to as the Template's "context."
+For example, to display a property inside a Route's Template, it should be defined in a Controller:
```javascript {data-filename=app/controllers/application.js}
import Controller from '@ember/controller';
@@ -86,12 +108,13 @@ The above template and controller render as the following HTML:
Hello, Trek Glowacki!
```
-If you use JavaScript to change the values of `firstName` or `lastName` in the Controller, what the user sees will be automatically updated! In Ember, this is referred to as "data binding."
+If you use JavaScript to change the values of `firstName` or `lastName` in the Controller, what the user sees will be automatically updated!
+In Ember, this is referred to as "data binding."
Here's another example using a Component.
Components are usually made of two files, a JavaScript file `my-component.js` and a
-template file with the same name, `my-component.js`. Whatever attributes are defined
-in the Component's JavaScript are available for use in the Template:
+template file with the same name, `my-component.js`.
+Whatever attributes are defined in the Component's JavaScript are available for use in the Template:
```javascript {data-filename=app/components/my-component.js}
import Component from '@ember/component';
@@ -114,7 +137,10 @@ Hello, Jessica Jordan!
## Things you might see in a Template
-A lot more than just HTML markup can go in templates. In the other pages of this guide, we will cover the features one at a time. In general, special Ember functionality will appear inside curly braces, like this: `{{example}}`. Here are a few examples of Ember Handlebars in action:
+A lot more than just HTML markup can go in templates.
+In the other pages of this guide, we will cover the features one at a time.
+In general, special Ember functionality will appear inside curly braces, like this: `{{example}}`.
+Here are a few examples of Ember Handlebars in action:
Route example:
```hbs {data-filename=app/templates/application.hbs data-update=true}
@@ -138,7 +164,7 @@ Component example:
{{!-- Some data passed down from a parent component or controller --}}
{{weatherStatus}}
-{{!-- This button uses Ember Actions to make it interactive. A method named `plantATree` is called when the button is clicked --}}
+{{!-- This button uses Ember Actions to make it interactive. 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 --}}
More trees!
@@ -152,8 +178,8 @@ Component example:
{{yield}}
```
-Lastly, it's important to know that data can be passed from
-one template to another. Here's what it looks like
+Lastly, it's important to know that data can be passed from one template to another.
+Here's what it looks like
to pass data from a Route template to a Component template.
```handlebars {data-filename=app/templates/application.hbs}
@@ -164,9 +190,10 @@ Learn more about passing data between templates in [../../components/passing-pro
## Helper functions
-Ember Helpers are pure functions that can be used in any template to change how data is displayed. For example, you could write a Helper function that capitalizes a word, does some math, converts a currency, or more.
+Ember Helpers are pure functions that can be used in any template to change how data is displayed.
+For example, you could write a Helper function that capitalizes a word, does some math, converts a currency, or more.
A Helper takes in `parameters`, which is an array of the values passed into the function, and should return a value.
-Ember gives you the ability to [write your own helpers](../writing-helpers/), and comes with some [helpers built-in]().
+Ember gives you the ability to [write your own helpers](../writing-helpers/), and comes with some [helpers built-in](../built-in-helpers).
For example, let's say you would like the ability to add two numbers together.
Define a function in `app/helpers/sum.js` to create a `sum` helper:
@@ -196,7 +223,7 @@ Ember ships with several built-in helpers, which you will learn more about in th
Sometimes, you might see helpers used inside of some parentheses, `()`.
It means that a Helper is being used inside of another Helper or Component.
-This is referred to as a "nested" Helper.
+This is referred to as a "nested" Helper.
Parentheses must be used because curly braces `{{}}` cannot be nested.
```handlebars {data-filename=app/templates/application.hbs}
@@ -209,4 +236,4 @@ Thus, the output of these combined helpers is `10`.
As you move forward with these template guides, keep in mind that a helper can be used anywhere a normal value can be used.
-Many of Ember's built-in helpers (as well as your custom helpers) can be used in nested form.
\ No newline at end of file
+Many of Ember's built-in helpers (as well as your custom helpers) can be used in nested form.
From 338262e4eb10f9099e5025daa98448114d524e9d Mon Sep 17 00:00:00 2001
From: Jen Weber
Date: Wed, 6 Mar 2019 22:19:12 -0500
Subject: [PATCH 08/14] apply feedback
---
guides/release/templates/handlebars-basics.md | 74 ++++++-------------
1 file changed, 23 insertions(+), 51 deletions(-)
diff --git a/guides/release/templates/handlebars-basics.md b/guides/release/templates/handlebars-basics.md
index ba6494efb1..ef4bbe6b12 100644
--- a/guides/release/templates/handlebars-basics.md
+++ b/guides/release/templates/handlebars-basics.md
@@ -80,21 +80,21 @@ Here's an example:
## Understanding a Template's context
-A Template only has access to the data it has been given.
-This is referred to as the Template's "context."
-For example, to display a property inside a Route's Template, it should be defined in a Controller:
+A template only has access to the data it has been given.
+This is referred to as the template's "context."
+For example, to display a property inside a Component's template, it should be defined in the Component's JavaScript file:
-```javascript {data-filename=app/controllers/application.js}
-import Controller from '@ember/controller';
+```javascript {data-filename=app/components/my-component.js}
+import Component from '@ember/component';
-export default Controller.extend({
+export default Component.extend({
firstName: 'Trek',
lastName: 'Glowacki',
favoriteFramework: 'Ember'
});
```
-The attributes like `firstName` can be used in the template
+Properties like `firstName` can be used in the template
by putting them inside of curly braces, plus the word
`this`:
@@ -102,40 +102,13 @@ by putting them inside of curly braces, plus the word
Hello, {{this.firstName}} {{this.lastName}}!
```
-The above template and controller render as the following HTML:
+Together, these render with the following HTML:
```html
Hello, Trek Glowacki!
```
-If you use JavaScript to change the values of `firstName` or `lastName` in the Controller, what the user sees will be automatically updated!
-In Ember, this is referred to as "data binding."
-
-Here's another example using a Component.
-Components are usually made of two files, a JavaScript file `my-component.js` and a
-template file with the same name, `my-component.js`.
-Whatever attributes are defined in the Component's JavaScript are available for use in the Template:
-
-```javascript {data-filename=app/components/my-component.js}
-import Component from '@ember/component';
-
-export default Component.extend({
- firstName: 'Jessica',
- lastName: 'Jordan'
-});
-```
-
-```handlebars {data-filename=app/templates/components/my-component.hbs}
-Hello, {{this.firstName}} {{this.lastName}}!
-```
-
-This would render:
-
-```html
-Hello, Jessica Jordan!
-```
-
-## Things you might see in a Template
+## Things you might see in a template
A lot more than just HTML markup can go in templates.
In the other pages of this guide, we will cover the features one at a time.
@@ -144,53 +117,52 @@ Here are a few examples of Ember Handlebars in action:
Route example:
```hbs {data-filename=app/templates/application.hbs data-update=true}
-{{!-- Example of a comment that will be invisible --}}
-{{!-- outlet determines where a child route's content should render. Don't delete it until you know more about it! --}}
+
{{outlet}}
-{{!-- One way to use a component within a template. This is called "Angle Bracket Component syntax." --}}
+
+{{! Example of a comment that will be invisible, even if it contains things in {{curlyBraces}} }}
+
```
Component example:
```hbs {data-filename=app/components/templates/my-component.hbs data-update=true}
-{{!-- An attribute that is defined in a component's JavaScript file --}}
+
{{this.numberOfSquirrels}}
-{{!-- Some data passed down from a parent component or controller --}}
+
{{weatherStatus}}
-{{!-- This button uses Ember Actions to make it interactive. 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 --}}
+
More trees!
-{{!-- Here's an example of template logic in action. If the `this.skyIsBlue` attribute is `true`, the text inside will be shown --}}
+
{{#if this.skyIsBlue}}
- If the skyIsBlue attribute is true, show this message
+ If the skyIsBlue property is true, show this message
{{/if}}
-{{!-- You can pass a whole block of markup and handlebars content from one component to another. yield is where the block shows up when the page is rendered --}}
+
{{yield}}
```
-Lastly, it's important to know that data can be passed from one template to another.
-Here's what it looks like
-to pass data from a Route template to a Component template.
+Lastly, it's important to know that arguments can be passed from one Component to another through templates:
-```handlebars {data-filename=app/templates/application.hbs}
+```handlebars {data-filename=app/templates/some-other-component.hbs}
```
-Learn more about passing data between templates in [../../components/passing-properties-to-a-component].
+To pass in arguments associated with a Route, define the property from within a Controller. Learn more about passing data between templates in [../../components/passing-properties-to-a-component].
## Helper functions
-Ember Helpers are pure functions that can be used in any template to change how data is displayed.
+Ember Helpers are a way to use JavaScript logic in your templates.
For example, you could write a Helper function that capitalizes a word, does some math, converts a currency, or more.
A Helper takes in `parameters`, which is an array of the values passed into the function, and should return a value.
Ember gives you the ability to [write your own helpers](../writing-helpers/), and comes with some [helpers built-in](../built-in-helpers).
From 18eda07070094c55eb5f1eb8015352a4f4286ea8 Mon Sep 17 00:00:00 2001
From: Jen Weber
Date: Thu, 7 Mar 2019 00:23:05 -0500
Subject: [PATCH 09/14] fix links
---
guides/release/templates/handlebars-basics.md | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/guides/release/templates/handlebars-basics.md b/guides/release/templates/handlebars-basics.md
index ef4bbe6b12..83c74a0f5d 100644
--- a/guides/release/templates/handlebars-basics.md
+++ b/guides/release/templates/handlebars-basics.md
@@ -1,7 +1,7 @@
Templates are the home for what the user sees, like forms, buttons, links, and headings.
In this section of the Guides, you will learn about where to write HTML markup, plus how to add interaction, dynamically changing content, styling, and more.
-If you want to learn in a step-by-step way, you should begin your journey in the [Tutorial](../../tutorial/ember-cli) instead.
+If you want to learn in a step-by-step way, you should begin your journey in the [Tutorial](../../tutorial/ember-cli/) instead.
## Writing plain HTML
@@ -27,7 +27,7 @@ Reading the error message on the page or in your browser's developer console wil
There are two main types of templates: Route templates and Component templates.
-A Route template determines what is shown when someone visits a particular url, like `https://guides.emberjs.com/some-route`.
+A Route template determines what is shown when someone visits a particular URL, like `https://guides.emberjs.com/some-route`.
A Component template has bits of content that can be reused in multiple places throughout the app, like buttons or forms.
If you look at an existing app, you will see templates in many different places in the app folder structure!
@@ -51,14 +51,14 @@ ember generate route my-route-name
A typical, modern web app is made of dozens of files that have to all be combined together into something the browser can understand.
Ember does this work for you with zero configuration, but as a result, there are some rules to follow when it comes to adding assets into your HTML.
-You cannot use script tags directly within a template, and should use [actions](../actions) or [Component Lifecycle Hooks](../../components/the-component-lifecycle/specifying-a-routes-model) to make your app responsive to user interactions and new data.
-If you are working with a non-Ember JavaScript library and need to use a `js` file from it, see the Guide section [Addons and Dependencies](../../addons-and-dependencies).
+You cannot use script tags directly within a template, and should use [actions](/actions) or [Component Lifecycle Hooks](../../components/the-component-lifecycle/) to make your app responsive to user interactions and new data.
+If you are working with a non-Ember JavaScript library and need to use a `js` file from it, see the Guide section [Addons and Dependencies](../../addons-and-dependencies/managing-dependencies/).
You should not add links to your own local CSS files within the `hbs` file.
Style rules should go in the `app/styles` directory instead.
`app/styles/app.css` is included in your app's build by default.
For CSS files within the styles directory, you can create multiple stylesheets and use regular CSS APIs like `import` to link them together.
-If you want to incorporate CSS from an npm package or similar, see [Addons and Dependencies](../../addons-and-dependencies) for instructions.
+If you want to incorporate CSS from an npm package or similar, see [Addons and Dependencies](../../addons-and-dependencies/managing-dependencies/) for instructions.
To load styles through a CDN, read the next section below.
## What is `index.html` for?
From 6f9f89d52f7091fc9dc8f27b132421934fe8e696 Mon Sep 17 00:00:00 2001
From: Jen Weber
Date: Thu, 7 Mar 2019 00:39:31 -0500
Subject: [PATCH 10/14] fix links
---
guides/release/templates/handlebars-basics.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/guides/release/templates/handlebars-basics.md b/guides/release/templates/handlebars-basics.md
index 83c74a0f5d..f75d7980a3 100644
--- a/guides/release/templates/handlebars-basics.md
+++ b/guides/release/templates/handlebars-basics.md
@@ -32,7 +32,7 @@ A Component template has bits of content that can be reused in multiple places t
If you look at an existing app, you will see templates in many different places in the app folder structure!
This is to help the app stay organized as it grows from one template to _one hundred_ templates.
-The best way to tell if a template is part of a Route or Component is to look at the filepath.
+The best way to tell if a template is part of a Route or Component is to look at the file path.
## Making new templates
@@ -158,7 +158,7 @@ Lastly, it's important to know that arguments can be passed from one Component t
```
-To pass in arguments associated with a Route, define the property from within a Controller. Learn more about passing data between templates in [../../components/passing-properties-to-a-component].
+To pass in arguments associated with a Route, define the property from within a Controller. Learn more about passing data between templates (here)[../../components/passing-properties-to-a-component].
## Helper functions
From c3168d6dc9bb90c1a489282b0de5034bcfa36bbc Mon Sep 17 00:00:00 2001
From: Jen Weber
Date: Thu, 7 Mar 2019 00:48:09 -0500
Subject: [PATCH 11/14] more linting
---
guides/release/templates/handlebars-basics.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/guides/release/templates/handlebars-basics.md b/guides/release/templates/handlebars-basics.md
index f75d7980a3..52854d8e50 100644
--- a/guides/release/templates/handlebars-basics.md
+++ b/guides/release/templates/handlebars-basics.md
@@ -51,7 +51,7 @@ ember generate route my-route-name
A typical, modern web app is made of dozens of files that have to all be combined together into something the browser can understand.
Ember does this work for you with zero configuration, but as a result, there are some rules to follow when it comes to adding assets into your HTML.
-You cannot use script tags directly within a template, and should use [actions](/actions) or [Component Lifecycle Hooks](../../components/the-component-lifecycle/) to make your app responsive to user interactions and new data.
+You cannot use script tags directly within a template, and should use [actions](../actions) or [Component Lifecycle Hooks](../../components/the-component-lifecycle/) to make your app responsive to user interactions and new data.
If you are working with a non-Ember JavaScript library and need to use a `js` file from it, see the Guide section [Addons and Dependencies](../../addons-and-dependencies/managing-dependencies/).
You should not add links to your own local CSS files within the `hbs` file.
@@ -158,7 +158,7 @@ Lastly, it's important to know that arguments can be passed from one Component t
```
-To pass in arguments associated with a Route, define the property from within a Controller. Learn more about passing data between templates (here)[../../components/passing-properties-to-a-component].
+To pass in arguments associated with a Route, define the property from within a Controller. Learn more about passing data between templates [here](../../components/passing-properties-to-a-component).
## Helper functions
From 6afb535db78bb9e2f5732f621cedc79f0d8c46b9 Mon Sep 17 00:00:00 2001
From: Jen Weber
Date: Thu, 7 Mar 2019 01:00:56 -0500
Subject: [PATCH 12/14] really actually fix the link?
---
guides/release/templates/handlebars-basics.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/guides/release/templates/handlebars-basics.md b/guides/release/templates/handlebars-basics.md
index 52854d8e50..559c22765f 100644
--- a/guides/release/templates/handlebars-basics.md
+++ b/guides/release/templates/handlebars-basics.md
@@ -51,7 +51,7 @@ ember generate route my-route-name
A typical, modern web app is made of dozens of files that have to all be combined together into something the browser can understand.
Ember does this work for you with zero configuration, but as a result, there are some rules to follow when it comes to adding assets into your HTML.
-You cannot use script tags directly within a template, and should use [actions](../actions) or [Component Lifecycle Hooks](../../components/the-component-lifecycle/) to make your app responsive to user interactions and new data.
+You cannot use script tags directly within a template, and should use [actions](../actions/) or [Component Lifecycle Hooks](../../components/the-component-lifecycle/) to make your app responsive to user interactions and new data.
If you are working with a non-Ember JavaScript library and need to use a `js` file from it, see the Guide section [Addons and Dependencies](../../addons-and-dependencies/managing-dependencies/).
You should not add links to your own local CSS files within the `hbs` file.
From 05fc27eb299f25af47ea83a98a3bd25a58c7e8c2 Mon Sep 17 00:00:00 2001
From: Jen Weber
Date: Thu, 7 Mar 2019 01:30:17 -0500
Subject: [PATCH 13/14] fix hbs syntax highlighting
---
guides/release/templates/handlebars-basics.md | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/guides/release/templates/handlebars-basics.md b/guides/release/templates/handlebars-basics.md
index 559c22765f..540e662707 100644
--- a/guides/release/templates/handlebars-basics.md
+++ b/guides/release/templates/handlebars-basics.md
@@ -13,7 +13,7 @@ HTML is the language that browsers understand for laying out content on a web pa
For example, every Ember app has a file called `application.hbs`.
You can write regular HTML markup there or in any other `hbs` file:
-```hbs {data-filename=app/templates/application.hbs data-update=false}
+```handlebars {data-filename=app/templates/application.hbs data-update=false}
Starting simple
This is regular html markup inside an hbs file
@@ -116,7 +116,7 @@ In general, special Ember functionality will appear inside curly braces, like th
Here are a few examples of Ember Handlebars in action:
Route example:
-```hbs {data-filename=app/templates/application.hbs data-update=true}
+```handlebars {data-filename=app/templates/application.hbs data-update=true}
@@ -131,7 +131,8 @@ Route example:
```
Component example:
-```hbs {data-filename=app/components/templates/my-component.hbs data-update=true}
+
+```handlebars {data-filename=app/components/templates/my-component.hbs data-update=true}
{{this.numberOfSquirrels}}
From 7fab37fd4de8bd3dacbf6538807335fa6584beb2 Mon Sep 17 00:00:00 2001
From: Jen Weber
Date: Thu, 7 Mar 2019 01:33:14 -0500
Subject: [PATCH 14/14] code block spacing
---
guides/release/templates/handlebars-basics.md | 28 +++++++++++++------
1 file changed, 20 insertions(+), 8 deletions(-)
diff --git a/guides/release/templates/handlebars-basics.md b/guides/release/templates/handlebars-basics.md
index 540e662707..24eacfc010 100644
--- a/guides/release/templates/handlebars-basics.md
+++ b/guides/release/templates/handlebars-basics.md
@@ -118,7 +118,9 @@ Here are a few examples of Ember Handlebars in action:
Route example:
```handlebars {data-filename=app/templates/application.hbs data-update=true}
-
+
{{outlet}}
@@ -126,30 +128,41 @@ Route example:
-{{! Example of a comment that will be invisible, even if it contains things in {{curlyBraces}} }}
+{{! Example of a comment that will be invisible, even
+if it contains things in {{curlyBraces}} }}
```
Component example:
```handlebars {data-filename=app/components/templates/my-component.hbs data-update=true}
-
+
{{this.numberOfSquirrels}}
-
+
{{weatherStatus}}
-
+
More trees!
-
+
{{#if this.skyIsBlue}}
If the skyIsBlue property is true, show this message
{{/if}}
-
+
{{yield}}
```
@@ -171,7 +184,6 @@ Ember gives you the ability to [write your own helpers](../writing-helpers/), an
For example, let's say you would like the ability to add two numbers together.
Define a function in `app/helpers/sum.js` to create a `sum` helper:
-
```javascript {data-filename=app/helpers/sum.js}
import { helper as buildHelper } from '@ember/component/helper';