Methods

The "assemble" object

Methods to the assemble object can be created using:

var  assemble = require('assemble' ).init(this );

• the this object is from the grunt task, and can be accessed in assemble "steps" through assemble.task
• the init method does some initial option configuration and sets the following properties on the assemble object:

assemble.task;    // refers to the grunt task 
assemble.options; // refers to the task.options merged with assemble defaults 
assemble.files;   // refers to the task.files 

init method

Describes init method to assemble.engine, and exposes engine on assemble.engine.

Custom Engines

If you don't wish to use Handlebars as your templates engine, you may add your own engine by providing an init function that takes in options from the assemble task/target. You may also override the init function in the task/target options by providing an initializeEngine function that takes the engine and the options:

assemble: {
  options: {
    engine: 'consolidate',
    initializeEngine: function (engine, options)  { 
      engine.engine.swig.init(options);
    }
  },
  docs: {
    files: {
      'docs/': ['src/templates/**/*.tmpl' ]
    }
  }
}

Assemble will attempt to load an engine and automatically add it's own wrapper methods around it while holding an instance of the engine. This is a way for engine plugin authors to write adapters between other engines and assemble's wrapper. To make these functions on the options useful, we've exposed the underlying engine through the assemble.engine object so developers can use the raw engine.

This is particularly useful when a) a library such as consolidate is used, where the engine is consolidate, and b) the developer wants to use another engine such as handlebars, swig, mustache etc.

• The init function allows assemble to pass in options to be used in initializing this engine plugin.
• init function is exposed, and handlebars-helpers is registered inside the init so that options can be passed in.

Admittedly, the engine.engine syntax is strange. This is "alpha", so feedback and pull requests are especially welcome if you have ideas for improving this.

Register Helpers

If you require helpers custom helpers beyond those included in handlebars-helpers, they can be loaded with the current engine via options: { helpers: []} in the assemble task or target.

You may also call registerFunctions by passing in an engine. This is used if you need to register custom helpers (filters, etc.):

registerFunctions(assemble.engine);

Example of how this would be setup in the options of the assemble task or target:

assemble: {
  options: {
    registerFunctions: function (engine)  { 
      var  helperFunctions = {};
      helperFunctions['foo' ] = function ()  {  return  'bar'; };
      engine.engine.registerFunctions(helperFunctions);
    }
  },
  site: {
    files: {
      'dist/': ['src/templates/**/*.tmpl' ]
    }
  }
}

Register Partials

Call registerPartial by passing in an engine:

registerPartial(assemble.engine, 'partialName', content);

Example of how this would be setup in the options of the assemble task or target:

assemble: {
  options: {
    registerPartial: function (engine, name, content)  { 
      var  tmpl = engine.compile(content);
      engine.engine.registerPartial(name, tmpl);
    }
  },
  blog: {
    files: {
      'dist/blog/': ['src/templates/**/*.tmpl' ]
    }
  }
}

Also see: options.partials

assemble steps

There are also methods to setup the assemble steps, and then execute the build:

The step function takes a function which takes 2 parameters function(assemble, next) :

1. assemble is the actual assemble object
2. next is a callback function that needs to be called when finished executing this step

See the following example:

assemble.step(function (assemble, next)  { 
  // do some code here 
  // you can add properties to assemble which can be accessed in later steps 
  assemble.myCustomProperty = { foo: 'bar'  };
  // always call next when finished and pass back the assemble object 
  next(assemble);
});

the step function

The step function also returns the current assemble object so it's chainable...

var  assemble = require('assemble' ).init(this )
    .step(step1)
    .step(step2)
    .step(step3)
    .build(done);
`

the build function

The build function takes a callback that is called when the build process is complete. The build process calls the steps that were previously setup, passing in the assemble object.

assemble.build(function (err, result)  { 
  if (err) {
    console.log(err);
    return;
  }
  console.log('finished building' );
});

Example custom Grunt.js plugin, "steps"

This shows how to create a custom Grunt plugin using Assemble steps.

grunt.registerMultiTask('steps', 'examples of using steps in assemble', function ()  { 
  var  done = this.async();
  grunt.verbose.writeln(('Running '  + this.name + ' - '  + this.target).cyan);
  // require assemble 
  var  assemble = require('assemble' );
  // initalize assemble with the currently running task 
  assemble = assemble.init(this );
  // let's see what assemble has now 
  grunt.verbose.writeln(require('util' ).inspect(assemble));
  grunt.verbose.writeln('' );
  // you can see there are some defaults that assemble sets up 
  // add the steps you want to execute 
  // add a custom string property to the assemble object 
  assemble.step(function (assemble, next)  { 
    grunt.log.writeln('running step 1' );
    assemble.step1 = 'This is step 1';
    next(assemble);
  });
  // add a custom object property to the assemble object 
  assemble.step(function (assemble, next)  { 
    grunt.log.writeln('running step 2' );
    assemble.step2 = {
      data: 'This is step 2' 
    };
    next(assemble);
  });
  // add a custom array property to the assemble object 
  assemble.step(function (assemble, next)  { 
    grunt.log.writeln('running step 3' );
    assemble.step3 = ['This is step 3' ];
    next(assemble);
  });
  // the last step will use the custom properties set up in the first 3 steps 
  assemble.step(function (assemble, next)  { 
    grunt.log.writeln('running step 4' );
    grunt.log.writeln('  data from other steps: ' );
    grunt.log.writeln('    '  + assemble.step1);
    grunt.log.writeln('    '  + assemble.step2.data);
    grunt.log.writeln('    '  + assemble.step3[0 ]);
    grunt.log.writeln('' );
    next(assemble);
  });
  // now run build 
  assemble.build(function (err, results)  { 
    grunt.log.writeln('build finished' );
    done();
  });
});

Example Gruntfile with steps task

The following code is for an entire Gruntfile.js, with an example of how to use step and build in the simpilest way.

module.exports = function (grunt)  { 
  // Project configuration. 
  grunt.initConfig({
    steps: {
      target1: {
        // do something 
      },
      target2: {
        // do something else 
      }
    }
  });
  // Load npm plugins to provide necessary tasks. 
  grunt.loadNpmTasks('grunt-contrib-jshint' );
  // Default task. 
  grunt.registerTask('default', ['jshint', 'steps' ]);
};

---

See the template for this page →