Much of the power of Expression comes from its scripting capabilities. Scripts are written in Javascript and have access to the Expression Objects Javascript API. They have the following entry points:

Entry Point	Description
`outputProcessors[]`	array of processors linked in a Datasource, triggered on Element execution
Post Handler	Respond to POSTs against Elements
API Hooks	Respond to API events
API Extension Module Requests	API routes extended by ObjectViews with an Extension Module

Output Processors

An outputProcessor is a script with a function named process which takes a single argument containing data from the parent context. They are attached to Datasources and can be chained.

The value returned by process is fed into the next outputProcessor in the chain defined on the Datasource.

If the outputProcessor is the last in its chain, the data in the object identified by the contextName name variable on the Datasource config becomes the return value from process

Example :

function process(inputArticles) {  
    for(var key in inputArticles) {
        var article = inputArticles[key];
        article.Title = article.Title.toUpperCase();
    }
    return inputArticles;
}

Post Handlers
————–

When an XprPostHandler is bound to an element, and that element is attached to a URL which receives an HTTP POST, the input is first processed by the Post Handler layer which validates the input and converts the formdata into a javascript object. The Post Handler configuration defines a script property which will be executed if the input data passes validation.

The data returned by process is stored in the result variable of the render context returned by the linked XprPostHandler Datasource.

Example :

var api = require('XprObjects/Api')

function getDefaultUserGroup() {
    return { Id: 1 };
}

function usernameAvailable(username) {

   var users = api.call({ method:"GET", uri:"/users/", params: "Username__eq" : username});
   if(users.length>0)
        return false;
   return true;
}

function process(signupForm) {

    if(!usernameAvailable(signupForm.Username)) {
        return {
                user: null,
                message: "That Username is not available"
        };
    }

    else {
        var newUser = api.call({ 
            method: "POST", 
            uri:"/users/", 
            params:{}, 
            data:{
                Username: signupForm.Username,
                Password: signupForm.Password,
                _embedded: {
                    UserGroup :  getDefaultUserGroup()
                }
            }
         });

        return {
            user: newUser,
            message: "Succesfully created User Id:" + newUser.Id
        };
    }
} 

API Hooks

An API Hook is typically configured in the Global Settings Store in the Expression Backend. A hook definition consists of an array of bundlePaths which will execute in sequence when a particular API event occurs.

The hook receives as context the first level properties of the effected object.

The interface implemented in the script pointed to by the bundlePath is dependent on the particular hook:

hook	description	interface
preSave	called before the object is saved	`function process(object)`
postAdd	called when a new object is created	`function process(object)`
postEdit	called when an object is changed	`function process(objectPrior, objectPost)`
preDelete	called before an object is deleted	`function process(object)`

The argument names are arbitrary, typically for clarity you will want to name the argument after the object the hook affects, e.g. function process(Article) { ... }.

Modules

While Output Processors, API Hooks and Post Handlers can define functions other than process in their scripts, it is often desirable to split code out into Modules, especially if you want to share functionality accross multiple scripts.

Module scripts are simply javascript which assigns the module to the module.exports variable.

Example :

var MathModule = {
    add: (x,y) => { return x+y; },
    sub: (x,y) => { return x-y; },
    mul: (x,y) => { return x*y; },
    div: (x,y) => { return x/y; }
};

module.exports = MathModule;

Modules are included via the require function which takes a bundlePath and returns the module contents.

Example :

var MathModule = require("MyModules/MathModule");

MathModule.add(1,1);

Builtin Libraries

Expression includes by default underscore.js and moment.js

underscore.js

Underscore is a library which provides a wide range of useful functional programming constructs for use in your scripts.

moment.js

Moment is a library which is used to transform and format dates.

Expression Objects

Expression Objects are the standard library of Expression, providing facility beyond pure javascript and interaction with Expression’s state.

Api

Api is used to execute synchronous requests against Expression’s REST API. The terminology is consistent with an HTTP request, the request to the API happens internally without ever

method	description
`call(options)`	execute an API call specified by `options`

Example :

var api = require('XprObjects/Api')

var matchingArticles = api.call({
    method: "GET",
    uri: "/articles/",
    params: {  
        Title__like : "Umbrella%"
    },  
    data: {  
    },
    parseHAL: true
});  

option key	description
method	HTTP method to emulate (GET/POST etc.)
uri	endpoint to request
params	map of query params to values
data	data for payload on POST/PATCH/PUT
parseHAL	when `true` (default), convert HAL collections to arrays. When `false`, include full HAL response including metadata like `Type` and `Total`

API Errors

If the API is unable to handle the request, an ApiError will be thrown, with the following properties:

property	description
status	Emulated HTTP status code, e.g. 403
data	metadata about the error
class	a string identifying the category of error, i.e. `ApiNotFoundError` or `ApiPermissionsError`
type	a subtype of the `class` of error, i.e. `PermissionsReadForbidden`
resource	the specific resource to submit the error. Useful if the error occurs within an `_embed` as opposed to the resource directly referenced by uri

In some cases, the error may not have all of the above context necessary for reporting back, in which case the error will have a single data property with whatever information the system has collected about the error.

Requests HTTP Client

The Requests library allows you to issue a synchronous HTTP request from your script.

Example :

function process(x) {

    var requests = require("XprObjects/Requests");
    var req = requests({
        "uri" : "http://vinceplayland2.xpr.ca/test.php",        
        "method" : "PUT",
        "data" : JSON.stringify( { "hello" : "world"}),
        "options" : {
            //"timeout" : [seconds]
            //"connect_timeout" :[seconds]
            //"useragent" : [string]
            //"follow_redirects : true,
            //"auth" : [ 'user', 'pass' ],
            //"proxy" : ???,
            //"max_bytes" : ???,
            //"data_format" : 'query' | 'body',
            //"headers" : { "header-name" : "value" }
        }
    });

    return req;

    //req.body (string)
    //req.raw  (string)
    //req.headers (array)
    //req.status_code (string)
    //req.protocol_version (string i.e. 1.0,1.1)
    //req.success (bool)
    //req.redirects (array)
    //req.url (string)
    //req.cookies (array)
}
 

CallingDatasource

CallingDatasource is available when the script was invoked as an outputProcessor. It contains the Datasource definition, post-variable replacement.

Example :

var callingDatasource = require('XprObjects/CallingDatasource');

function process(inputData) {  
    inputData.decorations = [
        "We are populating" : callingDatasource.contextName,
        "The adapter type was" : callingDatasource.adapter,
        "The configuration is" : JSON.stringify( callingDatasource.configuration ),
        "The list of bound output processors is" : JSON.stringify( callingDatasource.outputProcessors )
    ];
    return inputData;
}

WebRequest

WebRequest is the equivalent of the xpr.request object in the global render context.

Example :

var request = require('XprObjects/WebRequest');

function process(inputData) {  
    inputData.decorations = [
        "Logged in user is " + request.user.Username
    ];
    return inputData;
}  

request variable	description
user	authenticated frontend user API data
domain	The current domain
section	The current section API data, if routed as part of a page render and the router was able to resolved the landed section
article	The current article, resolved the same way as `section`
urlParams	map of HTTP query params to their specified values
debug	global `true` or `false` value indicating if the “debug” option was selected for this Expression session
language	active language for the request
client	data about the remote HTTP client
store	data about the ecommerce platform

CurrentBundle

XprBundle contains metadata about the bundle which contains the current executing script. This is primarily useful for getting the bundle’s JSON configuration data which is used to contain shared variables between the element stack and the script.

Example :

var bundle = require('XprObjects/CurrentBundle');

function process(inputData) {  
    inputData.decorations = [
        "This script lives inside of " + bundle.name,
        "The configuration data is" + JSON.stringify(bundle.config),
    ];
    return inputData;
} 

Settings

Settings is used to retrieve values from the Global Settings Store which have been enabled with the Export To Code option.

Example :

var settings = require('XprObjects/Settings');
var mySettingValue = settings["TestNamespace"]["TestSetting"];

HashLib

HashLib provides an MD5 function.

method	description
`MD5(input)`	returns the MD5 hash of `input`
`SHA1(input)`	returns the SHA1 hash of `input`

Example :

var hash = require('XprObjects/HashLib');

function process(inputData) {  
    inputData.decorations = [
        "The MD5 hash of the input data for this Datasource is" : hash.MD5(JSON.stringify(inputData)),
        "The SHA1 hash of the input data for this Datasource is" : hash.MD5(JSON.stringify(inputData)),
    ];
    return inputData;
}  

MediaExplorerFile

MediaExplorerFile allows you to read files from the web server, typically this will be something like a text file uploaded via the MediaExplorer.

method	description
`read(path)`	reads the file `path` from the webserver
`read_json(path)`	same as `read` but decodes JSON data

Example :

var file = require('XprObjects/MediaExplorerFile');

function process(inputData) {  
    var data = 
    inputData.decorations = [
        "The contents of /media/data.json are" : file.read("/media/data.json")
    ];
    return inputData;
} 

SendMail

SendMail allows you to send mail from the webserver.

method	description
`send(options)`	Send mail. Returns `false` on failure or the exception message in case an `\Exception` is thrown.

Example :

var mail = require('XprObjects/SendMail');

function process(inputData) {
    mail.send({
        to: "billg@microsoft.com",
        from: "sillygoat@crazyfarm.com",
        cc: "billg@microsoft.com, stevej@apple.com",
        bcc: {
          "billg@microsoft.com": "Bill Gates",
          "stevej@apple.com": ""
        },
        replyTo: "billg@microsoft.com, stevej@apple.com",
        subject: "Important business idea",
        body: "...",
    });
}  

Options

option key	description
to	target addresses
from	address to send from
cc	CC addresses
bcc	BCC addresses
replyTo	reply-to addresses
subject	subject of email
body	body of email
attachments	attachments of email
smtp	smtp settings

Adding addresses

Adding addresses can be achieved either by using a string, separating multiple entries with a comma:

to: "billg@microsoft.com, steve@apple.com"

or with an Email-keyed object which has the mail users’ Full Names (string) as values:

to: {
    "billg@microsoft.com": "Bill Gates",
    "stevej@apple.com": "Steve Jobs"
}

The above applies for the from/to/cc/bcc/replyTo options. Please note that:

The string method does not allow associating names with emails while the Email-keyed object one does.
Names can also be empty strings, in which case the email will not be associated with any Name.
The from option cannot have multiple values.

For legacy reasons, for the from option and only for the from option, the Name Surname <email@example.com> format can be used, e.g.:

from: "Bill Gates <billg@microsoft.com>"

Attachments

For adding attachments to the email, the file path under the media folder needs to be provided. This can be achieved either in a string, separating multiple entries with a comma:

attachments: "path/in/media/fileTitle1.png, path/in/media/fileTitle2.pdf"

or with a Path-keyed object which has the files’ Names as values:

attachments: {
    "path/in/media/fileTitle1.png": "fileTitle1.png",
    "path/in/media/fileTitle2.pdf": "filieTitle2.pdf"
}

In addition, an API call that requests files (i.e. having uri: "/files/" in the API call) can also be used.

Example :

var api = new XprApi();
var mail = new XprMail();

function process(inputData) {
    var files = api.call({
        method: "GET",
        uri: "/files/",
        params: {
            Title__eq: "fileTitle1.png"
        },
        data: {}
    });

    mail.send({
        to: "billg@microsoft.com",
        from: "sillygoat@crazyfarm.com",
        subject: "Important business idea",
        body: "...",
        attachments: files
    });
}

SMTP settings

XprMail makes use of the PHPMailer library, therefore by default it will use the built-in mail() PHP function. In case you wish to override it and use SMTP instead, then you can do it with one of the following ways:

Local configuration

When using the send method, set the smtp option key with the credentials:

var mail = new XprMail();
function process(inputData) {
    mail.send({
        to: {
            "billg@microsoft.com": "Bill Gates",
            "steve@apple.com": "Steve Jobs"
        },
        from: {
            "sillygoat@crazyfarm.com", ""
        },
        smtp: {
            host: "smtp.outbound.xpr.ca",
            secure: "tls",
            port: 543,
            username: "bill",
            password: "microsoft!"
        }
    });
}

option key	description
host	host URL
secure	type of security to use, `tls` or `ssl`
port	port to use, usually `578` for `tls` or `465` for `ssl`
username	username to authenticate
password	password to authenticate

Global configuration

In order to set global SMTP configuration, i.e. for every Sendmail to use SMTP, go to “Settings –> Global configuration” on the Expression backend and search for the Mail and SMTP KeyValue pairs. Set the Mail.method to "smtp" and then add the SMTP.host, SMTP.port, etc. settings according to the respective credentials.

Common SMTP providers

The following providers have been tested to work and are given here as examples.

Gmail

To enable SMTP usage for a Gmail account make sure you have configured the access to less secure apps for that account.

smtp: {
    host: "smtp.gmail.com",
    secure: 'tls',
    port: 587,
    username: "example@gmail.com",
    password: "examplePassword"
}

Sendgrid

smtp: {
    "host": "smtp.sendgrid.net",
    "port": 587,
    "username": "apikey",
    "password": "exampleApiKey"
}

TemplateRenderer

TemplateRenderer allows you to render HBS templates, with context:

method	description
`render(template, context)`	renders the hbs in template using context for variable replacement

Example :

var html = require('XprObjects/TemplateRenderer').render("replace: {{tagData}}",{ tagData: 'hello oscar!'});

html == "replace: hello oscar!";//true

XprRedirect

XprRedirect tells the webserver to issue a 302 redirect.

Note that all elements and referenced scripts on the requested URL will execute as normal, i.e. the request to redirect does not halt other processing.

If another script is executed which also requests a redirect, the last requested redirect will be the one issued by the webserver.

method	description
`setNextLocation(options)`	requests a 302 redirect be issued

Example :

var redirect = new XprRedirect();

redirect.setNextLocation({
   uri: "www.google.com"
});

property	description
uri	location for the 302 redirect

XprConsole

XprConsole is a global variable with one function, log which will emit its arguments to an Xpr Trace session, typically within the Bundle Editor.

Example :

XprConsole.log("Hello Expression Trace!", { hello: "world" });

XprApiExtensionRequest

XprApiExtensionRequest is issued by the API when hitting an ObjectView which has been extended with an API Extension Module.

method	description
`preventDefault()`	bypass standard API processing
`setResponse(code,data)`	send `data` as an API response, with the specified HTTP status code (Supported termination codes are 200,201,400,401,403,404,500)

An XprApiExtensionRequest also has a state, in the form of attached properties:

property	description
urlParams	HTTP/Emulated HTTP query params
payload	decoded JSON payload if present

Example :

getAll: function(request) {
    request.preventDefault();  
    request.setResponse(200,[1,2,3,4,5]);
}

{ article.Title }

Cannot find anything related to "{ keyword }"