Series: Making ember-cli Addons

Addon Blueprints

Published on Apr 01, 2016

Your addon can include generator blueprints- tools to help your users generate files.

Find out how to make blueprints, and discover the special blueprint that runs when you run ember install.


Links

Code

You can generate a blueprint:

ember g blueprint random-blueprint

Any files in blueprints/blueprint-name/files/ will be generated when you run the blueprint.

If you have a underscores surrounding something, it's a variable.

If the blueprint has the same name as the addon, it will be run during ember install.

Transcript

In the last couple of episodes, we’ve been talking about creating your own addons. And the example we’ve been giving is a component that you can include in the app that is using the addon. However, there are plenty of more examples of things that you can do with addons. And in this episode, we’ll begin to take a look at some of the tools you can use to do more than just include a class. In this particular case, we’ll be talking about blueprints and generators. And if you look at an addon, you’ll be able to see those under the blueprints folder.

So to start with one of those, we go into our addon folder and we say ember g blueprint. So here we’re using a blueprint to create a blueprint. And then we give it the name, so here, random-blueprint. And so what that’s going to do is it’s going to generate a file for us, and currently it’s just one file, index.js. Now index.js is sort of the nerve center of a blueprint, but we’re not going to get into it much today, because what we’re concerned about today is being able to generate files. So for example, when we did ember g blueprint random blueprint, it generated index.js for us, and we want to be able to generate files with our blueprint. So we’re going to look at some that have already been done.

So here we have a pac-man-level. Of course we have our index.js which isn’t doing much, and then we have files folder, and within that files folder are things that are going to be generated by the blueprint.

So here we have _root_. Anything with two underscores on either side is a variable, and so here it’s the root variable. In most places, that’ll be called app. And then the models folder, and then _name_. And this is the name that we give it. For example when we generated random-blueprint, the name was random-blueprint. Then what we generate here is fairly straightforward as a JavaScript file. You can put in variables and such there, and if you want to do that, then episodes 36 and 37 will help you do that. So to review, within your blueprint, anything within files/_root_ will be put into your app when you run the generator.

So let’s go ahead and we’ll go to another app that is using pacman. And so we'll ember g pac-man-level and my-screencast-level because I’m making it with you guys. So it creates a file in app/models/my-screencast-level. And when we go there, we can see that it has indeed been created. Great job everyone. And then of course we can change it however we want. And if you’re curious on how we’re going to change it, we’ll be going over that in the next screencast.

Anyways, back to blueprints. So we see that it gets put here if it’s being run in a consuming app. But what if it’s run in another addon? So let’s try that. So ember g pac-man-level, and we’ll see where this puts it. So it creates two files. It creates one in the addon, addon/models/try-it-here, and you remember this is pretty much the same path that it was before except it used to be app/model/try-it-here. And then the second one that’s being created is app/pac-man-levels/try-it-here. So here instead of putting it in models, it’s putting it in the name of the generator.

So that’s something you’ll be aware of if you’re generating stuff from blueprints within your addon. Normally with all the built-in ones that’s great, because let’s say we’re using ember g model, and then it’s going to put it in models in both places, and that’s awesome, and it’ll give us the separation that we had last time where we put most of it in addon/models, and then we import/export in app/models, so that the consuming app can use it without having to generate their own model. So that typically works great as I said, but be careful when you’re doing something like this.

Alright, so we’ve looked at one of our examples. What about our other example? Well, a lot of it is very similar. It has stuff in files/_root_, and then it generates something. What makes this blueprint different is that it has the same name as the addon itself. So it not only gets run when you run ember g pac-man, it also runs when you call ember install pac-man. And so it will run whenever you’re installing the addon from npm if you’re using ember install.

So that’s a great time to put in stuff that needs to be in the app or is commonly over-writable. In this case, we’re expecting people to overwrite a lot of levels and to create the new ones, so we go ahead and import the defaults, put them there, and we’re giving them this file so they have a great place to put their new levels.

So to review from this episode, you can create blueprints within your addon, and those blueprints will be included in whatever app you put that addon in. And so here we can create a pac-man-level by calling ember g pac-man-level, and then giving that level a name. Within the blueprints folder, there are several things that we can do. There we have the index.js which is the nerve center, but we haven’t really shown what we can do with it yet. That’ll be coming in two episodes. Then we have our list of files that will be generated whenever we run generate with the blueprint. And when we have _ _ surrounding a word, that means that it’s a variable. So here we have _root_ and here we have _name_. name is what we give it, so if we call pac-man-level and we give it the name my screencast level, it will create here my-screencast-level.js.

So these are all run whenever you call ember generate, or ember g for short, and then the name of the generator. But there’s a special case for a generator that has the same name as the addon. These will be run whenever you install the addon with Ember install.

So that’s it for this level. Join us next time as we go over the pacman addon and we show how to create your own custom level in pacman using that addon. I'll see you then.

Making ember-cli Addons

Subscribe to our mailing list