Extends:

CoreObject → Addon

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.

Hooks:

Static Method Summary

Static Private Methods
private static
lookup(addon): Addon

Returns the addon class for a given addon name. If the Addon exports a function, that function is used as constructor. If an Object is exported, a subclass of Addon is returned with the exported hash merged into it.

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.

Method Summary

Public Methods
public

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 applications 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
public
import(asset, [options])

Imports an asset into this addon.

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

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

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

public
public
lintTree(treeType, tree)

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

public

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

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

public

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

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

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

private

Loads all required modules for a build

private

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

private
_treeFor(name): Tree
private
addonJsFiles( ): Tree

Returns a tree containing the addon's js files

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

Discovers all child addons of this addon and stores their names and package.json contents in this.addonPackages as key-value pairs

private
eachAddonInvoke(methodName, args)

Invoke the specified method for each enabled addon.

private
jshintAddonTree( ): Tree

Returns a tree with JSHhint output for all addon JS.

private
preprocessJs( ): Tree

Preprocesses a javascript tree.

private

Returns a tree with all javascript for this addon.

private

Returns the absolute path for a given addon

private

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

private
treeGenerator( ): Tree

Generates a tree for the specified path

Static Private Methods

lib/models/addon.js:1583

private static lookup(addon): Addon

Returns the addon class for a given addon name. If the Addon exports a function, that function is used as constructor. If an Object is exported, a subclass of Addon is returned with the exported hash merged into it.

Parameters:

Name Type Attribute Description
addon String

Addon name

Return:

Addon

Addon class

Public Constructors

lib/models/addon.js:146

public Addon(parent, project)

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 Methods

lib/models/addon.js:1172

public blueprintsPath( ): String

Returns the path for addon blueprints.

Return:

String

The path for blueprints

Example:

lib/models/addon.js:1435

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

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:

lib/models/addon.js:526

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.

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:

String

cacheKey

lib/models/addon.js:1190

public config(env, baseConfig): Object

Augments the applications 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
      • minifyJS
      • storeConfigInMeta
      • et, al

Parameters:

Name Type Attribute Description
env String

Name of current environment (ie "developement")

baseConfig Object

Initial application configuration

Return:

Object

Configuration object to be merged with application configuration.

Example:

config: function(environment, appConfig) {
  return {
    someAddonDefault: "foo"
  };
}
lib/models/addon.js:1515

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

Parameters:

Name Type Attribute Description
type Object
config Object
content Object

Example:

lib/models/addon.js:1230

public dependencies( ): Object

Return:

Object

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

lib/models/addon.js:624

public import(asset, [options])

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

lib/models/addon.js:592

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

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: function(parent) {
  this.import(somePath);
}
lib/models/addon.js:1281

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..

This function is not implemented by default

Uses:

  • Include custom commands into consuming application

Return:

Object

An object with included commands

Example:

includedCommands: function() {
  return {
    'do-foo': require('./lib/commands/foo')
  };
}
lib/models/addon.js:179

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.

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();
}
lib/models/addon.js:292

public isDevelopingAddon( ): Boolean

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:

lib/models/addon.js:1240

public isEnabled( ): Boolean

Return:

Boolean

Whether or not this addon is enabled

lib/models/addon.js:1495

public lintTree(treeType, tree)

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:

lib/models/addon.js:1157

public moduleName( ): String

Returns the module name for this addon.

Return:

String

module name

lib/models/addon.js:1417

public outputReady(result)

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

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

public postprocessTree(type, tree): Tree

Post-process a tree

Parameters:

Name Type Attribute Description
type String

What kind of tree (eg. 'javascript', 'styles')

tree Tree

Tree to process

Return:

Tree

Processed tree

Example:

lib/models/addon.js:1391

public preBuild(result)

This hook is called before a build takes place.

Parameters:

Name Type Attribute Description
result Object

Build object

lib/models/addon.js:1306

public preprocessTree(type, tree): Tree

Pre-process a tree

Uses:

  • removing / adding files from the build.

Parameters:

Name Type Attribute Description
type String

What kind of tree (eg. 'javascript', 'styles')

tree Tree

Tree to process

Return:

Tree

Processed tree

lib/models/addon.js:1335

public serverMiddleware(startOptions)

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: function(startOptions) {
  var app = startOptions.app;

  app.use(function(req, res, next) {
    // Some middleware
  });
}
lib/models/addon.js:1452

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.

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: function(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: function(tree) {
      var htmlbarsOptions = this._addon.htmlbarsOptions();
      return htmlbarsCompile(tree, htmlbarsOptions);
    },

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

  if (type === 'parent') {
    this.parentRegistry = registry;
  }
}
lib/models/addon.js:1249

public shouldIncludeChildAddon(childAddon): Boolean

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: function(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);
  }
}
lib/models/addon.js:1375

public testemMiddleware(app)

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

lib/models/addon.js:436

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).

Available tree names:

Uses:

  • manipulating trees at build time

Parameters:

Name Type Attribute Description
name String

Return:

Tree
lib/models/addon.js:677

public treeForAddon(tree): Tree

Returns a tree for this addon

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree

Addon file tree

Example:

treeForAddon: function() {
  var tree = this._super.treeForAddon.apply(this, arguments);
  var checker = new VersionChecker(this);
  var isOldEmber = checker.for('ember', 'bower').lt('1.13.0');

  if (isOldEmber) {
    tree = new Funnel(tree, { exclude: [ /instance-initializers/ ] });
  }

  return tree;
}
lib/models/addon.js:665

public treeForAddonTemplates(tree): Tree

Returns the tree for this addon's templates

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree

Addon Template file tree

lib/models/addon.js:782

public treeForAddonTestSupport(tree): Tree

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

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree
lib/models/addon.js:641

public treeForApp(tree): Tree

Returns the tree for all app files

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree

App file tree

lib/models/addon.js:760

public treeForPublic(tree): Tree

Returns the tree for all public files

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree

Public file tree

lib/models/addon.js:715

public treeForStyles(tree): 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.

lib/models/addon.js:653

public treeForTemplates(tree): Tree

Returns the tree for all template files

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree

Template file tree

lib/models/addon.js:748

public treeForTestSupport(tree): Tree

Returns the tree for all test support files

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree

Test Support file tree

lib/models/addon.js:736

public treeForVendor(tree): Tree

Returns the tree for all vendor files

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree

Vendor file tree

Private Methods

lib/models/addon.js:357

private _eachProjectAddonInvoke(methodName, args)

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

lib/models/addon.js:569

private _findHost( )

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.

lib/models/addon.js:251

private _requireBuildPackages( )

Loads all required modules for a build

lib/models/addon.js:852

private _shouldCompilePodTemplates( ): Boolean

Looks in the addon/ and addon/templates trees to determine if template files exists 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

lib/models/addon.js:504

private _treeFor(name): Tree

Parameters:

Name Type Attribute Description
name String

Return:

Tree
lib/models/addon.js:1092

private addonJsFiles( ): Tree

Returns a tree containing the addon's js files

Return:

Tree

The filtered addon js files

lib/models/addon.js:1003

private compileAddon(tree): Tree

Runs the addon tree through preprocessors.

Parameters:

Name Type Attribute Description
tree Tree

Addon file tree

Return:

Tree

Compiled addon tree

lib/models/addon.js:815

private compileStyles(addonStylesTree): Tree

Runs the styles tree through preprocessors.

Parameters:

Name Type Attribute Description
addonStylesTree Tree

Styles file tree

Return:

Tree

Compiled styles tree

lib/models/addon.js:972

private compileTemplates(tree): Tree

Runs the templates tree through preprocessors.

Parameters:

Name Type Attribute Description
tree Tree

Templates file tree

Return:

Tree

Compiled templates tree

lib/models/addon.js:278

private concatFiles(tree, options): Tree

Shorthand method for broccoli-concat

Parameters:

Name Type Attribute Description
tree Tree

Tree of files

options Object

Options for broccoli-concat

Return:

Tree

Modified tree

lib/models/addon.js:310

private discoverAddons( )

Discovers all child addons of this addon and stores their names and package.json contents in this.addonPackages as key-value pairs

lib/models/addon.js:337

private eachAddonInvoke(methodName, args)

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

lib/models/addon.js:1059

private jshintAddonTree( ): Tree

Returns a tree with JSHhint output for all addon JS.

Return:

Tree

Tree with JShint output (tests)

lib/models/addon.js:1113

private preprocessJs( ): Tree

Preprocesses a javascript tree.

Return:

Tree

Preprocessed javascript

lib/models/addon.js:1124

private processedAddonJsFiles(the): Tree

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

lib/models/addon.js:1558

private resolvePath(addon): String

Returns the absolute path for a given addon

Parameters:

Name Type Attribute Description
addon String

Addon name

Return:

String

Absolute addon path

lib/models/addon.js:838

private shouldCompileTemplates( ): Boolean

Looks in the addon/ and addon/templates trees to determine if template files exists 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

lib/models/addon.js:385

private treeGenerator( ): Tree

Generates a tree for the specified path

Return:

Tree