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 --}} +