While you have seen an example of a URI template as defined by your Folder Listing Web script, it is worth spending some time taking a deeper look at what exactly a URI template is and how expressive it can be for defining complex Web script URIs.

A URI template is simply a URI containing tokens that may be substituted with actual values. Tokens may represent values to query parameters or values within the URI path, where the syntax for expressing a token is {<token name>}.

An example of specifying a URI with two query parameters — one named 'a' and the other named 'b' — follows:

/add?a={a}&b={b}

A client can generate the URI for invoking this Web script when given the URI template and values for 'a' and 'b'. For example, if 'a' is set to '1' and 'b' is set to '2', the resulting URI is:

/add?a=1&b=2

Query parameter tokens can indicate that the parameter is optional through the convention of appending a '?' to the token name. For example, to indicate that the query parameter 'b' is optional, the URI template becomes:

/add?a={a}&b={b?}

Although parameters may be marked as optional, it is only a convention and the Web Script Framework does not enforce mandatory query parameters. This responsibility is given to the Web script developer.

An example of specifying a URI path with embedded tokens — one named 'user' and the other named 'profilekind' — follows:

/user/{user}/profile/{profilekind}

Any URI that matches the URI template will invoke the Web script that defines it. But what does it mean to match? A match is made when:

For example, the following URIs match:

/user/joe/profile/public
/user/fred/profile/full

But the following URIs do not match:

/user/profile/public
/user/joe/profile

The value of a token in a URI path may itself consist of multiple path segments. For example, the following URI specifies the user value joe/smith and matches the previous URI template:

/user/joe/smith/profile/public

When a URI request is made, the Web Script Framework locates the associated Web script by finding the closest matching URI template for the URI. For example, consider that two Web scripts each define their own similar URIs:

The URI /a/b will invoke Web script A, while the URI /a/c will invoke Web script B. Matching of static parts of the URI template takes precedence over matching a token value.

Finally, the same token name may appear multiple times in a single URI template. Although very rare, it's worth knowing the implications of matching to a Web script. Consider the following URI template where the 'user' token is specified twice:

/user/{user}/profile/{user}

For a match to occur, the value provided for each same-named token must be the same. The following URI matches:

/user/joe/profile/joe

But the following URI does not match:

/user/joe/profile/fred

Web script developers have access to the value provided for each token in both the controller script and response template.

Remember, if you get stuck defining your own URI template, there are plenty of examples provided by out-of-the-box Web scripts, which you can browse through the Web script index.

A Web script is invoked when a URI is requested that matches one of the URI templates defined by the Web script. It is often necessary for the Web script to gain access to the requested URI to allow it to extract arguments that may have been passed in as URI query parameters or embedded as values in the URI path.

Your Folder Listing Web script defines the following URI template with one URI-path token and one query parameter token:

<uri>/dir/{folderpath}?verbose={verbose?}</uri>

To extract the values provided for the {folderpath} and {verbose} tokens, your Folder Listing controller script uses the following JavaScript:

...
var verbose = (args.verbose == "true" ? true : false);
var folderpath = url.templateArgs.folderpath;
...

Code snippet dir.get.js

The args root object is a special object provided by the Web Script Framework to all controller scripts. It represents a map of the URI query-parameter values indexed by their name. In this case, the controller script is extracting the verbose query parameter. If the query parameter is not specified on the URI, the returned value is null.

The url.templateArgs root object is another special object provided by the Web Script Framework. It represents a map of all values provided for tokens in the URI path, indexed by token name. In this case, the controller script is extracting the value for the folderpath token. URI-path values are never null.

Imagine a client has made the following URI request:

/dir/Company%20Home?verbose=true

The resulting value of verbose is true and the value of folderpath is Company Home.

Controller scripts have access to services provided by the Alfresco Content Application Server. This allows a Web script to query or perform operations against content residing in the Alfresco content repository. Services are exposed as root objects and each service provides its own application programming interface (API) to program against.

Your Folder Listing Web script simply needs to retrieve the folder value provided on the URI, identified by the {folderpath} token:

...
var folder = roothome.childByNamePath(folderpath);
...

Code snippet dir.get.js

The roothome root object is a special object provided by the Web Script Framework, which represents the root folder in the Alfresco content repository. From this object, it is possible to navigate through the content repository folder hierarchy or find sub-folders by name. Your controller script finds a sub-folder using the folder name provided in the URI.

There are many other root objects available to controller scripts:

When executing a Web script as an authenticated user, the controller script also has access to the following Alfresco services.

Remember, the out-of-the-box, pre-built Web scripts provide plenty of examples demonstrating how to use the root objects provided to controller scripts.

A Web script uses a response status code to inform the calling client of its execution outcome. Status codes may be used for the following scenarios:

Your Folder Listing Web script validates that the provided folder path actually exists in the Alfresco content repository using the following JavaScript in the controller script:

...
if (folder == undefined || !folder.isContainer) {
   status.code = 404;
   status.message = "Folder " + folderpath + " not found.";
   status.redirect = true;
}
...

Code snippet dir.get.js

The status root object is a special object provided to all controller scripts by the Web Script Framework. It allows a Web script to specify the response status code along with an associated status message. Typically, the value of the status code is set to a standard HTTP status code.

It is useful when reporting error status codes to provide additional information about the error in the response, such as the cause of the error. To support this, the Web Script Framework allows for a custom status response template to be rendered, but this happens only if the status.redirect value is set to true. A default status response template is provided by the Web Script Framework, which renders everything known about the status, so it's not necessary to develop your own; however, later in this chapter, you will discover how to create a custom status response template.

If the value of status.redirect is set to false, the status code is set on the response, but the response template for the requested format is rendered anyway.

One of the responsibilities of the controller script is to create a model for subsequent rendering by a response template. A model is a map of values indexed by their name, which can be read from and written to by the controller script.

Your Folder Listing Web script adds the verbose flag and retrieved folder to the model:

...
model.verbose = verbose;
model.folder = folder;
...

Code snippet dir.get.js

The model root object is provided to the controller script by the Web Script Framework. All items added to the model are available to the response template.

Response templates have access to the model created by the controller script. Each named value added to the model is accessible as a template root object by its respective model name.

Your Folder Listing controller script placed two values into the model: one named folder, a folder object, and the other named verbose, a Boolean. Your response template uses these two values to drive the rendered output on the response:

...
Contents of folder ${folder.displayPath}/${folder.name}
...
<#list folder.children as child>
...
  <#if verbose>
    ...
  </#if>
</#list>
...

Code snippet dir.get.html.ftl

The folder object is used to render properties of the folder and to iterate through its children while the verbose flag is used to determine if extra detail should be output.

As well as model root objects, response templates have access to services provided by the Alfresco Content Application Server. This allows a response template to directly query or navigate parts of the content repository or access the context within which the Web script is executing, such as the currently authenticated user.

It must be noted that although response templates can perform their own logic, this should not be encouraged. Web script logic is better implemented in controller scripts, allowing the response template to focus only on rendering the output. This allows the easy creation of multiple response templates, as logic does not have to be duplicated in each. It also means logic is encapsulated in one place, so changes to logic are centralized.

Your Folder Listing Web script first renders details about the Alfresco Content Application Server:

...
Alfresco ${server.edition} Edition v${server.version} : dir
...

Code snippet dir.get.html.ftl

The server root object is a special object provided by the Web Script Framework, which represents the server within which the Web script is executing. In this case, the response template simply accesses properties of the server.

There are many other root objects available to response templates:

When executing a Web script as an authenticated user, the controller script also has access to the following Alfresco services:

Remember that the out-of-the-box, pre-built Web scripts provide plenty of examples demonstrating how to use the root objects provided to response templates.

The FreeMarker template language supports the notion of a method. A method encapsulates an action to perform on a set of input parameters and may return an output value. Although FreeMarker provides many methods of its own, it also allows the registration of custom methods. The Web Script Framework takes advantage of this to provide the following methods specifically for developers of Web script response templates:

The out-of-the-box, pre-built Web scripts provide plenty of examples demonstrating how to use these methods. Imagine, though, you need to output the complete URL that was used to invoke a Web script. This is achieved using:

${absurl(url.full)}

The url root object represents the URL used to invoke the Web script. Access to the URL path, including its query parameters, is provided by the property named full; however, the URL scheme and authority are not included. To render a full URL, including scheme and authority, the absurl method is used.

At some point during the development of a Web script, you may hit an issue for which the solution is not obvious. In this case, it is really useful to be able to step through the controller script code line by line to pinpoint the cause of the issue.

The Alfresco Content Application Server provides a built-in JavaScript Debugger (as shown in Figure 9-2) that can be applied to Web scripts.

Figure 9.2. FIGURE 9-2

Step through the controller script of your Folder Listing Web script:

Remember, the JavaScript Debugger is an extremely useful tool for diagnosing the cause of issues. It is also really useful for stepping through other people's controller scripts to learn how they've implemented capabilities and how they've utilized Alfresco's services.

Response status code templates allow a Web script to render a custom response for a given status code. This is useful for providing unique information about a status code or to render a custom human-readable interface.

Your Folder Listing Web script returns a 404 (Not Found) status code if the requested folder does not exist in the content repository. By default, the Web script responds with a generic response that provides details about the status, including its descriptive message. This is useful for diagnosis but may not necessarily be consumable by the typical user of the Web script.

Add a custom response status code template that renders a human-readable message when the folder cannot be found:

As with all Web script component files, response status code template file names adhere to a naming convention as defined by the Web Script Framework. The appropriate response status code template is searched for in the following order:

Response status code templates have access to the same root objects as normal Web script response templates, with the exception that the default templates <code>.ftl and status.ftl only have access to the root objects url, status, server, and date.

When developing Web scripts, a useful tip is to leave the implementation of response status code templates until the end, as the templates are not essential to the Web scripts' execution. Testing can take place without custom response status code templates, as the Web Script Framework will always eventually find the default template status.ftl in the root package.

As with all other response templates, the addition and removal of a response status code template requires the Web script to be re-registered.

Authentication is required, as the Web script needs to query the Alfresco content repository.

The Knowledge Base site to search is passed in as a value within the Web script URI path through the {site} token. An Alfresco FTS (Full Text Search) query statement is constructed, which searches within the content repository path that represents the document library of the specified site:

/app:company_home/st:sites/cm:{site}/cm:documentLibrary

The query also filters results to knowledge articles by selecting only items that have the knowledge article aspect attached.

Having constructed the query statement, the query is executed through the search root object where the result set is optionally constrained to a maximum number of items, as specified by the {maxResults} URI query parameter.

Each row of the result set is converted to a knowledge-article item whose properties are fully calculated where necessary, such as the calculation of the author's full name. The converted result set is placed into the Web script model with the name data.

A default JSON response format is specified in the Web script descriptor, for which a single response template is provided. Each knowledge article item in the data model is visited and rendered into JSON. To ensure valid JSON is generated, the template utilizes the FreeMarker escape capability in conjunction with the Web script JSON encoding helper named jsonUtils.encodeJSONString().

You can't test the Knowledge Base Search Web script unless there are some knowledge articles to search for. To create knowledge articles you will develop another Web script, which first constructs an Alfresco Share site with a document library and then adds a knowledge article into the document library. The Web script may be executed repeatedly to create further knowledge articles.

You can now create some test data for the Knowledge Base Search Web script. Type the following in your command line to create the Alfresco Share site named kbtest and an initial knowledge article:

curl -uadmin:admin
"http://localhost:8080/alfresco/service/slingshot/knowledgebase/
create"

If successful, the response is:

Created article1 within site 'kbtest'.

You may repeat the command to create further knowledge articles.

With data created, it is finally time to test the Knowledge Base Search Web script. Type the following in your command line:

curl -uadmin:admin
"http://localhost:8080/alfresco/service/slingshot/knowledgebase/
search/site/kbtest"

If successful, the response is similar to the following, where each knowledge article is represented in JSON.

{
  "items":
  [
    {
      "nodeRef":
        "workspace://SpacesStore/1016b656-6288-4e17-be30-787138d1693b",
      "type": "cm:content",
      "name": "How to Create Content Models",
      "title": "",
      "description": "",
      "modifiedOn": "2010-01-29T10:57:59.608Z",
      "modifiedByUser": "admin",
      "modifiedBy": "Administrator ",
      "createdOn": "2010-01-29T10:57:59.451Z",
      "createdByUser": "admin",
      "createdBy": "Administrator",
      "author": "",
      "nodeDBID": "614",
      "properties":
        {
          "kb_articletype": "FAQ",
          "kb_status": "Draft"
        }
    }
  ]
}

You've now completed your first set of Web scripts that interact with the Alfresco Content Application Server. You'll see how they are used in Chapters 14–16, which go through the exercise of building the Knowledge Base application in Alfresco Share.

url is a root object providing access to the URL (or parts of the URL) that triggered the Web script. Access to the URL parts is via the following properties on the url object:

For example, imagine a Web script URI template of:

/user/{userid}

When the following URI is requested:

/alfresco/service/user/fred?profile=full&format=html

The url root object returns:

The status object represents a response status. The following properties allow for access to the status or the setting of a new status.

The cache object allows control over how the Web script response is cached. Caching is controlled via the following properties.

The format object represents the chosen format of the rendered response. The format is interrogated via the following properties.

The webscript object provides metadata describing the Web script currently being executed. Web script metadata is accessed via the following properties of the webscript object.

The server object provides metadata describing the host Alfresco server within which the Web script is currently being executed. Server metadata is accessed via the following properties of the server object.