ForgeDocumentation
en
English Español Slovenčina Deutsch Français Italiano Português Polski Čeština Nederlands Română Magyar Svenska Ελληνικά Български

Documentation

Options of NEWACTION and the object an action receives

Total.js 5 · total5@0.0.19 referenceactionsvalidation Executed against Total.js 5

NEWACTION(name, options) declares an action. name is its id (Users/insert): routes use it with --> *Users/insert and your code with ACTION('Users/insert', payload).

Options

OptionValueWhat it does
nametextA description of the action; it is also available as $.name.
actionfunction($, model)The code of the action. model is the validated input.
inputtextThe fields of the body, as name:Type separated by commas; a * before the name makes it required. See the input types page.
outputtextThe fields of the answer; fields that are not listed are removed.
paramstextThe {name} segments of the route, validated like input.
querytextThe query string, validated like input.
partialtrueOnly the fields that were sent reach the action. Use it for PATCH.
usertrue or falsetrue answers 401 when there is no signed-in user; false accepts only anonymous requests.
permissionstext or array'read,write': the user needs one of them (or to be a super administrator).
routetextDeclares the route of the action here: 'GET /products/', or true for an API route.
middlewaretextNames of middleware that run before the action, separated by spaces or commas.
timeoutmillisecondsWhen the action does not answer in time, the request fails with the error Timeout..
cachetrue or an objectKeep the result of an action with CACHE.
configobjectValues that the action reads from $.config.
audittextRecords an automatic event after successful completion; see the dedicated recipe for tested boundaries. action-audit
csrf, encrypt, compress, publishaction-transport-boundaries
sa, sutrueEither requires a user with either administrator flag. action-hooks-and-admin
oninput, onoutputfunctionBefore the handler after validation; successful completion hook after output processing. action-hooks-and-admin
extendpathAdds the result under this path in the validated input and returns the extended payload. action-hooks-and-admin

The object $ of an action

MemberWhat it is
$.query, $.paramsThe validated query string and route segments.
$.payloadThe validated input; it is the same object as the second argument of action.
$.userThe signed-in user.
$.configThe config option.
$.name, $.idThe name option and the id of the action.
$.controllerThe $ of the route when the action was called from a route, so $.controller.body is the raw body. It does not exist when the action is called with ACTION().
$.callback(value)Answers with a value; it is filtered by output. Without arguments it returns a function (err, response).
$.success(value)Answers { success: true }.
$.invalid(error)Answers with an error: a text, a status code or an ErrorBuilder.
$.done(arg), $.successful(fn)Return callbacks for functions that report an error as their first argument.
$.cookie(name, value, expiration)Reads or writes a cookie of the request.
$.redirect(url)Redirects the request.
$.output(name)Chooses how a route answers: json, html, xml, text, redirect, binary, jsonstring, empty or file.
$.unauthorized(...permissions)Answers 401 and returns true when the user has none of the permissions.
$.action(name, payload)Runs another action with the same request.
$.hostname(path)The address of this server.
definitions/options.js
MIDDLEWARE('tag', function($, next) {
	$.response.headers['x-tag'] = 'on';
	next();
});

var counter = { cached: 0 };
MAIN.counter = counter;

NEWACTION('Options/named', {
	name: 'The name',
	config: { limit: 3 },
	action: function($) {
		$.callback({ name: $.name, id: $.id, limit: $.config.limit });
	}
});

NEWACTION('Options/guarded', {
	name: 'Needs a user',
	user: true,
	permissions: 'read',
	action: function($) {
		$.success();
	}
});

NEWACTION('Options/slow', {
	name: 'Never answers',
	timeout: 300,
	action: function($) {}
});

NEWACTION('Options/cached', {
	name: 'The cache option',
	query: 'page:Number',
	cache: { expire: '1 minute', query: 'page' },
	action: function($) {
		counter.cached++;
		$.callback({ page: $.query.page, runs: counter.cached });
	}
});

NEWACTION('Options/routed', {
	name: 'Declares its own route',
	route: 'GET /routed/ #tag',
	action: function($) {
		$.callback({ routed: true });
	}
});

NEWACTION('Options/output', {
	name: 'Chooses how to answer',
	action: function($) {
		$.output('plain');
		$.callback('plain text');
	}
});

AUTH(function($) {
	if ($.headers['x-user'])
		$.success({ id: '1', permissions: $.headers['x-user'].split(',') });
	else
		$.invalid();
});
controllers/options.js
exports.install = function() {
	ROUTE('GET /named/ --> *Options/named');
	ROUTE('GET /guarded/ --> *Options/guarded');
	ROUTE('GET /slow/ --> *Options/slow');
	ROUTE('GET /cached/ --> *Options/cached');
	ROUTE('GET /output/ --> *Options/output');
};