New Templates intro #477

jenweber · 2019-02-18T22:26:44Z

This is a rough draft that should not be merged yet. It is for evaluating what, if any, of this content could come into the Guides.

To make Templates work as the opening topic, additions are necessary in the introduction.

This PR partially addresses #460

jenweber · 2019-02-18T22:35:01Z

Chatted with Jessica and she is ok with me using her name in an example :)

ppcano

@jenweber I reviewed and suggested the required changes for the Octane/MU layout.

Please, let me know if you have any question.

ppcano · 2019-02-19T06:03:25Z

guides/release/templates/handlebars-basics.md

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


In MU/Octane layout:

app/styles -> src/ui/styles
app/styles/app.css -> src/ui/styles/app.css

ppcano · 2019-02-19T06:04:39Z

guides/release/templates/handlebars-basics.md

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


app/index.html -> src/ui/index.html

ppcano · 2019-02-19T06:05:46Z

guides/release/templates/handlebars-basics.md

+by putting them inside of curly braces, plus the word
+`this`:
+
+```handlebars {data-filename=app/templates/application.hbs}


app/templates/application.hbs -> src/ui/routes/application/template.hbs

ppcano · 2019-02-19T06:06:07Z

guides/release/templates/handlebars-basics.md

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


app/controllers/application.hbs -> src/ui/routes/application/controller.js

ppcano · 2019-02-19T06:06:48Z

guides/release/templates/handlebars-basics.md


-### Helpers
+```javascript {data-filename=app/components/my-component.js}


app/components/my-component.js -> src/ui/components/my-component/component.js

ppcano · 2019-02-19T06:11:05Z

guides/release/templates/handlebars-basics.md

+Ember gives you the ability to [write your own helpers](../writing-helpers/), and comes with some [helpers built-in]().
+
+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:


app/helpers/sum.js -> src/ui/components/sum.js

ppcano · 2019-02-19T06:11:24Z

guides/release/templates/handlebars-basics.md

 };

 export default helper(sum);
 ```

-The above code will allow you invoke the `sum()` function as a `{{sum}}` handlebars "helper" in your templates:
+Now you can use the `sum()` function as `{{sum}}` in your templates:

 ```handlebars {data-filename=app/templates/application.hbs}


app/templates/application.hbs -> src/routes/application/template.hbs

ppcano · 2019-02-19T06:11:37Z

guides/release/templates/handlebars-basics.md

+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. 
+Parentheses must be used because curly braces `{{}}` cannot be nested.

 ```handlebars {data-filename=app/templates/application.hbs}


app/templates/application.hbs -> src/routes/application/template.hbs

guides/release/templates/handlebars-basics.md

ppcano · 2019-02-19T06:16:06Z

guides/release/templates/handlebars-basics.md


-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:


application.hbs --> src/ui/routes/application/application.hbs

I think it'd make sense to keep the phrasing, but add "(located at: )"

locks · 2019-02-19T08:15:56Z

@ppcano thanks for your input, but I believe this is targetting master and not octane on purpose!

locks

I am not fond of the capitalized Template throughout the prose 😅 .
Some small tweaks and questions heading your way!

guides/release/templates/handlebars-basics.md

locks · 2019-02-19T08:21:33Z

guides/release/templates/handlebars-basics.md

+
+## 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]().


"should" seems a bit strong because of the fact that the commands generate other files than the template.
Why not mention the ember generate template command?

guides/release/templates/handlebars-basics.md

locks · 2019-02-19T08:24:24Z

guides/release/templates/handlebars-basics.md

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


my kingdom for a styling section 😂

guides/release/templates/handlebars-basics.md

locks · 2019-02-19T08:34:01Z

guides/release/templates/handlebars-basics.md

+{{yield}}
+```
+
+Lastly, it's important to know that data can be passed from


I think this will be super confusing and could be removed.

Yeah, I'm not sure this should be explained quite like this. I wonder how React introduces props 🤔 I think this should be explained as arguments from the get go though. Maybe we can add a hand-wavey explanation of Component above to introduce the concept of arguments?

guides/release/templates/handlebars-basics.md

locks · 2019-02-19T08:49:12Z

guides/release/templates/handlebars-basics.md

+
+Learn more about passing data between Templates in [../../components/passing-properties-to-a-component].
+
+## Helper functions


I want to split this out ssooo bad.

pzuraq

This is looking really great so far! Sorry for the late review, but thanks for putting this together @jenweber, I really love the tone so far

guides/release/templates/handlebars-basics.md

pzuraq · 2019-02-20T02:24:27Z

guides/release/templates/handlebars-basics.md


-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:


I think it'd make sense to keep the phrasing, but add "(located at: )"

guides/release/templates/handlebars-basics.md

pzuraq · 2019-02-20T02:35:09Z

guides/release/templates/handlebars-basics.md

+{{yield}}
+```
+
+Lastly, it's important to know that data can be passed from


Yeah, I'm not sure this should be explained quite like this. I wonder how React introduces props 🤔 I think this should be explained as arguments from the get go though. Maybe we can add a hand-wavey explanation of Component above to introduce the concept of arguments?

guides/release/templates/handlebars-basics.md

jenweber · 2019-03-07T03:20:49Z

A few changes I made:

nearly all of the above suggestions
un-capitalized "templates" since it's a generic term
Added a line break after every period
I cut the "passing data from a controller to a component" altogether, and just added a note about it
I simplified wording in a few places but it could use another pass, someday that is not now
And I rebased

jenweber · 2019-03-07T03:23:43Z

P.S. Thanks everyone for your careful reviews ❤️

All issues addressed, and have been reviewed again

… templates

* Rough draft of new Templates intro * update helper to buildHelper * lowercase Template --> template * the compiler is your friend * one template to one hundred templates * correct route lifecycle to components, add ember generate command * apply feedback * fix links, more linting, code block spacing

jenweber requested a review from locks February 18, 2019 22:26

jenweber added the wip - work in progress label Feb 18, 2019

jenweber requested a review from pzuraq February 18, 2019 22:32

jenweber mentioned this pull request Feb 18, 2019

Update Octane guides section: Templates #460

Closed

7 tasks

ppcano suggested changes Feb 19, 2019

View reviewed changes

locks previously requested changes Feb 19, 2019

View reviewed changes

pzuraq reviewed Feb 20, 2019

View reviewed changes

pzuraq mentioned this pull request Feb 20, 2019

Analyze Section: Templates #252

Closed

2 tasks

jenweber added 8 commits March 6, 2019 22:22

Rough draft of new Templates intro

7779a68

update helper to buildHelper

9b8225e

lowercase Template --> template

8357d52

the compiler is your friend

c116e56

one template to one hundred templates

11d1d5b

correct route lifecycle to components, add ember generate command

8d67b44

md linting and small edits

ef1cae5

apply feedback

338262e

jenweber force-pushed the templates branch from 0cb74b5 to 338262e Compare March 7, 2019 03:22

jenweber changed the title ~~Rough draft of new Templates intro~~ New Templates intro Mar 7, 2019

jenweber added needs a reviewer and removed wip - work in progress labels Mar 7, 2019

pzuraq approved these changes Mar 7, 2019

View reviewed changes

jenweber added 4 commits March 7, 2019 00:23

fix links

18eda07

fix links

6f9f89d

more linting

c3168d6

really actually fix the link?

6afb535

Jen Weber and others added 4 commits March 7, 2019 01:26

Merge branch 'master' into templates

d0de32e

fix hbs syntax highlighting

05fc27e

code block spacing

7fab37f

Merge branch 'templates' of github.com:ember-learn/guides-source into…

cf68c1e

… templates

jenweber merged commit 66463f2 into master Mar 7, 2019

jenweber deleted the templates branch March 7, 2019 06:46

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New Templates intro #477

New Templates intro #477

jenweber commented Feb 18, 2019 •

edited

Loading

jenweber commented Feb 18, 2019

ppcano left a comment

ppcano Feb 19, 2019

ppcano Feb 19, 2019

ppcano Feb 19, 2019

ppcano Feb 19, 2019

ppcano Feb 19, 2019

ppcano Feb 19, 2019

ppcano Feb 19, 2019

ppcano Feb 19, 2019

ppcano Feb 19, 2019

pzuraq Feb 20, 2019

locks commented Feb 19, 2019

locks left a comment

locks Feb 19, 2019

locks Feb 19, 2019

locks Feb 19, 2019

pzuraq Feb 20, 2019

locks Feb 19, 2019

pzuraq left a comment

pzuraq Feb 20, 2019

pzuraq Feb 20, 2019

jenweber commented Mar 7, 2019 •

edited

Loading

jenweber commented Mar 7, 2019


		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.


		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}


		### Helpers
		```javascript {data-filename=app/components/my-component.js}


		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:


		## 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]().


		Learn more about passing data between Templates in [../../components/passing-properties-to-a-component].

		## Helper functions

New Templates intro #477

New Templates intro #477

Conversation

jenweber commented Feb 18, 2019 • edited Loading

jenweber commented Feb 18, 2019

ppcano left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

locks commented Feb 19, 2019

locks left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pzuraq left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jenweber commented Mar 7, 2019 • edited Loading

jenweber commented Mar 7, 2019

jenweber commented Feb 18, 2019 •

edited

Loading

jenweber commented Mar 7, 2019 •

edited

Loading