Addon - ember-cli

Extends:

CoreObject → Addon

Constructor Summary

Public Constructors
public	Addon(parent, project) Root class for an Addon. If your addon module exports an Object this will be extended from this base class. If you export a constructor (function), it will not extend from this class.

Public Constructors

public

Addon(parent, project)

Root class for an Addon. If your addon module exports an Object this will be extended from this base class. If you export a constructor (function), it will not extend from this class.

Property Summary

Public Properties
public final	addons: Addon[] The set of addons that this addon itself depends on.
public final	app: EmberApp The host app instance.
public final	name: String The name of this addon.
public final	parent: Project \| Addon This addon's parent.
public final	pkg: Object The contents of the addon's `package.json`.
public final	project: Project The root project to which this addon belongs.
public final	root: String The absolute path of the root directory where this addon is located.
public final	ui: UI A `console-ui` object that can be used to log messages for the user and indicate progress on long-running operations.

Method Summary

Public Methods
public	blueprintsPath( ): String Returns the path for addon blueprints.
public	buildError(error) This hook is called when an error occurs during the preBuild, postBuild or outputReady hooks for addons, or when the build fails
public	cacheKeyForTree(treeType): String Calculates a cacheKey for the given treeType. It is expected to return a cache key allowing multiple builds of the same tree to simply return the original tree (preventing duplicate work). If it returns null / undefined the tree in question will opt out of this caching system.
public	config(env, baseConfig): Object Augments the application's configuration settings.
public	contentFor(type, config, content) Allow addons to implement contentFor method to add string output into the associated `{{content-for 'foo'}}` section in `index.html`
public	dependencies( ): Object
public	findOwnAddonByName( ) Find an addon of the current addon.
public	hintingEnabled( ) Check if the current addon intends to be hinted. Typically this is for hinting/linting libraries such as eslint or jshint
public	import(asset, [options]) Imports an asset into this addon.
public	importTransforms( ): Object Allows addons to define a custom transform function that other addons and app can use when using `app.import`.
public	included(parent) This method is called when the addon is included in a build. You would typically use this hook to perform additional imports
public	includedCommands( ): Object Allows the specification of custom addon commands. Expects you to return an object whose key is the name of the command and value is the command instance..
public	init(parent, project) Initializes the addon. If you override this method make sure and call `this._super.init && this._super.init.apply(this, arguments);` or your addon will not work.
public	isDevelopingAddon( ): Boolean Allows to mark the addon as developing, triggering live-reload in the project the addon is linked to.
public	isEnabled( ): Boolean
public	lintTree(treeType, tree) Return value is merged into the tests tree. This lets you inject linter output as test results.
public	moduleName( ): String Returns the module name for this addon.
public	outputReady(result) This hook is called after the build has been processed and the build files have been copied to the output directory
public	postBuild(result) This hook is called after a build is complete.
public	postprocessTree(type, tree): Tree Post-process a tree
public	preBuild(result) This hook is called before a build takes place.
public	preprocessTree(type, tree): Tree Pre-process a tree
public	serverMiddleware(startOptions) This hook allows you to make changes to the express server run by ember-cli.
public	setupPreprocessorRegistry(type, registry) Used to add preprocessors to the preprocessor registry. This is often used by addons like ember-cli-htmlbars and ember-cli-coffeescript to add a `template` or `js` preprocessor to the registry.
public	shouldIncludeChildAddon(childAddon): Boolean Can be used to exclude addons from being added as a child addon.
public	testemMiddleware(app) This hook allows you to make changes to the express server run by testem.
public	treeFor(name): Tree Returns a given type of tree (if present), merged with the application tree. For each of the trees available using this method, you can also use a direct method called `treeFor[Type]` (eg. `treeForApp`).
public	treeForAddon(tree): Tree Returns a tree for this addon
public	treeForAddonTemplates(tree): Tree Returns the tree for this addon's templates
public	treeForAddonTestSupport(tree): Tree Returns the tree for all test files namespaced to a given addon.
public	treeForApp(tree): Tree Returns the tree for all app files
public	treeForPublic(tree): Tree Returns the tree for all public files
public	treeForStyles(tree): Tree Returns the tree for all style files
public	treeForTemplates(tree): Tree Returns the tree for all template files
public	treeForTestSupport(tree): Tree Returns the tree for all test support files
public	treeForVendor(tree): Tree Returns the tree for all vendor files

Private Methods
private	_eachProjectAddonInvoke(methodName, args) Invoke the specified method for each of the project's addons.
private	_findHost( ) This method climbs up the hierarchy of addons up to the host application.
private	_shouldCompilePodTemplates( ): Boolean Looks in the addon/ and addon/templates trees to determine if template files exist in the pods format that need to be precompiled.
private	_treeFor(name): Tree
private	compileAddon(tree): Tree Runs the addon tree through preprocessors.
private	compileStyles(addonStylesTree): Tree Runs the styles tree through preprocessors.
private	compileTemplates(tree): Tree Runs the templates tree through preprocessors.
private	concatFiles(tree, options): Tree Shorthand method for broccoli-concat
private	discoverAddons( ) Discovers all child addons of this addon and an AddonInfo about each addon in this.addonPackages (keyed on addon name).
private	eachAddonInvoke(methodName, args) Invoke the specified method for each enabled addon.
private	jshintAddonTree( ): Tree Returns a tree with JSHint output for all addon JS.
private	preprocessJs( ): Tree Preprocesses a javascript tree.
private	processedAddonJsFiles(the): Tree Returns a tree with all javascript for this addon.
private	shouldCompileTemplates( ): Boolean Looks in the addon/ and addon/templates trees to determine if template files exist that need to be precompiled.
private	treeGenerator( ): Tree Generates a tree for the specified path

Public Constructors

Parameters:

Name	Type	Attribute	Description
parent	Project \| Addon		The project or addon that directly depends on this addon
project	Project		The current project (deprecated)

Public Properties

The set of addons that this addon itself depends on.

This array is populated from the addon's listed dependencies and any items in ember-addon.paths in its package.json.

The host app instance.

Note: this property will only be present on addons that are a direct dependency of the application itself, not of other addons. It is also not available in init(), but will be set before setupPreprocessorRegistry() and included() are invoked.

This addon's parent.

If the addon is a direct dependency of an application, then parent will be the corresponding project instance. If it's a dependency of another addon, then parent will be a reference to that addon.

The contents of the addon's package.json.

The root project to which this addon belongs.

The absolute path of the root directory where this addon is located.

A console-ui object that can be used to log messages for the user and indicate progress on long-running operations.

Public Methods

This hook is called when an error occurs during the preBuild, postBuild or outputReady hooks for addons, or when the build fails

Uses:

Custom error handling during build process

Parameters:

Name	Type	Attribute	Description
error	Error		The error that was caught during the processes listed above

Example:

ember-cli-rails-addon

Calculates a cacheKey for the given treeType. It is expected to return a cache key allowing multiple builds of the same tree to simply return the original tree (preventing duplicate work). If it returns null / undefined the tree in question will opt out of this caching system.

This method is invoked prior to calling treeFor with the same tree name.

You should override this method if you implement custom treeFor or treeFor* methods, which cause addons to opt-out of this caching.

Parameters:

Name	Type	Attribute	Description
treeType	String

Return:

Augments the application's configuration settings.

Object returned from this hook is merged with the application's configuration object.

Application's configuration always take precedence.

Uses:

Modifying configuration options (see list of defaults here)
- For example
  - storeConfigInMeta
  - et, al

Parameters:

Name	Type	Attribute	Description
env	String		Name of current environment (ie "development")
baseConfig	Object		Initial application configuration

Return:

Object

Configuration object to be merged with application configuration.

Example:

config(environment, appConfig) {
  return {
    someAddonDefault: "foo"
  };
}

lib/models/addon.js:1653

public contentFor(type, config, content)

Allow addons to implement contentFor method to add string output into the associated {{content-for 'foo'}} section in index.html

Uses:

For instance, to inject analytics code into index.html

Example:

ember-cli-google-analytics

Return:

Object

The addon's dependencies based on the addon's package.json

Find an addon of the current addon.

Example: ember-data depends on ember-cli-babel and wishes to have additional control over transpilation this method helps.

// ember-data/index.js
treeForAddon(tree) {
  let babel = this.findOwnAddonByName('ember-cli-babel');

  return babel.transpileTree(tree, {
    // customize the babel step (see: ember-cli-addons readme for more details);
  });
}

Check if the current addon intends to be hinted. Typically this is for hinting/linting libraries such as eslint or jshint

Imports an asset into this addon.

Parameters:

Name	Type	Attribute	Description
asset	Object \| String		Either a path to the asset or an object with environment names and paths as key-value pairs.
options	Object	optional	Options object
options.type	String	optional	Either 'vendor' or 'test', defaults to 'vendor'
options.prepend	Boolean	optional	Whether or not this asset should be prepended, defaults to false
options.destDir	String	optional	Destination directory, defaults to the name of the directory the asset is in

Allows addons to define a custom transform function that other addons and app can use when using app.import.

This function is not implemented by default

Uses:

An app or addons want to transform a dependency that is being imported using app.import.

Return:

Object

An object with custom transforms

Example:

importTransforms() {
  return {
    'my-custom-transform': function(tree, options) {
      // transform the incoming tree and return the updated tree
    }
  };
}

Alternatively, if you want to process options before being passed into the custom transform function, use:

importTransforms() {
  return {
    'my-custom-transform': {
      transform: function(tree, options) {
          // transform the incoming tree and return the updated tree
      },
      processOptions: function(assetPath, entry, options) {
        // process your options

        return options
      }
  };
}

This method is called when the addon is included in a build. You would typically use this hook to perform additional imports

Uses:

including vendor files
setting configuration options

Note: Any options set in the consuming application will override the addon.

Parameters:

Name	Type	Attribute	Description
parent	EmberApp \| EmberAddon		The parent object which included this addon

Example:

included(parent) {
  this._super.included.apply(this, arguments);
  this.import(somePath);
}

Allows the specification of custom addon commands. Expects you to return an object whose key is the name of the command and value is the command instance..

This function is not implemented by default

Uses:

Include custom commands into consuming application

Return:

Object

An object with included commands

Example:

includedCommands() {
  return {
    'do-foo': require('./lib/commands/foo')
  };
}

Initializes the addon. If you override this method make sure and call this._super.init && this._super.init.apply(this, arguments); or your addon will not work.

Parameters:

Name	Type	Attribute	Description
parent	Project \| Addon		The project or addon that directly depends on this addon
project	Project		The current project (deprecated)

Example:

init(parent, project) {
  this._super.init && this._super.init.apply(this, arguments);
  this._someCustomSetup();
}

Allows to mark the addon as developing, triggering live-reload in the project the addon is linked to.

Uses:

Working on projects with internal addons

Return:

Boolean

Whether or not this addon is enabled

Return value is merged into the tests tree. This lets you inject linter output as test results.

Uses:

JSHint
any other form of automated test generation that turns code into tests

Parameters:

Name	Type	Attribute	Description
treeType	String		`app`, `tests`, `templates`, or `addon`
tree	Tree		tree of files (JavaScript files for `app`, `tests`, and `addon` types)

Example:

Returns the module name for this addon.

Return:

This hook is called after the build has been processed and the build files have been copied to the output directory

It's passed a result object which contains:

directory Path to build output

Parameters:

Name	Type	Attribute	Description
result	Object		Build result object

Example:

Opportunity to symlink or copy files elsewhere.
ember-cli-rails-addon
- In this case we are using this in tandem with a rails middleware to remove a lock file. This allows our ruby gem to block incoming requests until after the build happens reliably.

lib/models/addon.js:1543

public postBuild(result)

This hook is called after a build is complete.

It's passed a result object which contains:

directory Path to build output

Uses:

Slow tree listing
May be used to manipulate your project after build has happened

Parameters:

Name	Type	Attribute	Description
result	Object		Build result object

lib/models/addon.js:1468

public postprocessTree(type, tree): Tree

Post-process a tree

Parameters:

Name	Type	Attribute	Description
type	String		What kind of tree (eg. 'js', 'css', 'template')
tree	Tree		Tree to process

Return:

Tree

Processed tree

Example:

broccoli-asset-rev

This hook is called before a build takes place.

Parameters:

Name	Type	Attribute	Description
result	Object		Build object

Pre-process a tree

Uses:

removing / adding files from the build.

Parameters:

Name	Type	Attribute	Description
type	String		What kind of tree (eg. 'js', 'css', 'template')
tree	Tree		Tree to process

Return:

Tree

Processed tree

This hook allows you to make changes to the express server run by ember-cli.

It's passed a startOptions object which contains:

app Express server instance
options A hash with:
- project Current project
- watcher
- environment

This function is not implemented by default

Uses:

Tacking on headers to each request
Modifying the request object

Note: that this should only be used in development, and if you need the same behavior in production you'll need to configure your server.

Parameters:

Name	Type	Attribute	Description
startOptions	Object		Express server start options

Example:

serverMiddleware(startOptions) {
  var app = startOptions.app;

  app.use(function(req, res, next) {
    // Some middleware
  });
}

Used to add preprocessors to the preprocessor registry. This is often used by addons like ember-cli-htmlbars and ember-cli-coffeescript to add a template or js preprocessor to the registry.

Uses:

Adding preprocessors to the registry.

Parameters:

Name	Type	Attribute	Description
type	String		either `"self"` or `"parent"`
registry	Object		the registry to be set up

Example:

setupPreprocessorRegistry(type, registry) {
  // ensure that broccoli-ember-hbs-template-compiler is not processing hbs files
  registry.remove('template', 'broccoli-ember-hbs-template-compiler');

  registry.add('template', {
    name: 'ember-cli-htmlbars',
    ext: 'hbs',
    _addon: this,
    toTree(tree) {
      var htmlbarsOptions = this._addon.htmlbarsOptions();
      return htmlbarsCompile(tree, htmlbarsOptions);
    },

    precompile(string) {
      var htmlbarsOptions = this._addon.htmlbarsOptions();
      var templateCompiler = htmlbarsOptions.templateCompiler;
      return utils.template(templateCompiler, string);
    }
  });

  if (type === 'parent') {
    this.parentRegistry = registry;
  }
}

Can be used to exclude addons from being added as a child addon.

Uses:

Abstract away multiple addons while only including one into the built assets

Parameters:

Name	Type	Attribute	Description
childAddon	Addon

Return:

Boolean

Whether or not a child addon is supposed to be included

Example:

shouldIncludeChildAddon(childAddon) {
  if(childAddon.name === 'ember-cli-some-legacy-select-component') {
    return this.options.legacyMode;
  } else if(childAddon.name === 'ember-cli-awesome-new-select-component') {
    return !this.options.legacyMode;
  } else {
    return this._super.shouldIncludeChildAddon.apply(this, arguments);
  }
}

This hook allows you to make changes to the express server run by testem.

This function is not implemented by default

Uses:

Adding custom test-specific endpoints
Manipulating HTTP requests in tests

Parameters:

Name	Type	Attribute	Description
app	Object		the express app instance

Parameters:

Name	Type	Attribute	Description
name	String

Returns a tree for this addon

Parameters:

Name	Type	Attribute	Description
tree	Tree

Return:

Tree

Addon file tree

Example:

treeForAddon() {
  let emberVersion = new VersionChecker(this.project).for('ember-source');
  let shouldUsePolyfill = emberVersion.lt('4.5.0-alpha.4');

  if (shouldUsePolyfill) {
    return this._super.treeForAddon.apply(this, arguments);
  }
}

Returns the tree for this addon's templates

Parameters:

Name	Type	Attribute	Description
tree	Tree

Return:

Tree

Addon Template file tree

Returns the tree for all test files namespaced to a given addon.

Parameters:

Name	Type	Attribute	Description
tree	Tree

Returns the tree for all app files

Parameters:

Name	Type	Attribute	Description
tree	Tree

Return:

Tree

App file tree

Returns the tree for all public files

Parameters:

Name	Type	Attribute	Description
tree	Tree

Return:

Tree

Public file tree

Returns the tree for all style files

Parameters:

Name	Type	Attribute	Description
tree	Tree		The tree to process, usually `app/styles/` in the addon.

Return:

Tree

The return tree has the same contents as the input tree, but is moved so that the app/styles/ path is preserved.

Returns the tree for all template files

Parameters:

Name	Type	Attribute	Description
tree	Tree

Return:

Tree

Template file tree

Returns the tree for all test support files

Parameters:

Name	Type	Attribute	Description
tree	Tree

Return:

Tree

Test Support file tree

Returns the tree for all vendor files

Parameters:

Name	Type	Attribute	Description
tree	Tree

Return:

Tree

Vendor file tree

Private Methods

Invoke the specified method for each of the project's addons.

Parameters:

Name	Type	Attribute	Description
methodName	String		the method to invoke on each addon
args	Array		the arguments to pass to the invoked method

This method climbs up the hierarchy of addons up to the host application.

This prevents previous addons (prior to this.import, ca 2.7.0) to break at importing assets when they are used nested in other addons.

Looks in the addon/ and addon/templates trees to determine if template files exist in the pods format that need to be precompiled.

This is executed once when building, but not on rebuilds.

Return:

Boolean

indicates if pod based templates need to be compiled for this addon

Parameters:

Name	Type	Attribute	Description
name	String

Runs the addon tree through preprocessors.

Parameters:

Name	Type	Attribute	Description
tree	Tree		Addon file tree

Return:

Tree

Compiled addon tree

Runs the styles tree through preprocessors.

Parameters:

Name	Type	Attribute	Description
addonStylesTree	Tree		Styles file tree

Return:

Tree

Compiled styles tree

Runs the templates tree through preprocessors.

Parameters:

Name	Type	Attribute	Description
tree	Tree		Templates file tree

Return:

Tree

Compiled templates tree

Parameters:

Name	Type	Attribute	Description
tree	Tree		Tree of files
options	Object		Options for broccoli-concat

Return:

Tree

Modified tree

Discovers all child addons of this addon and an AddonInfo about each addon in this.addonPackages (keyed on addon name).

Child addons include those from 'dependencies' (not devDependencies) and in-repo addons

Any packageInfos that we find that are marked as not valid are excluded.

Invoke the specified method for each enabled addon.

Parameters:

Name	Type	Attribute	Description
methodName	String		the method to invoke on each addon
args	Array		the arguments to pass to the invoked method

Returns a tree with JSHint output for all addon JS.

Return:

Tree

Tree with JShint output (tests)

Preprocesses a javascript tree.

Return:

Tree

Preprocessed javascript

Returns a tree with all javascript for this addon.

Parameters:

Name	Type	Attribute	Description
the	Tree		tree to preprocess

Return:

Tree

Processed javascript file tree

Looks in the addon/ and addon/templates trees to determine if template files exist that need to be precompiled.

This is executed once when building, but not on rebuilds.

Return:

Boolean

indicates if templates need to be compiled for this addon

Generates a tree for the specified path