README.md

Plug-ins

gulp-component-assembler supports plug-ins to allow anyone to update the output generated by the assemble process.

To view the list of predefined plug-ins go to the PLUGINLIST.md file.

Load a predefined plug-in

To load a plugin that gulp-component-assembler defines, use loadPlugin and pass in the name of the plugin you want to load.

  compasm.loadPlugin('fileNameProvider');

How to write a plug-in

There are two steps to writing your own plug-in.

The first step is to create a function which takes in the params object, processes whatever it needs to process, and returns a string. This string is then added to the output of the component in the location indicated when you registered the plug-in.

The second step is to export a function that takes in a register function and a list of plug-in types. The function should call register and pass it the first function you created, the plug-in type to indicate when you want the plug-in to be processed, and the name of your plugin.

A plug-in must return a string that contains JavaScript compliant code. Your string is added to the component output file, which is a JavaScript file. So be cautious with your output.

Here is a simple example of a plug-in:

function pluginProcess(params, plugInType) {
  return "// This is from my plug-in of type `"+ plugInType +"`\n"; // This will add the comment into the output file
}

module.exports = function(register, types) {
  // register this plugin and process it before each assembly
  register(pluginProcess, types.BEFORE_ASSEMBLY, 'myPlugin');
};

Then, to use your plug-in you need to include your plug-in in your project and add the following in your gulpfile.js file:

var gulp = require('gulp');
var myPlugin = require('path/to/your/plug-in');
var compasm = require('gulp-component-assembler');

gulp.task('assemble', function() {
  compasm.loadPlugin(myPlugin);

  return gulp.src('./assembly.json')
    .pipe(compasm.assemble())
    .pipe(gulp.dest('./dist'));
});

Plug-in types

Plug-in Type	Description
BEFORE	BEFORE plug-ins are processed before the entire file is processed. The output is placed at the top of the output file, before any other content.
beforeASSEMBLY	BEFORE_ASSEMBLY plug-ins are processed before each assembly file is processed. Its output is placed just inside the IIFE.
BEFORE_JS_FILE	BEFORE_JS_FILE plug-ins are processed before each JavaScript file is processed. Its output is placed just before the inclusion of a file.
AFTER_JS_FILE	AFTER_JS_FILE plug-ins are processed after each JavaScript file is processed. Its output is placed just after the inclusion of a file.
AFTER_ASSEMBLY	AFTER_ASSEMBLY plug-ins are processed after each assembly file is processed. Its output is placed just before the end of the IIFE.
AFTER	AFTER plug-ins are processed after the entire file is processed. The output is placed at the bottom of the output file, after all other content.

Sample output file

The example output file below shows where each of the plug-in's output in injected:

// Assembly: sampleAssembly // Plugin: all.BEFORE console.log('plugin code called for BEFORE');

(function(window, document, undefined) {

// Plugin: all.BEFORE_ASSEMBLY console.log('plugin code called for BEFORE_ASSEMBLY');

/*

• Included File: src/test1.js */ // Plugin: all.BEFORE_JS_FILE console.log('plugin code called for BEFORE_JS_FILE');

function sampleFunction() { return false; } // Plugin: all.AFTER_JS_FILE console.log('plugin code called for AFTER_JS_FILE');

/*

• Included File: src/test2.js */ // Plugin: all.BEFORE_JS_FILE console.log('plugin code called for BEFORE_JS_FILE');

function fileTest2Js() { return "File: test2.js"; } // Plugin: all.AFTER_JS_FILE console.log('plugin code called for AFTER_JS_FILE');

// Plugin: all.AFTER_ASSEMBLY console.log('plugin code called for AFTER_ASSEMBLY');

})(window, document); // Plugin: all.AFTER console.log('plugin code called for AFTER');

### The `plugInType` object passed into your plug-in function

The `plug-in type`, from above, that indicates when this function was called. _Your function can use or ignore this parameter._

### The `params` object passed into your plug-in function

The `params` object is passed into your plug-in function and includes the following properties:

##### Property: projectPath - *{string}*
>This is the absolute path, at the time of assembly, to the folder that contains your assembly.json file.

##### Property: hasTranslations - *{boolean}*
>`hasTranslations` is `true` if there are any valid languages files being processed by this component.

##### Property: options - *{object}*
>The `options` object passed into the `assemble` function in your file `gulpfile.js`.

##### Property: assembly - *{object}*
>The JSON assembly object that is being processed at this time. This is the object that contains all of the properties found in the `assembly.json` file, including `files`, `templates`, `subs`, etc. 

##### Property: assemblyFileName - *{string}*
>This is the name of the assembly that is being built minus the `.js` extension. Normally this is the name of the folder that contains the `assembly.json` file.

#### Your own properties in the `assembly.json` file
You can add your own properties into the `assembly.json` file but *please*, in order to reduce the likelihood of name collisions, use name-spacing on all your variable. To do this, preface your variable names with a name that defines your plug-in.

*For example:* If your plug-in is called "banjo" then all of your properties should start with "banjo\_" as in the example below:

```js
{
  "files": [ "**/*.js" ],
  "banjo_classes": ["outer", "inner"],
  "banjo_title": "Lost and Found"
}

You access the above properties in your plug-in by reading the variables params.assembly.banjo_classes and params.assembly.banjo_title.

Note: If you are not planning to use 3rd party plug-ins and don't plan to make your plug-ins available to others then name-spacing is not as important. But be aware of the name collision risks of not name-spacing.

To simplify access to your properties avoid using non-variable characters in your property names like [`, !, -, +, =, etc.] otherwise you will need to access your properties like this: params.assembly['banjo!classes']

Plug-in Error Handling

When your plug-in encounters an error condition your code has two options:

1 Ignore the error and return nothing which will add nothing to the output

function pluginProcess(params) {
  var error = false;

  // Your logic here

  if (!error) {
    return "// Real string to add to output";
  }
}

module.exports = function(register, types) {
  register(pluginProcess, types.BEFORE_ASSEMBLY, 'myPlugin');
};

2 The error is catastrophic so you should throw an exception which will terminate your gulp process. You must throw an instance of the PluginError object.

var PluginError = require('gulp-util').PluginError;

function pluginProcess(params) {
  if (!params.assembly.files || params.assembly.files.length < 1) {
    throw new PluginError("my plugin", "You must supply a list of files");
  }

  return "// Real string to add to output";
}

module.exports = function(register, types) {
  register(pluginProcess, types.BEFORE_ASSEMBLY, 'myPlugin');
};