Integrating WCM Using Web Scripts [ 312 ] In this way, you can use Alfresco purely for web content management, which will be responsible for just producing the content, and then any application outside Alfresco will be responsible for the actual page composition. Hence, you will have the exibility to separate content production and content rendering/presentation. This allows us to easily integrate Alfresco with any other application. Later in this chapter, we will see integration with Liferay and Drupal, which will give you an overview of how we can use Alfresco as a content production environment. Then we will use that content in any application outside Alfresco. Implementing web scripts for WCM 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. Components of web scripts 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 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 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. Download from Wow! eBook <www.wowebook.com> Chapter 10 [ 313 ] One or more response templates 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. Conguration document There are different kinds of congurations dened in the XML document, which can be accessed via the config root object. This config object is available during both controller script and response template. This is an optional component of a web script. Locale message bundle From Alfresco version 3, a web script supports the localization of responses of a script. Each web script can have separate message bundles to store locale-specic messages. Creating a description document 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 lename 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> Download from Wow! eBook <www.wowebook.com> Integrating WCM Using Web Scripts [ 314 ] Basic elements of description document • 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 the format URI argument. For example, / news?format=json . ° extension: Species that the required response type can be declared via the URI extension. For example, /news.json. ° any: Species that either of the previous two is supported. If not specied, the default value for format is any. And if the URI doesn't contain any response type, a default content type is taken from the default attribute of the format element, which is optional. And, if not specied there as well, the default format is html. • authentication: The required level of authentication. This element is optional. If not specied, the default authentication is none. Valid values are as follows: ° none: Species that no authentication is required at all ° guest: Species that at least guest authentication is required ° user: Species that at least named user authentication is required ° admin: Species that at least a named admin authentication is required The optional runas attribute can be used to declare an alternative username to run the web script as. This is valid for classpath-stored web scripts only. Advanced conguration for a description document Following are the elements used for advanced conguration of a description document. All of them are optional elements: • transaction: Species the required level of transaction. This is an optional element. The default value is none. The valid values are: ° none: Species that no transaction is required at all Download from Wow! eBook <www.wowebook.com> Chapter 10 [ 315 ] ° required: Species that a transaction is required and will inherit an existing transaction, if any is open ° requiresnew: Species 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 one family tag if this script belongs to more than one family. • cache: Species the required level of caching. Available child elements are: ° never: Species whether caching should be applied at all; default option is true. Valid values are: • true: Species that the web script response should never be cached • false: Species that the web script response may be cached If never is not specied, the default is true. ° public: Species whether authenticated responses should be cached in a public cache; default is true. If public is not specied, then the default is false. Valid options for the public element are: • true: Species that the web script authenticated response may be cached in a public cache • false: Species that the web script authenticated response may not be cached in a public cache ° mustrevalidate: Species whether a cache must revalidate its version of the web script response in order to ensure freshness. The default value for this is true. Available valid values are: • true: Species that validation must occur • false: Species that validation may occur • negotiate (zero or more): Associates an Accept header MIME type to a specic web script format of response; the value (mandatory) species the format and the mandatory accept attribute species the MIME type when content negotiation is enabled with the denition of at least one negotiate element. • kind: An attribute discriminator for overriding the kind of web script. See the list of available web script kinds. An attribute kind allows 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. Download from Wow! eBook <www.wowebook.com> Integrating WCM Using Web Scripts [ 316 ] • 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: Species this method is part of the Alfresco public API and should be stable and well tested. ° draft_public_api: Species 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. Response templates (URI templates) 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 le 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 species 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 lename as getNewsHeadline.get.xml.ftl. Download from Wow! eBook <www.wowebook.com> Chapter 10 [ 317 ] Response type formats 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>:<p ort>/<contextPath>/<servicePath>/getNewsHeadline?format=xml . • As a part of web script URL directly. For example, http://<host>:<port>/ <contextPath>/<servicePath>/getNewsHeadline.xml . This species that the list of formats is the out-of-the-box supported format types by Alfresco. If you want to introduce a new format, congure 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> Download from Wow! eBook <www.wowebook.com> Integrating WCM Using Web Scripts [ 318 ] Root objects of FreeMarker Alfresco provides a default model provided by the JSF template component and template servlet, which provides a number of common root objects useful for most FreeMarker templates. The list of these root objects which you can use for a web script template is as follows: • companyhome: The company home template node. This is available only if authenticated. • userhome: Current user's home space template node. This is available only if authenticated. • person: Current user's person object template node. This is available only if authenticated. • args: A map of any URL parameters passed via the Template Content Servlet. • session: Session-related information. It provides a single-value session. ticket for the current authentication ticket. • classification: Read access to classications and root categories. • url: An object providing access to the URL or parts of the URL that triggered the web script. • workflow: Read access to information on workow objects and the currently executing workows for a user. • avm: Root-level object for a WCM web project. Using this API, it is possible to build templates that display content from les in the staging area or sandbox of a web project-based website. • argsM: An associative array of any URL parameters where each key is a parameter name and each value is an array containing the parameter values, even if only one is supplied. • guest: A Boolean indicating whether the web script executes as "Guest". • date: A date representing the date and time of the web script request. • server: An associative array of metadata properties that describe the hosting Alfresco server. • roothome: The repository root node. • webscript: An associative array of metadata properties that describe this web script. Download from Wow! eBook <www.wowebook.com> Chapter 10 [ 319 ] Apart from all of these root objects, the template also has access to root objects created by the execution script, if any script has been associated with the web script. You can also have JavaBeans associated with the web script, and you can create objects there as well, which will be accessed by this FreeMarker template for the web script. FreeMarker methods for the AVM repository Each of these root objects has different APIs. For more detail on this you can refer Alfresco wiki's Template Guide page at http://wiki.alfresco.com/wiki/ Template_Guide and see some examples at http://wiki.alfresco.com/wiki/ FreeMarker_Template_Cookbook . In this section, we will talk about the FreeMarker APIs available for the AVM repository. AVM API As stated earlier, avm is the root object for FreeMarker templates; with this root object, you can access the AVM repository. The available APIs for an AVM root node are as follows: • stores: This returns all store objects in the AVM repository • lookupStore(storeid): This returns the store object for the specied store ID • lookupStoreRoot(storeid): This returns the root node for the specied store ID • lookupNode(path): This returns a single AVM node based on the given full path including store to the node • webappsFolderPath(storeid): This returns the root path to the AVM webapps folder for the specied store ID • getModifiedItems(storeId, username, webapp): This returns a sequence of nodes representing modied items for the specied User Sandbox store for a specic webapps folder in the store • stagingStore(storeId): This returns the Staging Sandbox store for the specied store ID • avm.userSandboxStore(storeId, username): This returns the User Sandbox store for the specied user and store • websiteStagingUrl(storeId): This returns the preview URL to the Staging Sandbox for the specied store ID Download from Wow! eBook <www.wowebook.com> Integrating WCM Using Web Scripts [ 320 ] • websiteUserSandboxUrl(storeId, username): This returns the preview URL to the User's Sandbox for the specied store ID and username • assetUrl(path): This returns the preview URL to the specied fully qualied AVM path for the asset node • assetUrl(storeId, path): This returns the preview URL to the specied store and asset path AVM store API When you use any of the AVM APIs mentioned in the previous section, you will get the object of an AVM store. This store object can have the APIs described below: • id: This returns the internal ID of the store • name: This returns the name of the store • creator: This returns the user who has created this store • createdDate: This returns the date on which the store was created • lookupRoot: This returns the root node for the store • lookupNode(path): This returns the node for the specied path relative to avm webapps root folder for the store • luceneSearch(query): This executes the Lucene Search query against the store and returns the search results as a sequence of nodes AVM node API Following are the APIs for an AVM node: • version: Returns the node's version, generally it will be -1 (Head revision). • path: Returns fully qualied AVM path to the node. • parentPath: Returns fully qualied AVM path to the parent of the node. • isDirectory: Returns true if this node is a directory. • isFile: Returns true if this node is a le. • isLocked: Returns true if this node is currently locked. • isLockOwner: Returns true if this node is locked by the current user. • hasLockAccess: Returns true if this user has the permission to perform operations on the node when locked. This is true if the item is either unlocked, locked by the current user, or locked and the current user has the Content Manager role in the associated web project. • rename(name): This renames the node. Download from Wow! eBook <www.wowebook.com> Chapter 10 [ 321 ] Response status Web script response is used to inform the status to the client. It uses HTTP response status code for the following scenarios: • To inform the client about the cause of an error • To inform the client about the occurrence of an event • To instruct a client to perform a follow-up request • To inform a client about the success of a web script To set this status code, the status root object is available in the web script. And if you are using a Java-backed web script, then overload the API with status as one of the parameters. In the script, you can use the status code as follows: status.code = 400; status.message = "Required parameter's value has not been provided."; status.redirect = true; When you redirect like this, it will render the custom response template for the specied code. Searching of corresponding status templates will be performed in the following order: • Web script-specic template named <scriptid>.<method>.<format>. <code>.ftl • Web script-specic template named <scriptid>.<method>.<format>. status.ftl • Package-level template named <format>.<code>.ftl • Package-level template named <format>.status.ftl • Default template named <code>.ftl • Default template named status.ftl Web script controller In this section, we will discuss about the web script controller. Controller is an optional attribute of any web script. If you don't need it, you can omit this section. Download from Wow! eBook <www.wowebook.com> . create a web script and the required components of web scripts in detail. Components of web scripts Before creating any web script, it is necessary to know about the different components of a web. use that implementation instead of the out-of-the-box one provided by Alfresco. Download from Wow! eBook <www.wowebook.com> Integrating WCM Using Web Scripts [ 316 ] • lifecycle: An attribute. follow-up request • To inform a client about the success of a web script To set this status code, the status root object is available in the web script. And if you are using a Java-backed web