Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions guides/reference/windows.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ the Administrators group must run their shell using Run As Administrator
because UAC strips away certain permissions from the Administrators +group,
including `SeCreateSymbolicLinkPrivilege`.

![Run As Administrator]({{ site.url }}/assets/images/common-issues/run-as-admin.png)
![Run As Administrator](/assets/images/run-as-admin.png)

If the user account is not part of the Administrators group you will need to
add the `SeCreateSymbolicLinkPrivilege` to allow the creation of symlinks. To
Expand All @@ -66,7 +66,7 @@ group has been added, your user should be able to create symlinks. Keep in mind
if your user is part of the Administrators group and UAC is enabled you will
still need to start your shell using `Run as Administrator`.

![Enabling Symlinks]({{ site.url }}/assets/images/common-issues/enabling-symlinks.png)
![Enabling Symlinks](/assets/images/enabling-symlinks.png)

### Issues With npm: `EEXISTS`, Path too Long, etc

Expand Down
12 changes: 6 additions & 6 deletions guides/writing-addons/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,15 +18,15 @@ The result is the creation of a directory called `<addon-name>`, which has many

### Addon file structure

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

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

#### `addon/`
#### `addon/`

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.

#### `app/`
#### `app/`

The `app` directory plays an important role to help an Ember app automatically discover the components exported by an addon.
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/`.
Expand All @@ -36,9 +36,9 @@ Fortunately, when we run `ember generate component my-component-name` in an addo
#### `tests/dummy/`
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.

#### `package.json`
#### `package.json`

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

#### `config/ember-try.js`

Expand Down
26 changes: 13 additions & 13 deletions guides/writing-addons/tutorial.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,14 +50,14 @@ Our goal is to be able to pass the `buttonName` value to the addon, just like we

### Trying out the addon template in an app

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

** From the addon project directory:**
**From the addon project directory:**
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.
2. `yarn install` or `npm install`
3. Run the command `yarn link` or `npm link`

** From the directory of the app using the addon:**
**From the directory of the app using the addon:**
1. `yarn link <addon-name>` or `npm link <addon-name>`.
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.
3. Run `yarn install` or `npm install` in the app
Expand All @@ -67,17 +67,17 @@ There are several options to see the addon in action. We could use `npm link` or
We should now see our addon in action!

**Having problems?**
- Check to make sure that your `package.json` is valid, looking for missing commas or trailing commas.
- "Template precompiler" errors mean that you skipped Step 1 and 2 above.
- `404 not found` means we forgot to `yarn` or `npm install`
- Check to make sure that your `package.json` is valid, looking for missing commas or trailing commas.
- "Template precompiler" errors mean that you skipped Step 1 and 2 above.
- `404 not found` means we forgot to `yarn` or `npm install`
- Make sure all the files have been saved.
- 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.
- 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.

### Making a UI component available in block form

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.

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

Let's change our button addon we made earlier so that developers can pass in their own handlebars content by using the `{{yield}}` helper:

Expand Down Expand Up @@ -141,9 +141,9 @@ Now any buttons made using our addon will have the `padding: 10px` rule applied.

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.

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

Let's create `app/styles/our-addon-name.css` and add a rule to it:
Let's create `app/styles/our-addon-name.css` and add a rule to it:

```css
/* addon/styles/our-addon-name.css */
Expand Down Expand Up @@ -175,7 +175,7 @@ The best way to learn how to use CSS preprocessors in your addon is to consult t
There are two main types of JavaScript functionality that an addon can provide:

1. API methods that developers can use after importing your addon
2. Interactive features that are part of UI components.
2. Interactive features that are part of UI components.

We'll cover UI use cases first.

Expand Down Expand Up @@ -250,7 +250,7 @@ This is a very tiny example of what addons can do in terms of providing JavaScri

## In-repo addons

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

From within an existing Ember app, create an in-repo addon:

Expand All @@ -268,7 +268,7 @@ The most common use case for an in-repo addon is when there is a chance a compon

## Documenting addons

For other developers to discover and use our addon, we need to teach them how to use it!
For other developers to discover and use our addon, we need to teach them how to use it!

Here are the most common ways that addons provide user-facing documentation:

Expand Down
Binary file added public/assets/images/enabling-symlinks.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added public/assets/images/run-as-admin.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.