Plugin request handling

As well as integrating into the main platform UI with features like Elements, your Plugin may implement it’s own user interface via request handlers. Use respond() to create a request handler, and use the response generation features to create your response.

Interface

function respond(methods, path, argDeclarations, handlerFunction)

Declare that this plugin responds to a URL. See Request handling for how it’s used.

Methods declares the HTTP methods this handler will respond to. Acceptable values are "GET", "POST" and "GET,POST". You can declare two handlers for a single path if one responds to GET and the other POST, which is handy for avoiding conditional checks on the HTTP method in the handler functions while still having pleasant URL schemes.

path is the URL to be handled. It must begin with /do/ or /api/.

WARNING: If the root of this URL has not been declared in plugin.json, the request handlers will never be called and will appear to be silently ignored.

argDeclarations is an Array of JavaScript Objects, used to define where the values for the handler arguments. See ‘Handler argument declarations’ below.

handlerFunction is the handler, and will probably be an anonymous function. The first argument should be called E, and will be the Exchange object. The other arguments are defined by the argDeclarations array.

Handler argument declarations

A declaration contains

  • A source for the argument (required)
  • What kind of argument (required)
  • Optional flag, if the argument may be omitted
  • Validation specification

Argument source

Each handler declaration must contain exactly one of the ‘source’ keys.

key pathElement

The argument value will be obtained from the URL path. The value is the zero-based index of the element, with the 0th element as the first element after the path the handler handles.

key parameter

The argument value will be obtained from the request parameters, either from the GET URL or the POST body. The value is the name of the parameter as a string.

key body: “body”

The argument value will be obtained from the HTTP request body, treated as a UTF-8 string.

The value of the property must be the string "body".

Argument value

key as

Declares what type of value is to be used for the handler function argument.

value as: “string”

The value is passed to the handler function as a String.

value as: “int”

The value is passed to the handler function as a number.

value as: “ref”

The value is passed to the handler as a Ref. The argument source should be the presentation string encoding of the object reference, as decoded by O.ref().

value as: “object”

The value is passed to the handler as a StoreObject. This is similar to "ref", but the object it refers to is loaded.

If the current user does not have permission to read this object, validation will fail and the handler function will not be called.

value as: “workUnit”

The value is passed to the handler as a WorkUnit. The argument should be the id of a work unit.

If no work unit with the specified id exists, then validation will fail and the handler function will not be called.

Unless overridden using the allUsers parameter, any work unit that is not actionable by the currently logged in user will fail validation.

value as: “db”

The value is passed to the handler as a DatabaseRow. The database table is specified with the table key, which must be present.

The source must be the string representation of a positive integer, referring to the row ID in the database table.

value as: “json”

The value is parsed as JSON and passed to the handler.

Invalid JSON will cause the request to fail validation and your handler will not be called.

value as: “file”

The value is passed to the handler as a BinaryData object. All files which may be uploaded by your form must be declared, and the form element must have an enctype="multipart/form-data" attribute. Uploaded files cannot be retrieved from E.request.parameters.

Unless it is stored using O.file(), the uploaded file will be deleted at the end of the request.

You should consider using a form with a file element instead.

Argument validation

key optional

If optional is true, then the argument can be omitted. If the request does not include it, the argument value will be null.

If the source for this argument is included in the specification, but validation fails, an error is raised and the handler is not called.

key validate

Used for string and int arguments. If it’s a function, it will be called with the value as it’s only argument, and should return true if the value passes validation.

string arguments also allow a RegExp object for validation. The value must match the regular expression to pass validation.

key allUsers

Used for workUnit arguments. By default, only work units that are actionable by the currently logged in user pass validation. Setting allUsers to true disables this check.

key workType

Used for workUnit arguments. If specified, will validate that the work unit’s workType attribute matches this value.

Handler argument examples

[
    {pathElement:0, as:"ref"},
    {pathElement:1, as:"db", table:"employee"},
    {parameter:"date", as:"string", validate:/^\d\d\d\d-\d\d$/},
    {parameter:"key", as:"string", validate:function(v) {return v.length > 4;}},
    {parameter:"number", as:"int", optional:true, validate: function(v) {return (v > 20);}},
    {parameter:"display", as:"object", optional:true}
]