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 behaviour 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 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): 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])

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

Property Summary

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
addBowerPackagesToProject(packages, installOptions): Promise

Used to add an array of packages to the projects bower.json.

public
addBowerPackageToProject(localPackageName, target, installOptions): Promise

Used to add a package to the projects bower.json.

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( ): 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)
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, analytics, 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

private
_locals(options): Object
private
private
_process(options, beforeHook, process, afterHook)
private
private
_writeStatusToUI(chalkColor, keyword, message)

Write a status and message to the UI

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
isFile(info): Promise
private
isFilePath(fileInfo): Promise
private
private
isValidFile(fileInfo): Promise
private
private
private
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:1390

public static defaultLookupPaths: Unknown

lib/models/blueprint.js:1372

public static ignoredFiles: Unknown

lib/models/blueprint.js:1380

public static ignoredUpdateFiles: Unknown

lib/models/blueprint.js:1357

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:1308

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:1281

public static load(blueprintPath): Blueprint

Loads a blueprint from given path.

Parameters:

Name Type Attribute Description
blueprintPath String

Return:

Blueprint

blueprint instance

lib/models/blueprint.js:1251

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

Return:

Public Constructors

lib/models/blueprint.js:33

public Blueprint([blueprintPath])

Parameters:

Name Type Attribute Description
blueprintPath String
  • optional

Private Properties

Actions lookup

Public Methods

lib/models/blueprint.js:1066

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:1046

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:1011

public addBowerPackagesToProject(packages, installOptions): Promise

Used to add an array of packages to the projects bower.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, or a source to specify a non-local name to be resolved.

Parameters:

Name Type Attribute Description
packages Array
installOptions Object

Return:

lib/models/blueprint.js:970

public addBowerPackageToProject(localPackageName, target, installOptions): Promise

Used to add a package to the projects bower.json.

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

localPackageName and target may be thought of as equivalent to the key-value pairs in the dependency or devDepencency objects contained within a bower.json file.

Parameters:

Name Type Attribute Description
localPackageName String
target String
installOptions Object

Return:

Example:

addBowerPackageToProject('jquery', '~1.11.1');
addBowerPackageToProject('old_jquery', 'jquery#~1.9.1');
addBowerPackageToProject('bootstrap-3', 'https://twitter.github.io/bootstrap/assets/bootstrap');
lib/models/blueprint.js:868

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:846

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:491

public afterInstall( ): Promise | Null

Hook for running operations after install.

Return:

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

public afterUninstall( ): Promise | Null

Hook for running operations after uninstall.

Return:

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

public beforeInstall( ): Promise | Null

Hook for running operations before install.

Return:

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

public beforeUninstall( ): Promise | Null

Hook for running operations before uninstall.

Return:

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

public buildFileInfo(destPath, templateVariables, file): FileInfo

Parameters:

Name Type Attribute Description
destPath Function
templateVariables Object
file String

Return:

FileInfo
lib/models/blueprint.js:547

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

Used to retrieve files for blueprint.

Return:

Array

Contents of the blueprint's files directory

lib/models/blueprint.js:214

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:624

public generateFileMap(fileMapVariables): Object

Used to generate fileMap tokens for mapFile.

Parameters:

Name Type Attribute Description
fileMapVariables Object

Return:

lib/models/blueprint.js:1130

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:420

public install(options): Promise

Parameters:

Name Type Attribute Description
options Object

Return:

lib/models/blueprint.js:660

public isUpdate( ): Boolean

Return:

lib/models/blueprint.js:514

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

The object passed to locals looks like this:

{
  entity: {
    name: 'foo',
    options: {
      type: 'array'
    }
  },
  dryRun: true
}

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:1234

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:755

public mapFile(file, locals): String

Parameters:

Name Type Attribute Description
file String
locals Object

Return:

lib/models/blueprint.js:260

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:719

public processFiles(intoDir, templateVariables)

Parameters:

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

public processFilesForUninstall(intoDir, templateVariables)

Parameters:

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

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:934

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:251

public srcPath(file): String

Parameters:

Name Type Attribute Description
file String

Return:

String

Resolved path to the file

lib/models/blueprint.js:1112

public taskFor(dasherizedName)

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

Parameters:

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

public uninstall(options): Promise

Parameters:

Name Type Attribute Description
options Object

Return:

Private Methods

lib/models/blueprint.js:706

private _checkForNoMatch(fileInfos, rawArgs)

Parameters:

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

private _checkForPod( )

Prints warning for pod unsupported.

lib/models/blueprint.js:386

private _checkInRepoAddonExists(inRepoAddon)

Parameters:

Name Type Attribute Description
inRepoAddon String
lib/models/blueprint.js:344

private _commit(result): Promise

Calls an action.

Parameters:

Name Type Attribute Description
result Object

Return:

Throws:

lib/models/blueprint.js:575

private _fileMapTokens(options): Object

Parameters:

Name Type Attribute Description
options Object

Return:

lib/models/blueprint.js:784

private _generateFileMapVariables(moduleName, locals, options): Object

Parameters:

Name Type Attribute Description
moduleName String
locals Object
options Object

Return:

lib/models/blueprint.js:670

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:693

private _getFilesForInstall(targetFiles): Array

Parameters:

Name Type Attribute Description
targetFiles Array

Return:

Array

files

lib/models/blueprint.js:682

private _ignoreUpdateFiles( )

Add update files to ignored files

lib/models/blueprint.js:813

private _locals(options): Object

Parameters:

Name Type Attribute Description
options Object

Return:

lib/models/blueprint.js:375

private _normalizeEntityName(entity)

Parameters:

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

private _process(options, beforeHook, process, afterHook)

Parameters:

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

private _writeFile(info): Promise

Parameters:

Name Type Attribute Description
info Object

Return:

lib/models/blueprint.js:280

private _writeStatusToUI(chalkColor, keyword, message)

Write a status and message to the UI

Parameters:

Name Type Attribute Description
chalkColor Function
keyword String
message String

Return:

Array

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

lib/models/blueprint.js:1433

private gatherConfirmationMessages(collection, info): Array

Parameters:

Name Type Attribute Description
collection Array
info FileInfo

Return:

lib/models/blueprint.js:1469

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:1553

private getDetailedHelpPath(thisPath): String

Parameters:

Name Type Attribute Description
thisPath String

Return:

String

help path

lib/models/blueprint.js:1484

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:1447

private isFile(info): Promise

Parameters:

Name Type Attribute Description
info FileInfo

Return:

lib/models/blueprint.js:1530

private isFilePath(fileInfo): Promise

Parameters:

Name Type Attribute Description
fileInfo Object

Return:

lib/models/blueprint.js:1457

private isIgnored(info): Boolean

Parameters:

Name Type Attribute Description
info FileInfo

Return:

lib/models/blueprint.js:1516

private isValidFile(fileInfo): Promise

Parameters:

Name Type Attribute Description
fileInfo Object

Return:

lib/models/blueprint.js:1413

private markIdenticalToBeSkipped(info)

Parameters:

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

private markToBeRemoved(info)

Parameters:

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

private prepareConfirm(info): Promise

Parameters:

Name Type Attribute Description
info FileInfo

Return:

lib/models/blueprint.js:772

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: