Module

The Cloud CMS Application Server can also be run as a custom Node.js application. It is available as a Node.js module that you can require() in from npmjs.org. The server features a number of extension points that you can utilize to wire in new functionality or extend the framework.

Getting Started

Here is a simple example where we start up the Application Server from within a Node.js application:

var server = require("cloudcms-server/server");
server.start();

The start() method takes an optional configuration object as an argument that can be used to configure and set up the features and services available within the framework.

// start up the server with wcm (web content management) enabled
var server = require("cloudcms-server/server");
server.start({
    "wcm": {
        "enabled": true
    }
});

Configure the Express App

When the server instance starts up, it calls through a chain of configuration functions that are able to configure the underlying Express app instance.

You can register a configuration function using the configure(function(app, callback) { }) method. The callback must be fired once your code completes.

server.configure(function(app, callback) {

    // set up the app instance
    app.abc = 123;

    // fire the callback
    callback();
});

Configure Web Sockets

If you've enabled web sockets, then the underlying socket.io connect event will fire for every browser or mobile app connection that is started up. You can use the sockets(function(socket, callback) { }) function to configure sockets before they are used.

The callback must be fired once your code completes.

server.sockets(function(socket, callback) {

    // send a hello message to the client
    socket.emit("hello", {
        "message": "Hello World"
    });

    // fire the callback
    callback();
});

Configure Routes

The routes(function(app, callback) { }) function provides a place where you can register conventional Express routes. These includes handlers for GET and POST method calls and so forth.

The callback must be fired once your code completes.

server.routes(function(app, callback) {
    app.get("/hello", function(req, res) {
        res.send("Hello World").end();
    });
    callback();
});

Configure Dust

The Application Server uses the LinkedIn Dust.js engine to provide layouts, templating and component rendering. You may wish to register custom Dust handlers or customize the Dust engine. Use the dust(function(app, dust, callback) { }) function to customize Dust before it is used.

The callback must be fired once your code completes.

Here is an example where we register a new @sample helper Dust tag.

server.dust(function(app, dust, callback) {

    // utilities
    var support = require('cloudcms-server/duster/support')(dust);
    var end = support.end;

    // sample dust helper
    dust.helpers.sample = function(chunk, context, bodies, params)
    {
        return support.map(chunk, function (chunk) {

            // message
            var message = context.resolve(params.message);

            // write and end this chunk
            chunk.write(message);
            end(chunk);
        });
    };

    callback();

});

This helper function can then be used within your HTML pages like this:

{@sample message="Hello World" /}

Before Server Startup

Use the before(function(app, callback) { }) method to provide handlers that should run before the server binds to the port (i.e. before the server comes online).

The callback must be fired once your code completes.

server.before(function(app, callback) {
    console.log("The server is about to start!");
    callback();
});

After Server Startup

Use the after(function(app, callback) { }) method to provide handlers that should run after the server has started. This code runs once the port has been bound and the server is handling requests.

The callback must be fired once your code completes.

server.after(function(app, callback) {
    console.log("The server has started!");
    callback();
});

Post Startup Report

Depending on how you have things set up, the server will start up either on a single CPU or on multiple CPUs using the Node.js cluster module. If started on multiple CPUs, the before and after methods will run once per CPU. This means that the "The server has started!" message from above may print multiple times - once per CPU.

In some cases, you may wish to provide a callback that only runs once all of the servers have started on all of the available CPUs. Use the report(function(callback) { }) method to register a callback that will be fired exactly once when all servers are online.

This is frequently useful for reporting and/or logging the startup of your server. Hence the name!

The callback must be fired once your code completes.

server.report(function(callback) {

    var cpuCount = require('os').cpus().length;

    console.log("Hello World - running on: " + cpuCount + " cpus");

    callback();

});

Store Values

The server object provides get and set methods for storing key/value pairs on the server instance. You can use this as you wish and as a means for retrieval later within custom services.

// set a value onto the server
server.set("host", "http://www.cnn.com");

// get a value from the server
var host = server.get("host");