Now after getting a good overview of web scripts, REST architecture, and the Alfresco web script framework, it's time to implement the web script for Alfresco WCM. In this section, we will discuss how to create a web script and the required components of web scripts in detail.
Before creating any web script, it is necessary to know about the different components of a web script. So now we are going to talk about them.
Description document is the entry point and required component for a web script. Here you have to specify the URI of a web script, which will initiate that web script. Along with the URI of the web script, a description document describes the short name, description, authentication, and transactional details. The description document provides Alfresco with all of the necessary information to bind the web script to one or more URLs.
Controller script is generally used if you want to perform some business logic such as querying the database and fetching some content or updating the repository with some data or content. You can generate a data model within the controller, which will be used by one or more response templates. This is an optional component of a web script.
Response template is basically the view part of a web script MVC framework, which is responsible for rendering the output in the proper format. You can specify more than one response format in the description document and create those templates for different formats. You can use the model generated by the controller in response templates. This is a mandatory component of a web script. You should have at least one response template for each web script.
As stated earlier, a description document is the entry point for a web script, which initiates the web script. This is the mandatory component for a web script. You need to follow the naming convention for a web script description document, which is as follows:
<serviceId>.<httpMethod>.desc.xml
where serviceId is the web script ID and httpMethod can be GET, POST, PUT, or DELETE.
For example, if we have a web script that is responsible for getting the news headlines, we can have the filename as getNewsHeadline.get.desc.xml.
The content of this description document can be:
<webscript>
<shortname>Listing Of News Headlines</shortname>
<description>Listing Of News Headlines for Cignex home page thru Webscript</description>
<url>/org/cignex/news/getNewsHeadlines.xml?storeId={storeId}</url>
<authentication>user</authentication>
</webscript>
shortname:Human readable name for the web script and a mandatory element.description:Documentation for the web script. This is an optional element.url:A URI template to which the web script is bound. There can be one or more variants of the URI template for different formats.format:Decides how the required response type is stated with the URI. This is an optional element. Possible values (optional) are as follows:argument:Describes the required response type, which can be declared via theformatURI argument. For example,/news?format=json.extension:Specifies that the required response type can be declared via the URI extension. For example,/news.json.any:Specifies that either of the previous two is supported.
If not specified, the default value for
formatisany. And if the URI doesn't contain any response type, a default content type is taken from the default attribute of theformatelement, which is optional. And, if not specified there as well, the defaultformatishtml.authentication:The required level of authentication. This element is optional. If not specified, the default authentication isnone. Valid values are as follows:none:Specifies that no authentication is required at allguest:Specifies that at least guest authentication is requireduser:Specifies that at least named user authentication is requiredadmin:Specifies that at least a named admin authentication is required
The optional
runasattribute can be used to declare an alternative username to run the web script as. This is valid for classpath-stored web scripts only.
Following are the elements used for advanced configuration of a description document. All of them are optional elements:
transaction:Specifies the required level of transaction. This is an optional element. The default value isnone. The valid values are:none:Specifies that no transaction is required at allrequired:Specifies that a transaction is required and will inherit an existing transaction, if any is openrequiresnew:Specifies that a new transaction is required; this will not inherit an existing transaction, if any is open
family:Used to specify a tag for categorizing similar or related web scripts. You can have more than onefamilytag if this script belongs to more than one family.cache:Specifies the required level of caching. Available child elements are:never:Specifies whether caching should be applied at all; default option istrue. Valid values are:true:Specifies that the web script response should never be cachedfalse:Specifies that the web script response may be cached
If
neveris not specified, the default istrue.public:Specifies whether authenticated responses should be cached in a public cache; default istrue. Ifpublicis not specified, then the default isfalse. Valid options for thepublicelement are:true:Specifies that the web script authenticated response may be cached in a public cachefalse:Specifies that the web script authenticated response may not be cached in a public cache
mustrevalidate:Specifies whether a cache must revalidate its version of the web script response in order to ensure freshness. The default value for this istrue. Available valid values are:true:Specifies that validation must occurfalse:Specifies that validation may occur
negotiate(zero or more): Associates an Accept header MIME type to a specific web script format of response; the value (mandatory) specifies the format and the mandatory accept attribute specifies the MIME type when content negotiation is enabled with the definition of at least onenegotiateelement.kind:An attribute discriminator for overriding the kind of web script. See the list of available web script kinds. An attributekindallows a Java-backed implementation to be named, and for any web script description document to state, it wants to use that implementation instead of the out-of-the-box one provided by Alfresco.lifecycle:An attribute for describing the lifecycle of the web script. Web scripts typically start out in some sort of a draft state, are promoted to full production use, and are then retired at the end of their life. The possible values for this attribute are as follows:none:States this web script is not part of a lifecycle.sample:Indicates this web script is a sample and is not intended for production use.draft:Indicates this method may be incomplete, experimental, or still subject to change.public_api:Specifies this method is part of the Alfresco public API and should be stable and well tested.draft_public_api:Specifies this method is intended to eventually become part of the public API, but is incomplete or still subject to change.deprecated:States this method should be avoided. It may be removed in future versions of Alfresco.internal:Indicates this script is for Alfresco use only. This script should not be relied upon between versions.
According to the MVC architecture of a web script, a template acts as the role of view, which is responsible for rendering the web script output. You can have more than one template file for different response types. However, at least one template is a mandatory component for any web script. You need to follow the naming convention for a web script response template, which is as follows:
<serviceId>.<httpMethod>.<format>.ftl
where serviceId is the web script ID and httpMethod can be GET, POST, PUT, or DELETE. format specifies the response type format.
For example, if we have a web script that is responsible for getting the news headlines in the XML format, we can have the filename as getNewsHeadline.get.xml.ftl.
Any web script can have one or more response types. By default, formats supported by Alfresco for response type are as follows:
- html: text/html
- text: text/plain
- xml: text/xml
- atom: application/atom+xml
- atomentry: application/atom+xml;type=entry
- atomfeed: application/atom+xml;type=feed
- rss: application/rss+xml
- json: application/json
- opensearchdescription: application/opensearchdescription+xml
- mediawiki: text/plain (Media Wiki markup)
- portlet: text/html
- fbml: text/html
- php: text/html
- js: text/javascript
- calendar: text/calendar
There are two ways to specify the format of the response type:
- As format argument in the web script URL. For example,
http://<host>:<port>/<contextPath>/<servicePath>/getNewsHeadline?format=xml. - As a part of web script URL directly. For example,
http://<host>:<port>/<contextPath>/<servicePath>/getNewsHeadline.xml.
This specifies that the list of formats is the out-of-the-box supported format types by Alfresco. If you want to introduce a new format, configure the following Spring Bean declaring the format map with your new format:
<bean parent="webscripts.formatmap"> <property name="formats"> <props> <prop key="wav">audio/x-mpeg-3 </prop> </props> </property> </bean>