Developer Guide

Choose Programming Models

Once you have chosen the call patterns, specific data formats, and schemas to be used by each of your extensibility points, the next step is to select an appropriate programming model. A programming model dictates how your users will implement the logic of their extension, accept any input data, and send data back to your product.

Node.js programming model

Extend allows your users to write Node.js code to implement their extension logic. Each extension is a Node.js module that exports a single JavaScript function. Three basic function signatures are supported out of the box.

Simple function

In the simplest mechanism, you must provide JavaScript code that returns a function which accepts a single argument: a callback. To indicate completion, the function must call the callback with two arguments: an error and the result.

module.exports = function(cb) {
    cb(null, { i_am: 'done '});
}        

When the callback is invoked, the result value or an error will be serialized as JSON and sent back to the caller with the application/json content type.

Function with context

A more advanced version of the programming model allows you to return a function that accepts two arguments: a context and a callback.

module.exports = function(context, cb) {
    cb(null, { hello: context.body.name || 'Anonymous' });
}        

The context parameter is a JavaScript object with body, meta, query, secrets, and headers properties. It also offers the context.storage.get and context.storage.set APIs to access durable storage. You can read detailed documentation on the context object.

Full HTTP control

The most flexible programming model allows you to take full control over the HTTP request and response.

module.exports = function (context, req, res) {
    res.writeHead(200, { 'Content-Type': 'text/html '});
    res.end('<h1>Hello, world!</h1>');
}        

The context argument behaves the same way as in the previous programming model. Note that this programming model does not have a concept of a callback. Ending the HTTP response indicates completion.

Custom model using middleware

Instead of using one of the programming models that comes with Extend, you can choose to design your own. For example, if you have an “on account changed” extension in your system that accepts information about the account, account representative, and contact history, and allows for a modified account to be returned, you can choose to offer a tailored programming model for your users:

module.exports = function (account, representative, history, cb) {
  // make changes in account info
  return cb(null, account);
};

Supporting advanced scenarios (like this) that require custom programming models, DSLs, and more, is addressed in the Middleware section.

NPM Modules

The Node.js code your customers write to extend your platform can utilize all built-in Node.js modules as well as any module from the public NPM registry. When your customers write extension code, they should use require as they would normally, e.g:

var mongo = require('mongodb');

module.exports = function (ctx, cb) { };

However, before executing a webtask that has a dependency on an NPM module, the NPM module must be registered with the platform. Registering NPM modules allows the platform to download and install the NPM module beforehand, ensuring that the dependency is available whenever the webtask executes.

If your customers are using the command line tool, then the tool will read the dependencies listed in the package.json file and ensure that each is registered with the platform. If the package.json file specifies a version range for the module semver, the semver will be resolved to a particular version.

If your customers are using the embedded Extend Editor, then they can specify their dependencies by clicking on the editor ‘Settings’ icon and selecting ‘NPM Modules’.

Settings > NPM Modules

Your customers can then enter the NPM module that their code will take a dependency upon.

Adding an NPM Module

If your customers are not using either the command line tool or the embedded Extend Editor, you will need to ensure your customers’ NPM modules are registered with the platform by calling the HTTP API.