Hook reference

trussDoxSourceList

Provide sources for documentation processing.

This hook allows packages to define source files that will be processed into markdown during the documentation build process.

NOTE: All paths are relative from the directory containing Gruntfile.coffee.

Implementations must return

An array of glob patterns.

trussDoxSourceMarkdownTransform

Provide Transform implementations to convert sources to markdown.

This hook allows packages to define Transforms that will process sources into markdown during the documentation build process. A Transform is a subclass of stream.Transform.

Implementations must return

An object containing the following keys:

• extensions: A String Array of file extensions this Transform operates on e.g. ['coffee', 'yml'].
• Transform: A subclassed stream.Transform whose constructor is passed two arguments:
  • processor: The SourcesProcessor operating on the source.
  • stream: The source file stream.

trussFrontendAssetsMiddleware

Define assets to serve to the client application.

Packages may come bundled with JavaScript or CSS assets. This hook is how you can provide them to the client application.

Asset middleware takes assets as its first argument. This is an object with the following properties:

• ((Object or String) Array) scripts - A list of script assets.
• ((Object or String) Array) stylesheets - A list of sylesheet assets.

Scripts and stylesheets may be specified in object form:

• type: Either remote or inline.
• data: If type is remote, then the src/href URL to find the script/style sheet (respectively). If type is inline, then the actual script/style sheet content.

If a script or style sheet is specified as a string, then it is normalized to object form. type is assumed to be remote, and the string value becomes the value of data in the object.

NOTE: This hook lets you serve assets, but will not automatically copy them from your package to the frontend directory where they will be served. You'll need to implement the trussServerGruntConfig hook for that.

Implementations must return

A middleware hook specification. The middleware have the following signature:

function(req, assets, next) {
  ...
}

trussFrontendPackageTasks

Define Grunt tasks to run when building packages' frontends.

Packages can implement this hook to define Grunt tasks to run when the package's frontend is built. All tasks are registered as subtasks of truss-frontend-packages.

If this hook is not implemented, then two tasks are added for the package:

• Watch coffee files in [package]/client for changes, and rebuild the frontend if any change.
• Compile coffee files in [package]/client and add them to the module build path, making them accessible in the client.

Implementations must return

Either a String for a single task or a String Array for multiple tasks.

trussHttpServerRequestMiddleware

Define middleware to run for every HTTP request.

The req parameter to the middleware is an instance of http.IncomingMessage from the HTTP request.

The res parameter to the middleware is an instance of http.ServerResponse from the HTTP request.

Implementations must return

A middleware hook specification. The middleware have the following signature:

function(req, res, next) {
  ...
}

trussHttpServerRoutes

Define HTTP routes.

Packages use this hook to define HTTP routes.

Implementations must return

An array of objects structured like:

• (String) path - The HTTP path of the route. Include the leading slash.
• (String) verb - The HTTP verb to associate with this route. Defaults to 'get'.
• (Function) receiver - The function invoked when the route is hit. Takes three parameters:
  • (http.IncomingMessage) req - The request object.
  • (http.ServerResponse) res - The response object.
  • (Function) fn - A nodeback called when the route is complete.

trussReplServerContext

Add to the REPL context.

Packages may use this hook to provide access to parts of their state to the REPL context.

Implementations accept the following arguments:

• (Object) context - The context object.

To set context variables, simply set them on the context object.

trussServerBootstrapMiddleware

Define middleware to run when the server application is bootstrapping.

This hook is where most of the major initialization work happens on the server. You use this to spin up HTTP/sockets/database/whatever.

Implementations must return

A middleware hook specification. The middleware have the following signature:

function(next) {
  ...
}

trussServerGruntConfig

Hook into the Grunt build process.

This hook allows packages to define Grunt tasks, configure existing tasks, and load NPM tasks. This is achieved through the first implementation parameter which is an instance of the class GruntConfiguration. The grunt object is passed in through the second parameter in case it's needed.

One of the most common uses of this hook is to copy any asset files your package may include to the app directory, where they can be served to clients.

trussServerGruntConfigAlter

Alter the Grunt build process.

This hook allows packages to alter Grunt configuration specified through trussServerGruntConfig.

The first implementation parameter is an instance of the class GruntConfiguration. The grunt object is passed in through the second parameter in case it's needed.

trussServerPackageConfig

Define server-side configuration settings.

Packages may use this hook to define default configuration for server-side functionality. These settings can be overridden in the settings file.

Implementations must return

A recursive object which will be folded into the server configuration under the package name key. For instance, say we have a package my-package which defines the hook like:

registrar.registerHook('trussConfigServer', function() {
  return {
    one: 68,
    two: {
      three: 419
    }
  };
});

You would then find those values in the configuration at:

config.get('packageSettings:my-package:one');
config.get('packageSettings:my-package:two:three');

See the default configuration file for an example of how settings may be overridden. This should always be preferred to actually changing the code in a given package's hook.

trussServerPreBootstrap

Invoked before the application bootstrap phase.

Mitigate slow build times

If your package requires heavy modules, you should require them in an implementation of hook trussServerPreBootstrap. For instance, say you have a package like:

var someHeavyModule = require('some-heavy-module');

exports.pkgmanRegister = function(registrar) {

  registrar.registerHook('someHook', function() {
    someHeavyModule.doSomething();
  });
};

This will slow the build process down, since some-heavy-module must be loaded when loading your package. Use this pattern instead:

var someHeavyModule = null;

exports.pkgmanRegister = function(registrar) {

  registrar.registerHook('trussServerPreBootstrap', function() {
    someHeavyModule = require('some-heavy-module');
  });

  registrar.registerHook('someHook', function() {
    someHeavyModule.doSomething();
  });
};

So that the heavy module will not be required until hook trussServerPreBootstrap is invoked.

trussServerProcessExit

Final cleanups as the process is exiting.

The application tries its hardest to always invoke this hook, even in the event of a raised signal or unhandled exception.

You should not schedule asynchronous events, as they are not guaranteed to be dispatched. See the Node.js documentation for more information.

trussTransmittableErrors

Define errors that can be transmitted easily over the wire.

See the documentation on errors for more information.

Implementations must return

An array of subclasses of TransmittableError.