The Web Script Framework lets you create a web script using familiar technologies, such as scripting and template languages.
Each web script comprises only the following components:
- A description document
- An optional controller script
- One or more FreeMarker response templates
Each component is implemented in its own file. The Web Script Framework dictates where the files are located and how they are named. This allows the framework to automatically locate and register web scripts without having to tell the framework where they are. In some cases, a web script can fall back to Java or rely on advanced Web Script Framework features where scripting alone cannot support the requirements of the web script.
Users of a web script only interact through the web script interface, which comprises its URI, HTTP method, and request/response document types. All of these are described in the web script description document, which is defined by the web script creator.
Web script description document
A web script description document is an XML file that describes the URI and HTTP method that initiates the web script. For example, the web script is given a short name and description, along with authentication and transactional needs. URI bindings are described as URI templates.
An example of a web script description document follows:
<webscript>
<shortname>Blog Search Sample</shortname>
<description>Sample that finds all blog entries whose content contains the specified search term</description>
<url>/sample/blog/search?q={searchTerm}</url>
<url>/sample/blog/search.atom?q={searchTerm}</url>
<url>/sample/b/s?q={searchTerm}</url>
<url>/sample/b/s.atom?q={searchTerm}</url>
<format default="html">extension</format>
<authentication>guest</authentication>
<transaction>required</transaction>
</webscript>
The following table describes the available options that can be set for a web script in the .desc.xml file:
| Option | Description | Notes |
|---|---|---|
| <shortname> | An identifier for the web script, for referencing. | For example: Reset User Password |
| <description> | A short description of the web script, shown in listings. | For example: Reset a user's password and send an e-mail confirmation |
| <url> | A list of URL patterns the web script responds to. | For example: /extras/modules/reset-user-password
Parameterized URL patterns can also be defined using curly braces to specify named parameters. For example: /slingshot/node/content{property}/{store_type}/{store_id}/{id}?a={attach?}, where {store_type}, {store_id}, and {id} are required named parameters. A ? after the parameter name, such as {attach?}, marks it as optional. |
| <format> | The requested format for the web script’s response. | The following options are available:
You can specify the default format if none is configured, such as in the following example: <format default=”json”>extension</format> or <format default=”json”>argument</format> |
| <authentication> | The required authentication to access the web script, defining who can call the script. | The following options are available:
|
| <transaction> | The transaction policy defining how the web script is executed within an Alfresco transaction. | The following options are available:
Note: If a web script implements an API
that uses the POST method but only requires read-only access,
such as the Search API, define the transaction option as
allow="readonly", such as in the following
example: <transaction
allow=”readonly”>required</transaction>. This
configuration informs the Alfresco engine that the script is
safe to run in read-only mode, enabling the API to function
correctly.
|
| <family> | The label for grouping related web scripts. | For example: Password |
| <lifecycle> | The status or visibility of the web script in the Alfresco repository. | The following options are available:
|
| <cache> | The HTTP caching behavior for an endpoint. | The following options are available:
|
Web script controller script
A web script controller script is a JavaScript file that contains the actual logic of a web script.
The controller script can query the repository to build a set of data items, known as a model, to render in the response. It might also update the repository for URIs that intend to modify the repository (PUT, POST, and DELETE method bindings). The JavaScript has access to the URI query string, services, and repository data entry points.
// check that search term has been provided
if (args.q == undefined || args.q.length == 0)
{
status.code = 400;
status.message = "Search term has not been provided.";
status.redirect = true;
}
else
{
// perform search
var nodes = search.luceneSearch("TEXT:" + args.q);
model.resultset = nodes;
}
Web script response template
Known as views, web script response templates render output in the correct format for specific needs, such as HTML, Atom, XML, RSS, JSON, CSV, or any combination of these.
The HTTP response is rendered by using one of the supplied templates, where the chosen template is based on the required response content type or status outcome. The template has access to the URI query string, common repository data entry points, and any data items built by the optional controller script.
<html>
<body>
<img src="${url.context}/images/logo/AlfrescoLogo32.png" alt="Alfresco" />
Blog query: ${args.q}
<br/>
<table>
<#list resultset as node>
<tr>
<td><img src="${url.context}${node.icon16}"/></td>
<td><a href="${url.serviceContext}/api/node/content/${node.nodeRef.storeRef.protocol}/${node.nodeRef.storeRef.identifier}/${node.nodeRef.id}/${node.name?url}">${node.name}</a></td>
</tr>
</#list>
</table>
</body>
</html>