lib/models/blueprint.js:30
Blueprint
Extends:
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 |
|
public static |
Loads a blueprint from given path. |
public static |
|
Static Property Summary
Static Public Properties | |
---|---|
public static |
defaultLookupPaths: Unknown
|
public static |
ignoredFiles: Unknown
|
public static |
ignoredUpdateFiles: Unknown
|
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 |
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 |
addAddonsToProject(options): Promise
Used to add multiple addons to the project's |
public |
addAddonToProject(options): Promise
Used to add an addon to the project's |
public |
addBowerPackagesToProject(packages, installOptions): Promise
Used to add an array of packages to the projects |
public |
addBowerPackageToProject(localPackageName, target, installOptions): Promise
Used to add a package to the projects |
public |
addPackagesToProject(packages): Promise
Used to add multiple packages to the project's |
public |
addPackageToProject(packageName, target): Promise
Used to add a package to the project's |
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 |
beforeUninstall( ): Promise | Null
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 |
Used to retrieve files for blueprint. |
public |
Hook to specify the path to the blueprint's files. By default this is |
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 |
public |
|
public |
|
public |
Hook for adding custom template variables. |
public |
lookupBlueprint(dasherizedName): Blueprint
Used to retrieve a blueprint with the given name. |
public |
|
public |
normalizeEntityName(entityName): Null
Hook for normalizing entity name |
public |
processFiles(intoDir, templateVariables): Promise
|
public |
processFilesForUninstall(intoDir, templateVariables)
|
public |
removePackageFromProject(packageName): Promise
Used to remove a package from the project's |
public |
removePackagesFromProject(packages): Promise
Used to remove multiple packages from the project's |
public |
|
public |
taskFor(dasherizedName)
Used to retrieve a task with the given name. Passes the new task the standard information available (like |
public |
|
Private Methods | |
---|---|
private |
_checkForNoMatch(fileInfos, rawArgs)
|
private |
_checkForPod( )
Prints warning for pod unsupported. |
private |
_checkInRepoAddonExists(options)
|
private |
Calls an action. |
private |
_fileMapTokens(options): Object
|
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 |
|
private |
_normalizeEntityName(entity)
|
private |
_process(options, beforeHook, process, afterHook)
|
private |
_writeFile(info): Promise
|
private |
_writeStatusToUI(chalkColor, keyword, message)
Write a status and message to the UI |
private |
|
private |
gatherConfirmationMessages(collection, info): Array
|
private |
generateLookupPaths(lookupPaths): Array
Combines provided lookup paths with defaults and removes duplicates. |
private |
getDetailedHelpPath(thisPath): String
|
private |
hasPathToken(files): Boolean
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 |
markIdenticalToBeSkipped(info)
|
private |
markToBeRemoved(info)
|
private |
prepareConfirm(info): Promise
|
private |
supportsAddon( ): Boolean
Looks for a root token in the files folder. Must be present for the blueprint to support addon tokens. The |
Static Public Properties
lib/models/blueprint.js:1401
public static defaultLookupPaths: Unknown
lib/models/blueprint.js:1389
public static ignoredFiles: Unknown
lib/models/blueprint.js:1395
public static ignoredUpdateFiles: Unknown
lib/models/blueprint.js:1374
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:1325
public static list([options]): Array
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
options | Object |
|
|
options.paths | Array |
|
Extra paths to search for blueprints |
Return:
lib/models/blueprint.js:1298
public static load(blueprintPath): Blueprint
Loads a blueprint from given path.
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
blueprintPath | String |
|
Return:
blueprint instance
lib/models/blueprint.js:1268
public static lookup(name, [options]): Blueprint
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
name | String |
|
|
options | Object |
|
|
options.paths | Array |
|
Extra paths to search for blueprints |
options.ignoreMissing | Boolean |
|
Throw a |
Return:
Public Constructors
lib/models/blueprint.js:30
public Blueprint([blueprintPath])
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
blueprintPath | String |
|
Private Properties
lib/models/blueprint.js:299
private _actions: Object
Actions lookup
Public Methods
lib/models/blueprint.js:1083
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:1063
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:1026
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.
Return:
lib/models/blueprint.js:996
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:889
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:867
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.
Return:
lib/models/blueprint.js:500
public afterInstall( ): Promise | Null
Hook for running operations after install.
Return:
lib/models/blueprint.js:514
public afterUninstall( ): Promise | Null
Hook for running operations after uninstall.
Return:
lib/models/blueprint.js:493
public beforeInstall( ): Promise | Null
Hook for running operations before install.
Return:
lib/models/blueprint.js:507
public beforeUninstall( ): Promise | Null
Hook for running operations before uninstall.
Return:
lib/models/blueprint.js:657
public buildFileInfo(destPath, templateVariables, file): FileInfo
Return:
lib/models/blueprint.js:558
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:
lib/models/blueprint.js:222
public files( ): Array
Used to retrieve files for blueprint.
Return:
Contents of the blueprint's files directory
lib/models/blueprint.js:205
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:
Path to the blueprints files directory.
lib/models/blueprint.js:642
public generateFileMap(fileMapVariables): Object
Used to generate fileMap tokens for mapFile.
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
fileMapVariables | Object |
|
Return:
lib/models/blueprint.js:1147
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:438
public install(options): Promise
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
options | Object |
|
Return:
lib/models/blueprint.js:678
public isUpdate( ): Boolean
Return:
lib/models/blueprint.js:523
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 |
lib/models/blueprint.js:1251
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:775
public mapFile(file, locals): String
Return:
lib/models/blueprint.js:253
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:
lib/models/blueprint.js:740
public
processFiles(intoDir, templateVariables): Promise
Return:
lib/models/blueprint.js:762
public processFilesForUninstall(intoDir, templateVariables)
lib/models/blueprint.js:938
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:955
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:244
public srcPath(file): String
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
file | String |
|
Return:
Resolved path to the file
lib/models/blueprint.js:1129
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:468
public uninstall(options): Promise
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
options | Object |
|
Return:
Private Methods
lib/models/blueprint.js:726
private _checkForNoMatch(fileInfos, rawArgs)
lib/models/blueprint.js:355
private _checkForPod( )
Prints warning for pod unsupported.
lib/models/blueprint.js:383
private _checkInRepoAddonExists(options)
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
options | Object |
|
lib/models/blueprint.js:337
private _commit(result): Promise
Calls an action.
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
result | Object |
|
Return:
Throws:
Action doesn't exist.
lib/models/blueprint.js:586
private _fileMapTokens(options): Object
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
options | Object |
|
Return:
lib/models/blueprint.js:804
private _generateFileMapVariables(moduleName, locals, options): Object
Return:
lib/models/blueprint.js:688
private _getFileInfos(files, intoDir, templateVariables): Array
Return:
file infos
lib/models/blueprint.js:713
private _getFilesForInstall(targetFiles): Array
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
targetFiles | Array |
|
Return:
files
lib/models/blueprint.js:700
private _ignoreUpdateFiles( )
Add update files to ignored files or reset them
lib/models/blueprint.js:834
private _locals(options): Object
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
options | Object |
|
Return:
lib/models/blueprint.js:372
private _normalizeEntityName(entity)
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
entity | Object |
|
lib/models/blueprint.js:412
private _process(options, beforeHook, process, afterHook)
lib/models/blueprint.js:287
private _writeFile(info): Promise
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
info | Object |
|
Return:
lib/models/blueprint.js:273
private _writeStatusToUI(chalkColor, keyword, message)
Write a status and message to the UI
lib/models/blueprint.js:1546
private dir( ): Array
Return:
list of files in the given directory or and empty array if no directory exists
lib/models/blueprint.js:1442
private gatherConfirmationMessages(collection, info): Array
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
collection | Array |
|
|
info | FileInfo |
|
Return:
lib/models/blueprint.js:1468
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:1559
private getDetailedHelpPath(thisPath): String
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
thisPath | String |
|
Return:
help path
lib/models/blueprint.js:1483
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:1536
private isFilePath(fileInfo): Promise
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
fileInfo | Object |
|
Return:
lib/models/blueprint.js:1456
private isIgnored(info): Boolean
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
info | FileInfo |
|
Return:
lib/models/blueprint.js:1522
private isValidFile(fileInfo): Promise
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
fileInfo | Object |
|
Return:
lib/models/blueprint.js:1422
private markIdenticalToBeSkipped(info)
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
info | FileInfo |
|
lib/models/blueprint.js:1433
private markToBeRemoved(info)
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
info | FileInfo |
|
lib/models/blueprint.js:1409
private prepareConfirm(info): Promise
Parameters:
Name | Type | Attribute | Description |
---|---|---|---|
info | FileInfo |
|
Return:
lib/models/blueprint.js:792
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