Preprocessors

Experience with Javascript and Node.js modules is highly recommended before writing Solidus preprocessors

Preprocessors are javascript functions that are run on a page's context just after its resources are loaded. Preprocessors can be used to modify the page's context in any way, including the modification of resource data, page metadata, or even the addition of completely new information. Common preprocessing tasks include:

• Excluding unwanted data from an array
• Adding a new key to an object
• Mutating a string (capitalization, adding/removing a word, etc)

======

Creating a Preprocessor

Solidus preprocessors are defined the same way that Node.js modules are: by defining the value of module.exports. Preprocessors will always export a function with one argument, context, that must return an updated context at the end. Here's a quick example of a simple preprocessor:

module.exports = function( context ){
    context.new_data = 'You can add new data to the page context with preprocessors!';
    return context;
};

Preprocessors must be saved as .js files in the preprocessors/ directory.

======

Using a Preprocessor in a page

To use a preprocessor you'll need to add it to a page's configuration. This can be done by adding the preprocessor key with the path to the preprocessor you want to use (relative to the preprocessors/ directory).

index.hbs

{{!
    "preprocessor": "index.js"
}}

======

Using Javascript Libraries and Modules

Third party libraries such as Underscore.js and Moment.js can also be used in preprocessors. If these are on npm, you can include them in your site's package.json and install them. If not, you'll have to make sure they're packaged properly for Node.js, then place them somewhere in the preprocessors/ directory and include them by their local path. Here's an example of a preprocessor that includes modules:

With these files:

/preprocessors
└── index.js
/views
└── index.hbs
package.json

this package.json:

{
  "name": "keith-urban",
  "version": "0.0.0",
  "devDependencies": { ... },
  "dependencies": {
    "solidus": "~0.1.0",
    "underscore": "~1.5.2"
  },
  "main": "start.js"
}

and preprocessors/index.js as your preprocessor:

var _ = require('underscore');
var updateName = require('./updatename.js');
module.exports = function( context ){
    context.paired_info = _.pairs( context.info );
    context.name = updateName( context.name );
    return context;
};

======

Preprocessor Errors

When a preprocessor fails the context will be passed through unmodified, and the terminal will show a detailed error trace. Here's an example of a preprocessor error:

preprocessor:

module.exports = function( context ){
    context.doesnt_exist.not_here = 5;
    return context;
};

error:

[SOLIDUS] Preprocessor Error:
TypeError: Cannot set property 'not_here' of undefined
    at module.exports (/solidus-test-site/preprocessors/index.js:2:32)
    at module.exports (/solidus/lib/preprocessor_worker.js:13:13)
    at handle (/solidus/node_modules/worker-farm/lib/child/index.js:37:8)
    at process.<anonymous> (/solidus/node_modules/worker-farm/lib/child/index.js:43:3)
    at process.EventEmitter.emit (events.js:98:17)
    at handleMessage (child_process.js:318:10)
    at Pipe.channel.onread (child_process.js:345:11)

======

Solidus is still under development. If you have comments or questions, please reach out to us in our IRC channel: #solidus on irc.freenode.net

======