You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: guides/writing-addons/index.md
+6-6Lines changed: 6 additions & 6 deletions
Original file line number
Diff line number
Diff line change
@@ -18,15 +18,15 @@ The result is the creation of a directory called `<addon-name>`, which has many
18
18
19
19
### Addon file structure
20
20
21
-
In some ways, an addon is like a mini Ember app. It has a very similar file structure, uses a lot of the same API methods, and can do most things that components are able to do.
21
+
In some ways, an addon is like a mini Ember app. It has a very similar file structure, uses a lot of the same API methods, and can do most things that components are able to do.
22
22
23
-
Let's take a look a some of the most important files and folders in an addon, and how they are different from what we would find in an app.
23
+
Let's take a look a some of the most important files and folders in an addon, and how they are different from what we would find in an app.
24
24
25
-
#### `addon/`
25
+
#### `addon/`
26
26
27
27
This directory can hold many of the same subdirectories and files that an Ember app would, like `/components/` and `/templates/`. For developers who are making components, most of the work will happen here.
28
28
29
-
#### `app/`
29
+
#### `app/`
30
30
31
31
The `app` directory plays an important role to help an Ember app automatically discover the components exported by an addon.
32
32
The default way to make a component is to put the implementation in `addon/`, which allows developers to import and extend the addon component. However, Ember apps always look for components within the `app` namespace, so we must re-export our components from `app/`.
@@ -36,9 +36,9 @@ Fortunately, when we run `ember generate component my-component-name` in an addo
36
36
#### `tests/dummy/`
37
37
This directory contains a full Ember app for addon testing purposes. During tests, we can check to make sure that the addon works or looks as expected when it is used in an app. Many addon developers use the dummy app to hold their documentation site's content as well.
38
38
39
-
#### `package.json`
39
+
#### `package.json`
40
40
41
-
If we want other people to be able to use our addon, we need to specify a name, license, version, the repository url, and description. For an addon to show up on [https://emberobserver.com](Ember Observer), it must have `keywords: ["ember-addon"]` and a repository URL.
41
+
If we want other people to be able to use our addon, we need to specify a name, license, version, the repository url, and description. For an addon to show up on [Ember Observer](https://emberobserver.com), it must have `keywords: ["ember-addon"]` and a repository URL.
Copy file name to clipboardExpand all lines: guides/writing-addons/tutorial.md
+13-13Lines changed: 13 additions & 13 deletions
Original file line number
Diff line number
Diff line change
@@ -50,14 +50,14 @@ Our goal is to be able to pass the `buttonName` value to the addon, just like we
50
50
51
51
### Trying out the addon template in an app
52
52
53
-
There are several options to see the addon in action. We could use `npm link` or `yarn link` to try it out locally or publish the addon online. We'll use `link` while we are still developing and testing.
53
+
There are several options to see the addon in action. We could use `npm link` or `yarn link` to try it out locally or publish the addon online. We'll use `link` while we are still developing and testing.
54
54
55
-
**From the addon project directory:**
55
+
**From the addon project directory:**
56
56
1. Since our addon uses a template, we need the template precompiler to be a `dependency` and not a `devDependency`. In the addon's `package.json`, move the entry for `ember-cli-htmlbars` into the `dependencies` listing. If this step is missed, there is a clear error message when we try to start the app that uses our addon.
57
57
2.`yarn install` or `npm install`
58
58
3. Run the command `yarn link` or `npm link`
59
59
60
-
**From the directory of the app using the addon:**
60
+
**From the directory of the app using the addon:**
61
61
1.`yarn link <addon-name>` or `npm link <addon-name>`.
62
62
2. In the Ember app's `package.json`, add a `devDependencies` entry for your addon, like `"addon-name": "*"`. The `*` means that it will include all version numbers of our addon.
63
63
3. Run `yarn install` or `npm install` in the app
@@ -67,17 +67,17 @@ There are several options to see the addon in action. We could use `npm link` or
67
67
We should now see our addon in action!
68
68
69
69
**Having problems?**
70
-
- Check to make sure that your `package.json` is valid, looking for missing commas or trailing commas.
71
-
- "Template precompiler" errors mean that you skipped Step 1 and 2 above.
72
-
-`404 not found` means we forgot to `yarn` or `npm install`
70
+
- Check to make sure that your `package.json` is valid, looking for missing commas or trailing commas.
71
+
- "Template precompiler" errors mean that you skipped Step 1 and 2 above.
72
+
-`404 not found` means we forgot to `yarn` or `npm install`
73
73
- Make sure all the files have been saved.
74
-
- Did you rename or relocate any files after they were created? This is prone to mistakes, and the resulting errors can be really strange. It is best to create files using the CLI.
74
+
- Did you rename or relocate any files after they were created? This is prone to mistakes, and the resulting errors can be really strange. It is best to create files using the CLI.
75
75
76
76
### Making a UI component available in block form
77
77
78
78
In an Ember app, components can be used in ["simple" or "block" form](https://guides.emberjs.com/release/components/wrapping-content-in-a-component/). Addon templates have the same capabilities. The simple form allows data objects or configuration values to be passed to the addon. The block form allows a developer to pass in their own template, content, and interactivity.
79
79
80
-
In an Ember app, a block style component uses the `{{yield}}` helper as a placeholder for where the passed-in content will go. It is the same in an Ember addon.
80
+
In an Ember app, a block style component uses the `{{yield}}` helper as a placeholder for where the passed-in content will go. It is the same in an Ember addon.
81
81
82
82
Let's change our button addon we made earlier so that developers can pass in their own handlebars content by using the `{{yield}}` helper:
83
83
@@ -141,9 +141,9 @@ Now any buttons made using our addon will have the `padding: 10px` rule applied.
141
141
142
142
For some addons, it makes sense to give the developer the option to import the stylesheet we provide, or import no stylesheets at all. Using this approach, we could even offer the developer a few themes to choose from.
143
143
144
-
We can do this by creating stylesheets in the `app/styles/` directory instead. These stylesheets share a file namespace with the consuming app and all the other addons someone is using, so name them wisely. For example, if we name our stylesheet `addon.css`, that's likely to clash. Just as before, it's important to choose uniquely named targets for the CSS rules so that they don't clash with other addons or the app.
144
+
We can do this by creating stylesheets in the `app/styles/` directory instead. These stylesheets share a file namespace with the consuming app and all the other addons someone is using, so name them wisely. For example, if we name our stylesheet `addon.css`, that's likely to clash. Just as before, it's important to choose uniquely named targets for the CSS rules so that they don't clash with other addons or the app.
145
145
146
-
Let's create `app/styles/our-addon-name.css` and add a rule to it:
146
+
Let's create `app/styles/our-addon-name.css` and add a rule to it:
147
147
148
148
```css
149
149
/* addon/styles/our-addon-name.css */
@@ -175,7 +175,7 @@ The best way to learn how to use CSS preprocessors in your addon is to consult t
175
175
There are two main types of JavaScript functionality that an addon can provide:
176
176
177
177
1. API methods that developers can use after importing your addon
178
-
2. Interactive features that are part of UI components.
178
+
2. Interactive features that are part of UI components.
179
179
180
180
We'll cover UI use cases first.
181
181
@@ -250,7 +250,7 @@ This is a very tiny example of what addons can do in terms of providing JavaScri
250
250
251
251
## In-repo addons
252
252
253
-
If the addon is just meant to be used in a single project, an "in-repo" addon could be created instead. The benefits are that it is lightweight and the developer has access addon APIs, like adding packages and commands. However, there are some major limitations: an in-repo addon can't be shared between apps, versioned independently, or published to npm.
253
+
If the addon is just meant to be used in a single project, an "in-repo" addon could be created instead. The benefits are that it is lightweight and the developer has access addon APIs, like adding packages and commands. However, there are some major limitations: an in-repo addon can't be shared between apps, versioned independently, or published to npm.
254
254
255
255
From within an existing Ember app, create an in-repo addon:
256
256
@@ -268,7 +268,7 @@ The most common use case for an in-repo addon is when there is a chance a compon
268
268
269
269
## Documenting addons
270
270
271
-
For other developers to discover and use our addon, we need to teach them how to use it!
271
+
For other developers to discover and use our addon, we need to teach them how to use it!
272
272
273
273
Here are the most common ways that addons provide user-facing documentation:
0 commit comments