Skip to content

Commit b716a23

Browse files
AndriyTykhanatykhan-amplifyijlee2
authored
Add links for learning more (part 2 of 4) (#166)
* Add links to learn more part 2 * Updated links in 04-component-basics * Updated links in 05-more-about-components * Updated links in 06-interactive-components Co-authored-by: andrii-amplify <atykhan@amplify.com> Co-authored-by: ijlee2 <ijlee2@users.noreply.github.com>
1 parent d435e7e commit b716a23

File tree

3 files changed

+20
-20
lines changed

3 files changed

+20
-20
lines changed

src/markdown/tutorial/part-1/04-component-basics.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
ember server
55
```
66

7-
In this chapter, you will *[refactor][TODO: link to refactor]* your existing templates to use components. We will also be adding a site-wide navigation bar:
7+
In this chapter, you will *[refactor](../../../components/introducing-components/#toc_breaking-it-into-pieces)* your existing templates to use components. We will also be adding a site-wide navigation bar:
88

99
![The Super Rentals app by the end of the chapter](/images/tutorial/part-1/component-basics/index-with-nav@2x.png)
1010

@@ -20,7 +20,7 @@ In doing so, you will learn about:
2020

2121
## Extracting Markup into Components
2222

23-
In a [previous chapter](../building-pages/), we got a light introduction to *[components][TODO: link to components]* when using `<LinkTo>` to connect our pages. To recap, we said that components are Ember's way of creating *[custom tags][TODO: link to custom tags]* to supplement the built-in HTML tags from the browser. Now, we are going to create our own components!
23+
In a [previous chapter](../building-pages/), we got a light introduction to *[components](../../../components/introducing-components/)* when using `<LinkTo>` to connect our pages. To recap, we said that components are Ember's way of creating *[custom tags][TODO: link to custom tags]* to supplement the built-in HTML tags from the browser. Now, we are going to create our own components!
2424

2525
During the course of developing an app, it is pretty common to reuse the same UI element across different parts of the app. For example, we have been using the same "jumbo" header in all three pages so far. On every page we worked to follow the same basic structure:
2626

@@ -54,7 +54,7 @@ That's it, we have created our first component! We can now *[invoke][TODO: link
5454
5555
## Passing Content to Components with `{{yield}}`
5656

57-
When invoking a component, Ember will replace the component tag with the content found in the component's template. Just like regular HTML tags, it is common to pass *[content][TODO: link to content]* to components, like `<Jumbo>some content</Jumbo>`. We can enable this using the `{{yield}}` keyword, which will be replaced with the content that was passed to the component.
57+
When invoking a component, Ember will replace the component tag with the content found in the component's template. Just like regular HTML tags, it is common to pass *[content](../../../components/block-content/)* to components, like `<Jumbo>some content</Jumbo>`. We can enable this using the `{{yield}}` keyword, which will be replaced with the content that was passed to the component.
5858

5959
Let's try it out by editing the index template:
6060

@@ -72,7 +72,7 @@ Let's try it out by editing the index template:
7272

7373
## Refactoring Existing Code
7474

75-
After saving the changes, your page should automatically reload, and, *voilà*... nothing changed? Well, that's exactly what we wanted to happen this time! We successfully *[refactored][TODO: link to refactored]* our index template to use the `<Jumbo>` component, and everything still works as expected. And the tests still pass!
75+
After saving the changes, your page should automatically reload, and, *voilà*... nothing changed? Well, that's exactly what we wanted to happen this time! We successfully *[refactored](../../../components/introducing-components/#toc_breaking-components-down-further)* our index template to use the `<Jumbo>` component, and everything still works as expected. And the tests still pass!
7676

7777
```run:screenshot width=1024 retina=true filename=index.png alt="Index page – nothing changed"
7878
visit http://localhost:4200/?deterministic
@@ -139,7 +139,7 @@ visit http://localhost:4200/tests?nocontainer&nolint&deterministic
139139
wait #qunit-banner.qunit-pass
140140
```
141141

142-
While it may not save you a lot of characters in this case, *[encapsulating][TODO: link to encapsulating]* the implementation of the "jumbo" header into its own component makes the template slightly easier to read, as it allows the reader to focus on things that are unique to just that page. Further, if we need to make a change to the header, we can make it in a single place. Feel free to give that a try!
142+
While it may not save you a lot of characters in this case, *[encapsulating](../../../components/component-arguments-and-html-attributes/)* the implementation of the "jumbo" header into its own component makes the template slightly easier to read, as it allows the reader to focus on things that are unique to just that page. Further, if we need to make a change to the header, we can make it in a single place. Feel free to give that a try!
143143

144144
## Writing Component Tests
145145

@@ -153,7 +153,7 @@ ember generate component-test jumbo
153153
git add tests/integration/components/jumbo-test.js
154154
```
155155

156-
Here, we used the generator to generate a *[component test][TODO: link to component test]*, also known as a *[rendering test][TODO: link to rendering test]*. These are used to render and test a single component at a time. This is in contrast to the acceptance tests that we wrote earlier, which have to navigate and render entire pages worth of content.
156+
Here, we used the generator to generate a *[component test](../../../testing/testing-components/)*, also known as a rendering test. These are used to render and test a single component at a time. This is in contrast to the acceptance tests that we wrote earlier, which have to navigate and render entire pages worth of content.
157157

158158
Let's replace the boilerplate code that was generated for us with our own test:
159159

@@ -354,7 +354,7 @@ While we are at it, we will also add a container element that wraps around the w
354354
<Jumbo>
355355
```
356356

357-
The `{{outlet}}` keyword denotes the place where our site's pages should be rendered into, similar to the `{{yield}}` keyword we saw [earlier][TODO: add anchor link back to where we first mentioned it].
357+
The `{{outlet}}` keyword denotes the place where our site's pages should be rendered into, similar to the `{{yield}}` keyword we saw [earlier](#toc_passing-content-to-components-with-yield).
358358

359359
This is much nicer! We can run our test suite, which confirms that everything still works after our refactor. We are ready to move on to the next feature!
360360

src/markdown/tutorial/part-1/05-more-about-components.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,7 @@ Let's edit the component's template:
162162
+</div>
163163
```
164164
165-
Instead of hard-coding specific values for the `src` and `alt` attributes on the `<img>` tag, we opted for the `...attributes` keyword instead, which is also sometimes referred to as the *["splattributes"][TODO: link to splattributes]* syntax. This allows arbitrary HTML attributes to be passed in when invoking this component, like so:
165+
Instead of hard-coding specific values for the `src` and `alt` attributes on the `<img>` tag, we opted for the `...attributes` keyword instead, which is also sometimes referred to as the *["splattributes"](../../../components/component-arguments-and-html-attributes/#toc_html-attributes)* syntax. This allows arbitrary HTML attributes to be passed in when invoking this component, like so:
166166
167167
```run:file:patch lang=handlebars cwd=super-rentals filename=app/components/rental.hbs
168168
@@ -1,2 +1,6 @@

src/markdown/tutorial/part-1/06-interactive-components.md

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,11 @@ While doing so, you will learn about:
2626

2727
So far, all the components we have written are purely *[presentational][TODO: link to presentational]*&mdash;they are simply reusable snippets of markup. That's pretty cool! But in Ember, components can do so much more.
2828

29-
Sometimes, you want to associate some *[behavior][TODO: link to behavior]* with your components so that they can do more interesting things. For example, `<LinkTo>` can respond to clicks by changing the URL and navigating us to a different page.
29+
Sometimes, you want to associate some *[behavior](https://developer.mozilla.org/docs/Learn/JavaScript/Building_blocks/Events)* with your components so that they can do more interesting things. For example, `<LinkTo>` can respond to clicks by changing the URL and navigating us to a different page.
3030

3131
Here, we are going to do just that! We are going to implement the "View Larger" and "View Smaller" functionality, which will allow our users to click on a property's image to view a larger version, and click on it again to return to the smaller version.
3232

33-
In other words, we want a way to *toggle* the image between one of the two *[states][TODO: link to states]*. In order to do that, we need a way for the component to store two possible states, and to be aware of which state it is currently in.
33+
In other words, we want a way to *toggle* the image between one of the two *[states](../../../components/component-state-and-actions/)*. In order to do that, we need a way for the component to store two possible states, and to be aware of which state it is currently in.
3434

3535
Ember optionally allows us to associate JavaScript code with a component for exactly this purpose. We can add a JavaScript file for our `<Rental::Image>` component by running the `component-class` generator:
3636

@@ -43,13 +43,13 @@ ember test --path dist
4343
git add app/components/rental/image.js
4444
```
4545

46-
This generated a JavaScript file with the same name as our component's template at `app/components/rentals/image.js`. It contains a *[JavaScript class][TODO: link to JavaScript class]*, *[inheriting][TODO: link to inheriting]* from `@glimmer/component`.
46+
This generated a JavaScript file with the same name as our component's template at `app/components/rental/image.js`. It contains a *[JavaScript class](https://javascript.info/class)*, *[inheriting](https://javascript.info/class-inheritance)* from `@glimmer/component`.
4747

4848
> Zoey says...
4949
>
50-
> `@glimmer/component`, or *[Glimmer component][TODO: link to Glimmer component]*, is one of the several component classes available to use. They are a great starting point whenever you want to add behavior to your components. In this tutorial, we will be using Glimmer components exclusively.
50+
> `@glimmer/component`, or *[Glimmer component](../../../upgrading/current-edition/glimmer-components/)*, is one of the several component classes available to use. They are a great starting point whenever you want to add behavior to your components. In this tutorial, we will be using Glimmer components exclusively.
5151
>
52-
> In general, Glimmer components should be used whenever possible. However, you may also see `@ember/components`, or *[classic components][TODO: link to classic components]*, used in older apps. You can tell them apart by looking at their import path (which is helpful for looking up the respective documentation, as they have different and incompatible APIs).
52+
> In general, Glimmer components should be used whenever possible. However, you may also see `@ember/components`, or *[classic components](https://ember-learn.github.io/ember-octane-vs-classic-cheat-sheet/)*, used in older apps. You can tell them apart by looking at their import path (which is helpful for looking up the respective documentation, as they have different and incompatible APIs).
5353
5454
Ember will create an *[instance][TODO: link to instance]* of the class whenever our component is invoked. We can use that instance to store our state:
5555

@@ -87,7 +87,7 @@ Let's update our template to use this state we just added:
8787
+{{/if}}
8888
```
8989

90-
In the template, we have access to the component's instance variables. The `{{#if ...}}...{{else}}...{{/if}}` *[conditionals][TODO: link to conditionals]* syntax allows us to render different content based on a condition (in this case, the value of the instance variable `this.isLarge`). Combining these two features, we can render either the small or the large version of the image accordingly.
90+
In the template, we have access to the component's instance variables. The `{{#if ...}}...{{else}}...{{/if}}` *[conditionals](../../../components/conditional-content/)* syntax allows us to render different content based on a condition (in this case, the value of the instance variable `this.isLarge`). Combining these two features, we can render either the small or the large version of the image accordingly.
9191

9292
```run:command hidden=true cwd=super-rentals
9393
ember test --path dist
@@ -140,7 +140,7 @@ Of course, our users cannot edit our source code, so we need a way for them to t
140140

141141
## Managing State with Tracked Properties
142142

143-
Let's modify our class to add a *[method][TODO: link to method]* for toggling the size:
143+
Let's modify our class to add a *[method](../../../in-depth-topics/native-classes-in-depth/#toc_methods)* for toggling the size:
144144

145145
```run:file:patch lang=js cwd=super-rentals filename=app/components/rental/image.js
146146
@@ -1,5 +1,11 @@
@@ -160,9 +160,9 @@ Let's modify our class to add a *[method][TODO: link to method]* for toggling th
160160

161161
We did a few things here, so let's break it down.
162162

163-
First, we added the `@tracked` *[decorator][TODO: link to decorator]* to the `isLarge` instance variable. This annotation tells Ember to monitor this variable for updates. Whenever this variable's value changes, Ember will automatically re-render any templates that depend on its value.
163+
First, we added the `@tracked` *[decorator](../../../in-depth-topics/native-classes-in-depth/#toc_decorators)* to the `isLarge` instance variable. This annotation tells Ember to monitor this variable for updates. Whenever this variable's value changes, Ember will automatically re-render any templates that depend on its value.
164164

165-
In our case, whenever we assign a new value to `this.isLarge`, the `@tracked` annotation will cause Ember to re-evaluate the `{{#if this.isLarge}}` conditional in our template, and will switch between the two *[blocks][TODO: link to blocks]* accordingly.
165+
In our case, whenever we assign a new value to `this.isLarge`, the `@tracked` annotation will cause Ember to re-evaluate the `{{#if this.isLarge}}` conditional in our template, and will switch between the two *[blocks](../../../components/conditional-content/#toc_block-if)* accordingly.
166166

167167
> Zoey says...
168168
>
@@ -203,7 +203,7 @@ We changed two things here.
203203

204204
First, since we wanted to make our component interactive, we switched the containing tag from `<div>` to `<button>` (this is important for accessibility reasons). By using the correct semantic tag, we will also get focusability and keyboard interaction handling "for free".
205205

206-
Next, we used the `{{on}}` *[modifier][TODO: link to modifier]* to attach `this.toggleSize` as a click handler on the button.
206+
Next, we used the `{{on}}` *[modifier](../../../components/template-lifecycle-dom-and-modifiers/#toc_event-handlers)* to attach `this.toggleSize` as a click handler on the button.
207207

208208
With that, we have created our first *[interactive][TODO: link to interactive]* component. Go ahead and try it in the browser!
209209

@@ -281,7 +281,7 @@ Let's clean up our template before moving on. We introduced a lot of duplication
281281
1. The presence of the `"large"` CSS class on the `<button>` tag.
282282
2. The "View Larger" and "View Smaller" text.
283283

284-
These changes are buried deep within the large amount of duplicated code. We can reduce the duplication by using an `{{if}}` *[expression][TODO: link to expression]* instead:
284+
These changes are buried deep within the large amount of duplicated code. We can reduce the duplication by using an `{{if}}` *[expression](../../../components/conditional-content/#toc_inline-if)* instead:
285285

286286
```run:file:patch lang=handlebars cwd=super-rentals filename=app/components/rental/image.hbs
287287
@@ -1,11 +1,8 @@
@@ -304,7 +304,7 @@ These changes are buried deep within the large amount of duplicated code. We can
304304
+</button>
305305
```
306306

307-
The expression version of `{{if}}` takes two arguments. The first argument is the *[condition][TODO: link to condition]*. The second argument is the expression that should be evaluated if the condition is true.
307+
The expression version of `{{if}}` takes two arguments. The first argument is the condition. The second argument is the expression that should be evaluated if the condition is true.
308308

309309
```run:command hidden=true cwd=super-rentals
310310
ember test --path dist

0 commit comments

Comments
 (0)