Extends:

CoreObject → Blueprint

A blueprint is a bundle of template files with optional install logic.

Blueprints follow a simple structure. Let's take the built-in controller blueprint as an example:

blueprints/controller
├── files
│   ├── app
│   │   └── __path__
│   │       └── __name__.js
└── index.js

blueprints/controller-test
├── files
│   └── tests
│       └── unit
│           └── controllers
│               └── __test__.js
└── index.js

Files

files contains templates for the all the files to be installed into the target directory.

The __name__ token is subtituted with the dasherized entity name at install time. For example, when the user invokes ember generate controller foo then __name__ becomes foo. When the --pod flag is used, for example ember generate controller foo --pod then __name__ becomes controller.

The __path__ token is substituted with the blueprint name at install time. For example, when the user invokes ember generate controller foo then __path__ becomes controller. When the --pod flag is used, for example ember generate controller foo --pod then __path__ becomes foo (or <podModulePrefix>/foo if the podModulePrefix is defined). This token is primarily for pod support, and is only necessary if the blueprint can be used in pod structure. If the blueprint does not require pod support, simply use the blueprint name instead of the __path__ token.

The __test__ token is substituted with the dasherized entity name and appended with -test at install time. This token is primarily for pod support and only necessary if the blueprint requires support for a pod structure. If the blueprint does not require pod support, simply use the __name__ token instead.

Template Variables (AKA Locals)

Variables can be inserted into templates with <%= someVariableName %>.

For example, the built-in util blueprint files/app/utils/__name__.js looks like this:

export default function <%= camelizedModuleName %>() {
  return true;
}

<%= camelizedModuleName %> is replaced with the real value at install time.

The following template variables are provided by default:

  • dasherizedPackageName
  • classifiedPackageName
  • dasherizedModuleName
  • classifiedModuleName
  • camelizedModuleName

packageName is the project name as found in the project's package.json.

moduleName is the name of the entity being generated.

The mechanism for providing custom template variables is described below.

Index.js

Custom installation and uninstallation behavior can be added by overriding the hooks documented below. index.js should export a plain object, which will extend the prototype of the Blueprint class. If needed, the original Blueprint prototype can be accessed through the _super property.

module.exports = {
  locals(options) {
    // Return custom template variables here.
    return {};
  },

  normalizeEntityName(entityName) {
    // Normalize and validate entity name here.
    return entityName;
  },

  fileMapTokens(options) {
    // Return custom tokens to be replaced in your files
    return {
      __token__(options){
        // logic to determine value goes here
        return 'value';
      }
    }
  },

  filesPath(options) {
    return path.join(this.path, 'files');
  },

  beforeInstall(options) {},
  afterInstall(options) {},
  beforeUninstall(options) {},
  afterUninstall(options) {}

};

Blueprint Hooks

beforeInstall & beforeUninstall

Called before any of the template files are processed and receives the options and locals hashes as parameters. Typically used for validating any additional command line options or for any asynchronous setup that is needed. As an example, the controller blueprint validates its --type option in this hook. If you need to run any asynchronous code, wrap it in a promise and return that promise from these hooks. This will ensure that your code is executed correctly.

afterInstall & afterUninstall

The afterInstall and afterUninstall hooks receives the same arguments as locals. Use it to perform any custom work after the files are processed. For example, the built-in route blueprint uses these hooks to add and remove relevant route declarations in app/router.js.

Overriding Install

If you don't want your blueprint to install the contents of files you can override the install method. It receives the same options object described above and must return a promise. See the built-in resource blueprint for an example of this.

Static Method Summary

Static Public Methods
public static
list([options]): Array
public static
load(blueprintPath, [blueprintOptions]): Blueprint

Loads a blueprint from given path.

public static
lookup(name, [options]): Blueprint

Static Property Summary

Static Public Properties
public static
public static
ignoredFiles: Unknown
public static
public static
renamedFiles: Unknown

Files that are renamed when installed into the target directory. This allows including files in the blueprint that would have an effect on another process, such as a file named .gitignore.

Constructor Summary

Public Constructors
public
Blueprint([blueprintPath], [blueprintOptions])

A blueprint is a bundle of template files with optional install logic.

Property Summary

Public Properties
public

Indicates whether or not a blueprint is a candidate for automatic transpilation from TS to JS. This property could be false in the case that the blueprint is written in JS and is not intended to work with TS at all, OR in the case that the blueprint is written in TS and the author does not intend to support transpilation to JS.

Private Properties
private

Actions lookup

Method Summary

Public Methods
public

Used to add multiple addons to the project's package.json and run their defaultBlueprint if they provide one.

public

Used to add an addon to the project's package.json and run it's defaultBlueprint if it provides one.

public

Used to add multiple packages to the project's package.json.

public
addPackageToProject(packageName, target): Promise

Used to add a package to the project's package.json.

public
afterInstall( ): Promise | Null

Hook for running operations after install.

public
afterUninstall( ): Promise | Null

Hook for running operations after uninstall.

public
beforeInstall( ): Promise | Null

Hook for running operations before install.

public

Hook for running operations before uninstall.

public
buildFileInfo(destPath, templateVariables, file): FileInfo
public
fileMapTokens( ): Object | Null

Hook to add additional or override existing fileMap tokens.

public
files(options): Array

Used to retrieve files for blueprint.

public
filesPath(options): String

Hook to specify the path to the blueprint's files. By default this is path.join(this.path, 'files).

public
generateFileMap(fileMapVariables): Object

Used to generate fileMap tokens for mapFile.

public
insertIntoFile(pathRelativeToProjectRoot, contentsToInsert, providedOptions): Promise

Inserts the given content into a file. If the contentsToInsert string is already present in the current contents, the file will not be changed unless force option is passed.

public
install(options): Promise
public
public
locals(options): Object | Promise | Null

Hook for adding custom template variables.

public
lookupBlueprint(dasherizedName): Blueprint

Used to retrieve a blueprint with the given name.

public
mapFile(file, locals): String
public
normalizeEntityName(entityName): Null

Hook for normalizing entity name

public
processFiles(intoDir, templateVariables): Promise
public
processFilesForUninstall(intoDir, templateVariables)
public

Used to remove a package from the project's package.json.

public

Used to remove multiple packages from the project's package.json.

public
srcPath(file): String
public
taskFor(dasherizedName)

Used to retrieve a task with the given name. Passes the new task the standard information available (like ui, project, etc).

public
uninstall(options): Promise
Private Methods
private
_checkForNoMatch(fileInfos, rawArgs)
private

Prints warning for pod unsupported.

private
private
_commit(result): Promise

Calls an action.

private
private
_generateFileMapVariables(moduleName, locals, options): Object
private
_getFileInfos(files, intoDir, templateVariables): Array
private
_getFilesForInstall(targetFiles): Array
private

Add update files to ignored files or reset them

private
_locals(options): Object
private
private
_process(options, beforeHook, process, afterHook)
private
_processOptions(options)

Process the options object coming from either the init, install or uninstall hook.

private
private
_writeStatusToUI(chalkColor, keyword, message)

Write a status and message to the UI

private
convertToJS(fileInfo): Promise
private
dir( ): Array
private
gatherConfirmationMessages(collection, info): Array
private
generateLookupPaths(lookupPaths): Array

Combines provided lookup paths with defaults and removes duplicates.

private
private

Looks for a path token in the files folder. Must be present for the blueprint to support pod tokens.

private
isFilePath(fileInfo): Promise
private
private
isValidFile(fileInfo): Promise
private
private
private
private
shouldConvertToJS(options, fileInfo): Boolean
private

Looks for a root token in the files folder. Must be present for the blueprint to support addon tokens. The server, blueprints, and test

Static Public Properties

lib/models/blueprint.js:1524

public static defaultLookupPaths: Unknown

lib/models/blueprint.js:1512

public static ignoredFiles: Unknown

lib/models/blueprint.js:1518

public static ignoredUpdateFiles: Unknown

lib/models/blueprint.js:1497

public static renamedFiles: Unknown

Files that are renamed when installed into the target directory. This allows including files in the blueprint that would have an effect on another process, such as a file named .gitignore.

The keys are the filenames used in the files folder. The values are the filenames used in the target directory.

Static Public Methods

lib/models/blueprint.js:1448

public static list([options]): Array

Parameters:

Name Type Attribute Description
options Object
  • optional
options.paths Array
  • optional

Extra paths to search for blueprints

Return:

lib/models/blueprint.js:1420

public static load(blueprintPath, [blueprintOptions]): Blueprint

Loads a blueprint from given path.

Parameters:

Name Type Attribute Description
blueprintPath String
blueprintOptions Object
  • optional

Return:

Blueprint

blueprint instance

lib/models/blueprint.js:1379

public static lookup(name, [options]): Blueprint

Parameters:

Name Type Attribute Description
name String
options Object
  • optional
options.paths Array
  • optional

Extra paths to search for blueprints

options.ignoreMissing Boolean
  • optional

Throw a SilentError if a matching Blueprint could not be found

options.blueprintOptions Object
  • optional

Options object that will be passed along to the Blueprint instance on creation.

Return:

Public Constructors

lib/models/blueprint.js:29

public Blueprint([blueprintPath], [blueprintOptions])

Parameters:

Name Type Attribute Description
blueprintPath String
  • optional
blueprintOptions Object
  • optional

Public Properties

lib/models/blueprint.js:198

public shouldTransformTypeScript: Boolean

Indicates whether or not a blueprint is a candidate for automatic transpilation from TS to JS. This property could be false in the case that the blueprint is written in JS and is not intended to work with TS at all, OR in the case that the blueprint is written in TS and the author does not intend to support transpilation to JS.

Private Properties

Actions lookup

Public Methods

lib/models/blueprint.js:1164

public addAddonsToProject(options): Promise

Used to add multiple addons to the project's package.json and run their defaultBlueprint if they provide one.

Generally, this would be done from the afterInstall hook, to ensure that a package that is required by a given blueprint is available.

Parameters:

Name Type Attribute Description
options Object

Return:

lib/models/blueprint.js:1144

public addAddonToProject(options): Promise

Used to add an addon to the project's package.json and run it's defaultBlueprint if it provides one.

Generally, this would be done from the afterInstall hook, to ensure that a package that is required by a given blueprint is available.

Parameters:

Name Type Attribute Description
options Object

Return:

lib/models/blueprint.js:1037

public addPackagesToProject(packages): Promise

Used to add multiple packages to the project's package.json.

Generally, this would be done from the afterInstall hook, to ensure that a package that is required by a given blueprint is available.

Expects each array item to be an object with a name. Each object may optionally have a target to specify a specific version.

Parameters:

Name Type Attribute Description
packages Array

Return:

Example:

this.addPackagesToProject([
  { name: 'lodash' },
  { name: 'moment', target: '^2.17.0' },
]);
lib/models/blueprint.js:1015

public addPackageToProject(packageName, target): Promise

Used to add a package to the project's package.json.

Generally, this would be done from the afterInstall hook, to ensure that a package that is required by a given blueprint is available.

Parameters:

Name Type Attribute Description
packageName String
target String

Return:

lib/models/blueprint.js:599

public afterInstall( ): Promise | Null

Hook for running operations after install.

Return:

Promise | Null
lib/models/blueprint.js:613

public afterUninstall( ): Promise | Null

Hook for running operations after uninstall.

Return:

Promise | Null
lib/models/blueprint.js:592

public beforeInstall( ): Promise | Null

Hook for running operations before install.

Return:

Promise | Null
lib/models/blueprint.js:606

public beforeUninstall( ): Promise | Null

Hook for running operations before uninstall.

Return:

Promise | Null
lib/models/blueprint.js:756

public buildFileInfo(destPath, templateVariables, file): FileInfo

Parameters:

Name Type Attribute Description
destPath Function
templateVariables Object
file String

Return:

FileInfo
lib/models/blueprint.js:657

public fileMapTokens( ): Object | Null

Hook to add additional or override existing fileMap tokens.

Use fileMapTokens to add custom fileMap tokens for use in the mapFile method. The hook must return an object in the following pattern:

{
  __token__(options){
    // logic to determine value goes here
    return 'value';
  }
}

It will be merged with the default fileMapTokens, and can be used to override any of the default tokens.

Tokens are used in the files folder (see files), and get replaced with values when the mapFile method is called.

Return:

Object | Null
lib/models/blueprint.js:252

public files(options): Array

Used to retrieve files for blueprint.

Parameters:

Name Type Attribute Description
options Object

Return:

Array

Contents of the blueprint's files directory

lib/models/blueprint.js:235

public filesPath(options): String

Hook to specify the path to the blueprint's files. By default this is path.join(this.path, 'files).

This can be used to customize which set of files to install based on options or environmental variables. It defaults to the files directory within the blueprint's folder.

Parameters:

Name Type Attribute Description
options Object

Return:

String

Path to the blueprints files directory.

lib/models/blueprint.js:741

public generateFileMap(fileMapVariables): Object

Used to generate fileMap tokens for mapFile.

Parameters:

Name Type Attribute Description
fileMapVariables Object

Return:

lib/models/blueprint.js:1258

public insertIntoFile(pathRelativeToProjectRoot, contentsToInsert, providedOptions): Promise

Inserts the given content into a file. If the contentsToInsert string is already present in the current contents, the file will not be changed unless force option is passed.

If options.before is specified, contentsToInsert will be inserted before the first instance of that string. If options.after is specified, the contents will be inserted after the first instance of that string. If the string specified by options.before or options.after is not in the file, no change will be made.

If neither options.before nor options.after are present, contentsToInsert will be inserted at the end of the file.

Example:

// app/router.js
Router.map(function () {
});
insertIntoFile('app/router.js', '  this.route("admin");', {
  after: 'Router.map(function () {' + EOL
}).then(function() {
  // file has been inserted into!
});


// app/router.js
Router.map(function () {
  this.route("admin");
});

Parameters:

Name Type Attribute Description
pathRelativeToProjectRoot String
contentsToInsert String
providedOptions Object

Return:

lib/models/blueprint.js:543

public install(options): Promise

Parameters:

Name Type Attribute Description
options Object

Return:

lib/models/blueprint.js:777

public isUpdate( ): Boolean

Return:

lib/models/blueprint.js:622

public locals(options): Object | Promise | Null

Hook for adding custom template variables.

When the following is called on the command line:

ember generate controller foo --type=array --dry-run isAdmin:true

The object passed to locals looks like this:

{
  entity: {
    name: 'foo',
    options: {
      isAdmin: true
    }
  },
  dryRun: true
  type: "array"
  // more keys
}

This hook must return an object or a Promise which resolves to an object. The resolved object will be merged with the aforementioned default locals.

Parameters:

Name Type Attribute Description
options Object

General and entity-specific options

Return:

Object | Promise | Null
lib/models/blueprint.js:1362

public lookupBlueprint(dasherizedName): Blueprint

Used to retrieve a blueprint with the given name.

Parameters:

Name Type Attribute Description
dasherizedName String

Return:

lib/models/blueprint.js:923

public mapFile(file, locals): String

Parameters:

Name Type Attribute Description
file String
locals Object

Return:

lib/models/blueprint.js:284

public normalizeEntityName(entityName): Null

Hook for normalizing entity name

Use the normalizeEntityName hook to add custom normalization and validation of the provided entity name. The default hook does not make any changes to the entity name, but makes sure an entity name is present and that it doesn't have a trailing slash.

This hook receives the entity name as its first argument. The string returned by this hook will be used as the new entity name.

Parameters:

Name Type Attribute Description
entityName String

Return:

Null
lib/models/blueprint.js:839

public processFiles(intoDir, templateVariables): Promise

Parameters:

Name Type Attribute Description
intoDir String
templateVariables Object

Return:

Promise
lib/models/blueprint.js:872

public processFilesForUninstall(intoDir, templateVariables)

Parameters:

Name Type Attribute Description
intoDir String
templateVariables Object
lib/models/blueprint.js:1086

public removePackageFromProject(packageName): Promise

Used to remove a package from the project's package.json.

Generally, this would be done from the afterInstall hook, to ensure that any package conflicts can be resolved before the addon is used.

Parameters:

Name Type Attribute Description
packageName String

Return:

lib/models/blueprint.js:1103

public removePackagesFromProject(packages): Promise

Used to remove multiple packages from the project's package.json.

Generally, this would be done from the afterInstall hook, to ensure that any package conflicts can be resolved before the addon is used.

Expects each array item to be an object with a name property.

Parameters:

Name Type Attribute Description
packages Array

Return:

lib/models/blueprint.js:275

public srcPath(file): String

Parameters:

Name Type Attribute Description
file String

Return:

String

Resolved path to the file

lib/models/blueprint.js:1241

public taskFor(dasherizedName)

Used to retrieve a task with the given name. Passes the new task the standard information available (like ui, project, etc).

Parameters:

Name Type Attribute Description
dasherizedName Object
lib/models/blueprint.js:570

public uninstall(options): Promise

Parameters:

Name Type Attribute Description
options Object

Return:

Private Methods

lib/models/blueprint.js:825

private _checkForNoMatch(fileInfos, rawArgs)

Parameters:

Name Type Attribute Description
fileInfos Array
rawArgs String
lib/models/blueprint.js:386

private _checkForPod( )

Prints warning for pod unsupported.

lib/models/blueprint.js:414

private _checkInRepoAddonExists(options)

Parameters:

Name Type Attribute Description
options Object
lib/models/blueprint.js:368

private _commit(result): Promise

Calls an action.

Parameters:

Name Type Attribute Description
result Object

Return:

Throws:

Error

Action doesn't exist.

lib/models/blueprint.js:685

private _fileMapTokens(options): Object

Parameters:

Name Type Attribute Description
options Object

Return:

lib/models/blueprint.js:952

private _generateFileMapVariables(moduleName, locals, options): Object

Parameters:

Name Type Attribute Description
moduleName String
locals Object
options Object

Return:

lib/models/blueprint.js:787

private _getFileInfos(files, intoDir, templateVariables): Array

Parameters:

Name Type Attribute Description
files Array
intoDir String
templateVariables Object

Return:

Array

file infos

lib/models/blueprint.js:812

private _getFilesForInstall(targetFiles): Array

Parameters:

Name Type Attribute Description
targetFiles Array

Return:

Array

files

lib/models/blueprint.js:799

private _ignoreUpdateFiles( )

Add update files to ignored files or reset them

lib/models/blueprint.js:982

private _locals(options): Object

Parameters:

Name Type Attribute Description
options Object

Return:

lib/models/blueprint.js:403

private _normalizeEntityName(entity)

Parameters:

Name Type Attribute Description
entity Object
lib/models/blueprint.js:443

private _process(options, beforeHook, process, afterHook)

Parameters:

Name Type Attribute Description
options Object
beforeHook Function
process Function
afterHook Function
lib/models/blueprint.js:219

private _processOptions(options)

Process the options object coming from either the init, install or uninstall hook.

Parameters:

Name Type Attribute Description
options Object
lib/models/blueprint.js:318

private _writeFile(info): Promise

Parameters:

Name Type Attribute Description
info Object

Return:

lib/models/blueprint.js:304

private _writeStatusToUI(chalkColor, keyword, message)

Write a status and message to the UI

Parameters:

Name Type Attribute Description
chalkColor Function
keyword String
message String
lib/models/blueprint.js:523

private convertToJS(fileInfo): Promise

Parameters:

Name Type Attribute Description
fileInfo FileInfo

Return:

Return:

Array

list of files in the given directory or and empty array if no directory exists

lib/models/blueprint.js:1565

private gatherConfirmationMessages(collection, info): Array

Parameters:

Name Type Attribute Description
collection Array
info FileInfo

Return:

lib/models/blueprint.js:1591

private generateLookupPaths(lookupPaths): Array

Combines provided lookup paths with defaults and removes duplicates.

Parameters:

Name Type Attribute Description
lookupPaths Array

Return:

lib/models/blueprint.js:1682

private getDetailedHelpPath(thisPath): String

Parameters:

Name Type Attribute Description
thisPath String

Return:

String

help path

lib/models/blueprint.js:1606

private hasPathToken(files): Boolean

Looks for a path token in the files folder. Must be present for the blueprint to support pod tokens.

Parameters:

Name Type Attribute Description
files Files

Return:

lib/models/blueprint.js:1659

private isFilePath(fileInfo): Promise

Parameters:

Name Type Attribute Description
fileInfo Object

Return:

lib/models/blueprint.js:1579

private isIgnored(info): Boolean

Parameters:

Name Type Attribute Description
info FileInfo

Return:

lib/models/blueprint.js:1645

private isValidFile(fileInfo): Promise

Parameters:

Name Type Attribute Description
fileInfo Object

Return:

lib/models/blueprint.js:1545

private markIdenticalToBeSkipped(info)

Parameters:

Name Type Attribute Description
info FileInfo
lib/models/blueprint.js:1556

private markToBeRemoved(info)

Parameters:

Name Type Attribute Description
info FileInfo
lib/models/blueprint.js:1532

private prepareConfirm(info): Promise

Parameters:

Name Type Attribute Description
info FileInfo

Return:

lib/models/blueprint.js:469

private shouldConvertToJS(options, fileInfo): Boolean

Parameters:

Name Type Attribute Description
options Object
fileInfo FileInfo

Return:

lib/models/blueprint.js:940

private supportsAddon( ): Boolean

Looks for a root token in the files folder. Must be present for the blueprint to support addon tokens. The server, blueprints, and test

Return: