Actions
Sometimes there is a need to display some content based on data provided by the user. Such a simple process usually consists of three steps:
- A form collecting user input (launcher content).
- Processing the data sent by the user (action function).
- Showing a content depending on the result of the previous step (result content).
The first and last steps are provided by content pages, however, the processing of the input data requires a JavaScript function called action. The next excerpt shows a very simple form that has a single text input field and a submit button. Note the action and method properties of the form!
<form class="form-inline search-phrase" action="/actions/task" method="post">
<div class="form-group">
<label>Task name:</label>
<input type="text" class="form-control" name="task"
maxlength="20" value="{{ .task }}">
</div>
<button type="submit" class="btn btn-primary">Check it!</button>
<span class="error">{{ .error }}</span>
</form>
Let suppose the data of the form will be processed by an action located in the
/actions/task.js file. The action has to be bound to the form. This is
done in the server start up program (server.js
) using an actions object:
/* /server.js */
...
// Set engine routes.
var actions = {
'POST:/actions/task': '/actions/task.js'
};
engine.setRoutes( app, actions, mode );
...
The property names of the actions object have to match to the method:action
pairs of the input forms. The method and the colon can be omitted, the default
method is POST
. The values of the properties define the JavaScript modules that
contain the individual action functions:
action( req, ctx, callback )
req: The request object of the express framework.
ctx: The engine context of the current request, see Context object.
callback( resultUrl ): The callback function the action has to call to signal the end of the action.
resultUrl
Type: string
Default value: '/404'
A valid identifier of a content file that displays the result of the action.
Using the ctx.getPathById( id )
method ensures that the correct localized
content path will be applied.
Let see a very simple example for the action function that receives the input text of the preceding form:
/* /actions/task.js */
'use strict';
// Task action.
function action( req, ctx, callback ) {
// Read form data.
var task = req.body.task;
// Save input data.
ctx.data.task = task;
// Process data.
if (task.length > 5) {
// Pass result data.
ctx.data.result = task.length;
// Display result.
callback( ctx.getPathById( '/tasks/task-result' ) );
}
else {
// Show error message.
ctx.data.error = 'Input text is too short!';
// Stay on form page.
callback( ctx.getPathById( '/tasks/task-form' ) );
}
}
module.exports = action;
Actions land on ordinary content files, and data are passed through the
ctx.data
object. The passed data are available on the contents and segments
by a context token, where the token name is the name of a property on the
data object, and it is preceded by a dot: {{ .property-name }}
. For
example using the previous sample action:
<p>
<label>Task name:</label> <span class="success">{{ .task }} characters</span>
</p>
<p>
<label>Length:</label> <span class="success">{{ .result }} characters</span>
</p>
Built-in actions
The engine has the following built-in actions:
URL | Description | See |
---|---|---|
/404 | It is called when a content is not found. | |
/set-language | It is called at changing language. | |
/reboot | It can be called to reinitialize the content manager. | |
/search | It is called at content search. | Content search |
/r&d | It can be called in development mode. | Development support |
The URLs of all built-in actions can be set in the paths
section of the
configuration.