1. Introduction and Installation

In introduction to the Alfresco Web Quick Start and demonstration of an install using the Alfresco Installer on a Windows platform.

Documentation – Documentation is in progress and forming here: Web Quick Start Developer Guide , Web Quick Start Install and Config Guide, Web Quick Start User Guide.

UPDATE: Alfresco 3.4.a Community is now available including the Web Quick Start AMP files and web application. See alfresco-community-wcmqs-3.4.a.zip here or the QS is listed as an install option from the main Alfresco installers e.g. alfresco-community-3.4.a-installer-win-x32.exe.

We have just merged the Web Quick Start (QS) files to HEAD in preparation for the 3.4 Community release at the end of September. Once complete, the QS will have its own installers and documentation, however I thought I would provide a quick overview of some of the features that the QS provides for those who want to take an early look.

As with anything within the HEAD code line, it comes with a warning that this is work in progress, and is subject to regular change.

What is the Web QS?

The Web Quick Start is a sample application built on the Alfresco platform. It provides an end-to-end WCM example including an authoring and publishing environment using Alfresco Share and a web application built using Spring MVC, Spring Surf and OpenCMIS. The web site is delivered dynamically using Alfresco as a CMIS runtime.

The primary design goals of the QS are to illustrate the power of the Alfresco platform in an easy-to-install package and to provide developers with a strong starting point for their Alfresco implementations. Both of these goals are fundamentally aimed at getting both business people and developers up and running with the Alfresco WCM platform in as short a time as possible. The Alfresco core product has not been changed in any way, just extended by plugging in content model, behaviours, workflows, etc using the many standard hooks provided by the Alfresco product.

The QS website will eventually be available in three flavours for different vertical markets, however the version in HEAD currently is loosely modelled on a Finance news site, but with the intention that this can be re-purposed very easily.

Getting up and running

Once complete, Alfresco will provide core product documentation for the Quick Start covering Install and Configuration, User Guide and Developer Guide. The QS will eventually run on both Alfresco 3.3 Enterprise and 3.4 however as it currently stands within HEAD, only the 3.4 (HEAD) version is supported, so make sure you build the alfresco.war also.

The QS comprises four artefacts – an AMP file for Alfresco, and AMP file for Share, an awe.war file for the Web Editor and a wcmqs.war file which is the Spring-based web application itself. Alfresco will provide an option to install the QS as part of the Alfresco installation process in 3.4, and also provide a standalone installer to add the QS to a current 3.3 install. Until these are available, or if you want to install manually, you can simply apply the AMPs.

Sync up with HEAD and build Alfresco.war and Share.war. To build the QS artefacts you can use the following build targets:

Alfresco AMP:
ant package-wcmquickstart

Share AMP:
ant package-wcmquickstart-share

The above will build the appropriate AMP files and apply them to the alfresco.war and share.war. You can then simply copy these into your Tomcat webapps location.

EDIT – Maven has now been removed from the web app build process so use ANT as follows:
ant build-wcmquickstartwebapp-war

To build the web application, you must have Maven installed. From root\modules\wcmquickstart\wcmquickstartwebapp run:
mvn -DskipTests install

The above will create the website WAR (qcmqs.war), so copy this into your Tomcat webapps location.

Once deployed and started, login to Share as normal (e.g. http://www.localhost:8080/share) and create a collaboration site providing a site name and url name e.g. “Web Quick Start” and “wqs” respectively. Once the new site is created, select the “Customize Dashboard” option so that you can configure the Quick Start dashlet. Select “Add Dashlets” and you can then add the “WCM Quick Start” dashlet to your site dashboard:

Add the Quick Start dashlet to the Share site dashboard

The QS dashlet simply provides a means of importing the Quick Start site data into a standard Share Collaboration site. Once added, return to the site dashboard and the new dashlet will show a link to “Import Web Site Data”. Click this link and then wait for the success message:

Select the import link from the Quick Start dashlet

Once the data has been successfully loaded, navigate to the Document Library where you will see the default site structure:

You will notice that the site structure is separated into the “Quick Start Editorial” and “Quick Start Live” folders. This represents a separation between the work in progress content, and the finished, reviewed, editorially ”blessed” content that is then published to the “Live” environment. More about the publishing mechanism later.

If your web container is running on port 8080 and the web application is running in the same container as Alfresco, the setup is now complete and you should be able to access the web site on http://localhost:8080/wcmqs.

If you are not running the web application on port 8080 or if the web application is deployed to a different container or host, you can easily configure the site accordingly. Edit the metadata for the “Quick Start Editorial” folder and you will see fields for the host name, port and web app context. Configure these to point to where your web application (wcmqs.war) is deployed.

Editorial Folder Meta Data

The website

The website provides a set of features that demonstrate various aspects of using Alfresco’s WCM services. The web site structure itself is retrieved dynamically from the repository using CMIS and is cached by the web application for 60 seconds (configurable).

The main sections of the site include a Home Page, News landing page and sub-sections, Publications landing page and sub-sections and Blog section, as well as search and contact pages. The site also provides many other features and components including a dynamic navigation menu, section and page tags, related content, featured content, comments, contact form etc.

Quick Start Home Page

The Publications section is designed to allow content editors to easily publish Office document (currently Microsoft, but possibly Open Office also) content and images. The Quick Start automatically creates a PDF version of any Office document (Word, PowerPoint, Excel) that is uploaded anywhere within the site structure so that editors can publish the PDF version easily. Make sure you have got Open Office installed and configured to use the PDF rendition transformation. The web site also provides a flash-based document preview so that site visitors do not need to download the document just to read it:

The Blog section provides a simple blogging mechanism with tagging and comments, posting the user generated content back into a Data List within Share. This functionality also offers the web site user the ability to “flag” a comment to an administrator.

The Contact page allows a web site visitor to submit a contact form which in turn posts the content back to Alfresco. This example triggers a simple workflow.

This is by no means a definitive list of the web site functionality, however provides a high level overview.

Editorial

The Quick Start web site is managed via Alfresco Share and the Alfresco Web Editor (for in-context editing). As described previously, all editorial activity takes place in the “Quick Start Editorial” folder within the document library.

Folders are used within Share to define the site structure i.e. sections. Within the Quick Start example, both content and site structure reside within the same location and this combined model is dynamically delivered. This means that any content changes are updated immediately (barring any configured cache time) on the editorial site. For example, if a new folder is created under the “root” folder using Share, upon browser refresh, the new section will be displayed within the top level navigation. Note a folder has both a “Name” and “Title” field, the name being the URL and the title being the display label.

Creating a new folder within the QS site structure automatically creates two other things below it. Firstly a “collections” folder and also an “index.html” file. The index.html file is the asset used by the section’s landing page. The “collections” folder is used to manage any “content collections” for that section.

Content Collections are simply (as the name suggests!) collections of content assets, grouped as the content editor sees fit. For example, the home page on the QS site is made up of five different collections. Navigating to Quick Start Editorial > root > collections shows the collections used on the Home Page. Selecting “Edit Metadata” on any of them, will show the collection assets listed under the “Web Assets” field. The “news.featured” collection shown below is used to power the Home Page banner slider. You can see that 3 articles have been manually selected:

Web Assets on a Static Collection

Content collections whose content has been manually selected by an editor are referred to as “Static Collections”. Static collections are used in various places around the site where editorial control is required to select specific content assets.

You may also notice that there is a “Query” field within the same metadata dialog. If populated, this then turns the collection into a “Dynamic Collection”, whereby the query is automatically run on a configured interval e.g. every 30 minutes. An example is shown at Quick Start Editorial > root > collections > blogs.latest collection. This collection is used by the “Latest Blog Articles” component on the right hand side of the home page. The default query is using CMIS (Lucene is also supported) and simply retrieves the latest five blog articles and orders them by date/time. Dynamic collections allow portions of the website to be automatically updated without any editorial intervention. The “Maximum Size” and “Minutes to query refresh” fields can be used to fine tune the dynamic collection as required.

The keyword “section” can also be used within native CMIS queries. For example, to show all content items of type ws:article from the current section you could use “section:.” As follows:

select d.* from cmis:document as d where in_tree(d, '${section:.}') and d.cmis:objectTypeId='D:ws:article' order by d.cmis:creationDate desc

You can also reference an absolute section from the site root using ${section:/blog} or for a subsection of the current section you can use
${section:companies} or for the parent of the current section you can use: ${section:..}. You can also access site root using ${section:/}, or you can go really mad and use a combination ${section:/blog/../news/./companies}.

As the query is just standard CMIS, you can also use standard property names such as cmis:contentStreamMimeType, so to return all PDF documents within the current section you could use:
select d.* from cmis:document as d where in_tree(d, '${section:.}') and d.cmis:objectTypeId='cmis:document' and d.cmis:contentStreamMimeType='application/pdf' order by d.cmis:creationDate desc

For each section of the website, content type to template mappings can be controlled from within Share. For example, if you edit the metadata on Quick Start Editorial > root > news, you will see the “Section Config” property set to “ws:indexPage=sectionpage1”. This maps all requests going to this section’s landing page (the index.html asset is of type ws:indexPage) to the sectionpage1 template. Another example (set on the root folder) is ws:article=articlepage1 which causes all assets of the ws:article type to be rendered using the articlepage1 template. This template can be seen when clicking on any news or blog article.

This template mapping is hierarchical in that if a match is not found in the requested section, it will then look for a match in the parent section and so on until the root section is reached. Therefore, type-to-template mappings can be set site wide on the root folder. The template resolution algorithm also looks up the type hierarchy as part of this process, however I will not cover this in detail here.

Renditions, powered by the Alfresco Rendition Service are used extensively across the Quick Start site. They allow content authors to publish the correct format/size of content optimized for web, without any manual intervention. Renditions are defined within a Spring config file (rendition-context.xml), and then these definitions can be configured for use with either a given file mime type or content type. Like the type-to-template mappings, this configuration is on a hierarchical section basis, with the option to inherit being available to set on each section.

An example configuration can be seen on the Quick Start Editorial > root > news folder. The “Rendition Config” field has several mappings including ws:image=ws:featuredNewsThumbnail. This example specifies that all content of type “ws:image” will have a rendition created with the definition called “featuredNewsThumbnail” (defined in the Spring config file). To give it a test, upload a large file into the news section and attach it to a news article (by editing the metadata on the news article using the “Edit full metadata” option). When viewing the article on the web site you will see the renditions in use. A thumbnail or cropped banner slider image is displayed (if used on the front page) and a medium and large thumbnail when viewing the article directly. Using the node browser you can browse all of the generated renditions.

Out of the box, the Alfresco Web Editor is configured for use when viewing either a news or blog article. In 3.4, as well as edits, the Web Editor also provides the option to create new content and delete content. NOTE: currently the HEAD version includes the 3.3 AWE and does not build the 3.4 version yet. UPDATE: The 3.3 awe.war is no longer included as part of the web app build from HEAD.  The 3.4 AWE can be built separately using ant incremental-webeditor. Just drop the awe.war into the same container as the wcmqs.war.

In-Context Editing with the Alfresco Web Editor

The QS also provides two examples of managing user generated content (UGC) with Alfresco. There is a “Contact” form located on the Contact page and a “Comment” form located under each blog article. Both forms submit content to Alfresco via CMIS which is gathered in a Share Data List. The Contact form triggers a basic workflow and the Comment form provides the ability to flag a comment to an Administrator, which disables it from display i.e. visitor moderated.

Publishing

The QS also provides an example publishing mechanism. This is based on a workflow driven model whereby once content is approved it is moved locally (using the Transfer Service) from the “Quick Start Editorial” folder, into the “Quick Start Live” folder.

The QS provides two sample workflows for achieving this. Firstly “Review and Publish Section Structure”. This is designed to allow content authors to easily publish specific sections of the site structure. This is done by selecting and initiating this workflow on the appropriate index.html file for the required section. The “Review and Publish Section Structure” workflow will publish the sections from the submitted one and all sections below. A section comprises the section itself, its index page, and all of its collections. Basically it’s a “publish sub tree” mechanism. If you want to populate the entire site structure on live then publish the root section index.html.

The “Review and Publish” workflow publishes either a single asset or group of assets (multi-select). If you use this workflow for a sections index.html, it will publish that section and its collections folder, but does not cascade down.

It is worth noting you can also configure the web application to view the “Live” site structure by configuring the meta-data properties on the “Quick Start Live” folder. The default configuration sets the host address to 127.0.0.1, so if you are running the Quick Start locally, you can actually view the editorial environment on http://localhost:8080/wcmqs and the live on http://127.0.0.1:8080/wcmqs. Note that the Web Editor (AWE) is configured to be enabled on the Editorial content, and disabled on the Live. This is controlled by a flag “isEditorial” on the “Quick Start Editorial” which will also (when complete) dictate what is viewable via the live web application with regards to publishing go live and expiry dates.

Summary

I have certainly not covered all features here, but hopefully provided enough information to get started. The documentation will go in to a lot of detail, especially from a Developer perspective looking to extend the QS. Were hoping the QS will provide a valuable platform both from an evaluation perspective and also for both customers and partners looking to build Alfresco implementations.

• Release Schedule
• WCM Quick Start
• Project “Cheetah”
• Project “Swift”

The webinar can be viewed here.

Firstly to clarify, Web Studio is no longer part of the Community Alfresco product so is no longer available for download.  Web Studio was not part of an Enterprise release and was therefore not supported as part of the core product by Alfresco.  The Surf framework that Web Studio utilised has been committed to Spring Source.  The Surf framework is the underlying framework for Alfresco Share and Alfresco will continue to invest in Surf and surrounding developer tools.

With 3.3 Alfresco started to heavily invest in WCM utilising the core Alfresco repository (non AVM).  As part of this strategy we introduced the Web Editor (in-context editing) and Web Editor Framework (WEF).  The Web Editor Framework provides a standard plug-in framework that people can develop any type of functionality on.  The framework can be loosely considered to be a ribbon toolbar that can be customised e.g. adding custom tabs, buttons and any other UI required.  Most importantly it is a common framework that Alfresco, the Alfresco community, partners, customers, the Spring community and anyone else can develop on.  A lot of effort has gone into the way that toolbars, buttons and components in general can be packaged into a single file, allowing for new plug-in’s to easily be “dropped in” to a WEF environment.

The Web Editor was Alfresco’s first core product (documented, supported) feature that was built utilising the Web Editor Framework i.e. the Web Editor has a dependency upon the WEF.  The Web Editor addresses a single specific use case which is to edit content (semantic page content) in the context of the web site.  In context editing.  This functionality is something we are now looking to build on in future releases, expanding this functionality above and beyond simple editing.  The Web Editor focus however of the next release (internally named “Swift”) is still on the content editorial process for the Web Editor.

There is also a great deal of interest in what I will term “presentation management”, and this is where Web Studio really sparked peoples thoughts around Alfresco WCM.  By this I mean providing the ability for a site administrator  to manage sites, site structures, templates, components, navigation etc.  In order to provide these features in a consistent, supportable manner, an underlying model is required within the repository which can then be utilised by a  delivery framework.  As the WCM functionality moves forward, we will start to implement such a model, and utilise Spring Surf and the WEF to deliver the presentation management functionality.  The Swift release remains focused on web content production, so no presentation management capabilities are in scope for this release, however the building blocks around the model and Spring Surf will start emerge.

Speaking to Alfresco partners, customers and community member recently, I know people are already starting to implement the Web Editor Framework and build out their required functionality.  We have current customers who have built presentation management capabilities with full custom clients, and the Web Editor Framework provides a powerful  alternative to this route.

As we approach the final stages of development for 3.3 functionality, I thought it would be useful to write a brief introduction to the AWE to help people get started.  Please note that this article describes features currently found in HEAD, and are subject to change.

The Alfresco Web Editor (AWE) is a Spring Surf based web application that utilises the Forms Service to provide in-context editing capabilities to Alfresco repository content (non AVM).  Alfresco 3.3 also introduces the Web Editor Framework (WEF), which is a client side JavaScript framework that is a dependency of the AWE.  More on the WEF later.   The AWE is packaged as a stand-alone WAR file so that it can be deployed to web applications that are remote to the Alfresco application server.

Documentation:
Web Editor – http://wiki.alfresco.com/wiki/Web_Editor
Web Editor Framework – http://wiki.alfresco.com/wiki/Web_Editor_Framework

AWE Components

The diagram below shows the core components of the AWE in a basic configuration where all components (Alfresco and the AWE) are installed on a single application server:

JSP Support

With the initial release, the AWE will support JSP based web sites by providing a tag library.  Additional languages will be supported in future releases with Freemarker and PHP being top of the list.  The tags have been designed for easy implementation so that a developer can enable the AWE with minimal effort, and without effecting the CSS layout and design of the site.

Web Editor Framework (WEF)

One of the key design requirements for the AWE was to provide a client side framework that could be extended and built upon by our community.  As a result, the Web Editor Framework was developed.  This provides a client side JavaScript framework built using YUI that can be extended easily.  New tabs and buttons can be packaged and “dropped in” to the framework.  This allows Alfresco to provide core product features, and the Spring Surf and wider community to build out any custom plugins that are required.

As noted above, when the AWE is enabled, the WEF is a dependency that renders the toolbar and basic in-context editing buttons and functionality.  If the WEF is deployed stand-alone, the default blank toolbar is rendered.

A great deal of work has been done by Alfresco to package the WEF into and modular framework.  Were really hoping to see custom functionality being built and exchanged.

Build and Deploy

As well as the AWE itself, Alfresco Development have also provided a sample “customer” web application that allows you to easily test the in-context editing functionality.  The customer web app includes a simple tag library for calling content items from the repository.

There are a number of options for building the AWE and customer sample application.  Setting the APP_TOMCAT_HOME environment variable allows the builds to deploy directly to your Tomcat webapps directory.  For example:

APP_TOMCAT_HOME=C:\alfresco\tomcat


The build options are as follows:

clean-webeditor-projects - Cleans all projects related to the web editor project.

deploy-webeditor-tomcat - Deploys the web editor WAR to the application Tomcat server

incremental-webeditor-tomcat – Performs an incremental build and deployment of the Web Editor WAR

deploy-webeditor-sample - Performs a build and deployment of the customer sample website

To quickly get up and running, run:

ant incremental-webeditor-tomcat-exploded deploy-webeditor-sample-exploded

This will create both the customer and AWE web applications in your Tomcat webapps directory:

Sample “Customer” Web Application

The “customer” web application provides some simple examples and tests for the AWE.  Bundled with the customer web application example is a “customer” tag library.  This provides a simple mechanism for fetching content from the Alfresco repository.  In a production environment, the web application could be loading the content in any number of ways, so the customer tag library just gets you up and running quickly for the purpose of testing the AWE.

Open up \customer\includes\noderefs.jsp file.  You will see the two node references for sample content items:


<%
String mainTextNodeRef = "workspace://SpacesStore/301a540e-7101-489c-a8a7-859102a99ea5";
String subTextNodeRef = "workspace://SpacesStore/e94797ce-c6e9-47eb-b28c-c6a4eb3ce666";
%>

The two node refs are used throughout the example pages.  Create two example html files on your local disk, add some textual content, and upload these to a location within the repository.  Browse to these files using the node browser, and add the appropriate node references to the noderefs.jsp file.  Save the file and then browse to http://localhost:8080/customer/, and you should see the page rendered and the WEF toolbar.  You should be able to go ahead and edit any of the content items.

AWE Tag Library

As noted previously, the customer tag library is simply providing a mechanism to load a content item from the repository.  Within the index.jsp example, you will see the customer:property and customer:content tags used.  These are relatively self explanatory in that either a property or the content is loaded, hence if you have null displayed for your title, that is because it has not been set.

The template has a awe:startTemplate tag which resides within the <head></head> section of the page, and also a awe:endTemplate tag which sits just inside the closing </body> tag.  The awe:startTemplate tag essentially outputs a <script> tag and loads the WEF bootstrap webscript.  The awe:endTemplate tag on the other hand sets up the config for AWE i.e. a list of editable content items on the page and then renders a <script> tag to load the WEF resources script.

The awe:markContent tag is used to mark editable content on the page.  An edit icon is displayed on the page wherever the tag is used, or if CSS is disabled, an edit link with no image is used .  It is an option for the template developer as to where these are positioned, providing flexibility on where the most appropriate and logical position is for the content item in question.  In the example below, two parameters are specified, the id of the content item i.e. the node ref, and the title.  The title is used on the toolbar dropdown to list the available editable content items.  Note that within this example, no form is specified so the default form is assumed:

<awe:markContent id="<%=mainTextNodeRef%>" title="Edit Press Release" />

The example used later within the page utilises two additional attributes.  The formId allows the developer to specify a specific form to use, and the nestedMarker flag defines if the awe:markContent tag is used within a nested element.  If so, the element is used for a JavaScript flash effect, when a user is navigating using the drop down menu.  For example, a surrounding <div> element.


<div id="xyz">
<awe:markContent id="<%=subTextNodeRef%>" formId="description" title="Edit Trailing Text" nestedMarker="true" />
</div>

Please see the links below for documentation. Hopefully this has provided a good introduction to some of the AWE and WEF capabilities.  Comments and feedback welcome!

Documentation:
Web Editor – http://wiki.alfresco.com/wiki/Web_Editor
Web Editor Framework – http://wiki.alfresco.com/wiki/Web_Editor_Framework

Note:  These resources do not cover installation and setup.  For further information on installation see http://www.alfresco.com/products/ecm/enttrial/

Getting Started

• Web CMS’s Dissected – where does Alfresco WCM fit in compared to other products? – Essential reading from Peter Monks for anyone who is new to Alfresco WCM, or starting to investigate the product.  http://blogs.alfresco.com/wp/pmonks/2008/11/05/web-cmss-dissected/
• Getting Started with Web Content Management (WCM) 3.1 Enterprise – A PDF document stepping through the basics of the product including installing the sample website and configuring web forms.  THE place to start for basic product usage – http://www.alfresco.com/products/ecm/enttrial/files/getting_started_with_wcm_for_enterprise3_1.pdf
• Really Simple WCM – A recorded webinar stepping through several features of the product including web forms, file system projection (CIFS, FTP), user roles, basic workflow, sandboxes, virtualisation server (preview), basic deployment (FSR and ASR) and snapshots.  http://webinars.alfresco.com/forms/simplewcm/
• Alfresco Wiki – The source for reading up on all topics.  Browse by category – http://wiki.alfresco.com/wiki/Category:WCM

Web Forms

• WCM Forms Quick Tutorial – Alfresco Wiki – This document provides a quick tutorial on how to register and use WCM Forms – http://wiki.alfresco.com/wiki/WCM_Forms_Quick_Tutorial
• Learning Alfresco Web Forms by Examples – The definitive guide to WCM Xforms.  Dr Q runs through a series of hands on tutorials from the basics to advanced web form creation and usage.  http://drquyong.com/myblog/?p=65

Deployment

• WCM Deployment Features – Documentation on all of the WCM deployment options – http://wiki.alfresco.com/wiki/WCM_Deployment_Features
• Alfresco Transfer Service – A new service as part of 3.3 for the transfer of content between Alfresco servers (non AVM). http://wiki.alfresco.com/wiki/Transfer_Service

Preview

• WCM Preview – Alfresco Wiki document detailing the various preview options available including their specific use cases – http://wiki.alfresco.com/wiki/WCM_Preview

Content Modeling

• WCM Content Modeling webinar – A very detailed webinar from Peter Monks stepping through how to take a web site or mock-up (wireframes etc), and break it down into a set of discrete assets that can be efficiently managed with Alfresco WCM.  http://www.alfresco.com/about/events/2009/06/wcm-content-modeling/

Alfresco Web Editor and Web Framework

• Alfresco Web Editor – In-context editing for DM based content – http://wiki.alfresco.com/wiki/Web_Editor
• Getting started guide – http://www.benh.co.uk/alfresco/alfresco-web-editor/getting-started/

Renditions

• Rendition API – Introduced in 3.3, the rendition API allows non AVM based content to be transformed, utilising Freemarker and XSLT.  http://wiki.alfresco.com/wiki/DM_Renditions.  Documentation of the XSLT Rendering Engine are here – http://wiki.alfresco.com/wiki/XSLT_rendering_engine

Spring Surf

• Spring Surf Home Page – http://www.springsource.org/extensions/se-surf
• Spring Surf Documentation and Tutorials – http://www.springsurf.org/
• SURF Platform – What is SURF? – Alfresco Wiki – This provides a good first step for getting started with the Surf Platform – http://wiki.alfresco.com/wiki/Surf_Platform
• SURF Deployment configurations – Alfresco Wiki – A detailed page on the various ways in which SURF can be configured based on the use case – http://wiki.alfresco.com/wiki/Surf_Platform_-_Deployment_Configurations
• Getting Started with SURF – Three hands on tutorials covering building a basic web site from scratch using SURF.  Concludes with Alfresco WCM integration example -  http://www.benh.co.uk/alfresco/surf-part-1-getting-started/

The 3.1 JavaSccript API wiki page shows the required parameters:

ScriptNode copy(ScriptNode source, ScriptNode destination, String name)

Download the example web script here.  This web script is based on some example code taken from the Alfresco Forge project – FlexSpaces which contains some great examples of WCM web scripts.

As you will see from the descriptor file, the required parameters are passed to the JavaScript via the following URL:

/crossRepoCopy?sourcenodeid={sourceAdmNodeId}&targetstoreid={targetAvmStoreId}&targetavmpath={targetAvmPath}

In a production environment, the required arguments will no doubt be generated programmatically, however for the purpose of a simple example, we will collect them manually.  Firstly, the sourcenodeid source i.e. the node id of the source item that you wish to copy from the DM repo.  Using the Node Browser for this example, navigate to the source file and copy the node.  It will look something like:

workspace://SpacesStore/371d692f-46e7-4ca8-84bb-81a032ac1363

Strip out the workspace://SpacesStore/ as the example script adds it as required so you are left with:

371d692f-46e7-4ca8-84bb-81a032ac1363

Next the targetAvmStoreId, so the store that we are going to copy to within the AVM. This is made up from the web project dns name and the sandbox user name. Use the node browser once again and look for the store-identifier property. In my example the store-identifier is:

demo--admin

Finally the targetAvmPath which is the folder path to the location within the sandbox of where the content item will be created. In my example I would like to copy the content to the root of my web application folder so I use:

/www/avm_webapps/ROOT


With all of the parameters in place, the final request string looks like:

If the copy was successful, you will see:

Result String - Node was copied
Result Code - true

In this article I will look at deploying and consuming WCM content from a SURF web application.  To make this very simple, we have created a standalone Tomcat 6 bundle which has an example SURF web application pre-configured (thanks to Michael Uzquiano for all the assistance!).  This is the same web app as used in the previous articles, so all previous material is still relevant.

Once the Tomcat bundle is deployed and your WCM instance configured, you will have working examples of:

• An AVM layout separating Surf content (components, templates etc) and Web content (XML content, CSS, images etc).
• Deployment configuration allowing the Surf and/or Web content to be deployed to a local file system directory.
• An FSR – configured for the deployment as above
• A Surf website example of including static content e.g. an HTML file from the local file system.
• A surf website example of dispatching dynamic content from the remote Alfresco repository.
• Web form examples for the creation of example content.

Initially I will describe the steps required to get up and running, and then I will dissect the configuration so that we fully understand how it is working.

Prerequisites

• It is expected that you are familiar with Alfresco concepts such as CIFS, Web Scripts, Web Forms etc.  This is not a beginners tutorial to Alfresco WCM!
• Alfresco v3.x installed with WCM configured and running at http://localhost:8080.  If this address is different, you will need to re-configure the Alfresco endpoint.  This is detailed below within the “Dynamic Content Example”, so do not be alarmed if your “Products” section does not work after the install.
• This article is based on the Surf Deployment Configurations wiki article which I would highly recommend reading.

Download

Download the surf-sample Tomcat bundle and extract to your local file system e.g. c:\surf-sample.

Installation

Download the Surf demo Tomcat bundle and extract to your local file system.  Have a browse through the files and you will see that the following is included:

• surf-sample\sample – The Tomcat 6 bundle directory
• surf-sample\setup\AVM – An example directory structure to be loaded into the AVM
• surf-sample\setup\FSR – An example FSR
• surf-sample\setup\web forms – Example web forms for creating news and product items
• surf-sample\setup\web scripts – Example web scripts for the products section

Alfresco Setup

• Create a new web project with the DNS name – “demo”. If you do not use this name, you will have to make a small change to the “Product” web script. See the “Web Scripts” section below.
• Connect via CIFS to the AVM as the “admin” user.
• Copy the contents of the AVM structure dir from the surf-sample\setup\AVM\ROOT to the admin user sandbox via CIFS. (You could also zip up and bulk import if you prefer)
• Submit this content to the Staging sandbox.

The AVM directory structure should look like the following:

Web Forms

I have included two example web forms with the files so that you can quickly create some example content to be used with deployment, and for testing the example functionality.  There are two web forms which need to be installed, one for the news articles and one for products.

Article Web Form

• Create a new article web form using the C:\surf-sample\setup\web forms\article\article.xsd file.  Add the output path pattern of /${webapp}/content/news/source/${name}.xml
• Add C:\surf-sample\setup\web forms\article\latestNews.html.ftl as a rendition with the output path pattern /${webapp}/content/news/latestNews.html

Products Web Form

The product XML items are read dynamically by the Surf webapp.

• Create a new product web form using the C:\surf-sample\setup\web forms\product\product.xsd. Add the output path pattern of /${webapp}/content/products/source/${name}.xml

Note there is also a article.html.ftl file, however at present this is not used.  Once the web forms are installed, you can test creating some content.  Verify that the output is being populated to the correct locations as listed above.

Web Scripts

The Products section uses a web script which must be installed.

• Copy the C:\surf-sample\setup\web scripts\products folder in to the Alfresco Data Dictionary\web scripts folder and refresh the web scripts. If your site name is not “demo”, you will need to edit the site reference within C:\surf-sample\setup\web scripts\products\products.get.js i.e.


var storeid = ("demo");


Deployment Setup

All content is deployed to the C:\surf-sample\sample\deploy directory. This represents a stand alone directory which is configured to deliver the Alfresco content.  This directory is separated into two sections as follows:

• Web Content – e.g. HTML renditions, JS, CSS etc – deployed to C:\surf-sample\sample\deploy\webroot\ROOT
• Surf Content – surf items such as templates, components etc – deployed to C:\surf-sample\sample\deploy\alfresco

Configure two deployment targets:

• Edit your Web Project and add two File System Receivers using the details below.

Name: Content Production
Excludes: [A-Za-z0-9:/_]*ROOT/WEB-INF/*
Target Name: content

Name: Surf Production
Source Path: /ROOT/WEB-INF/classes/alfresco
Target Name: alfresco

FSR

There is an example FSR located within C:\surf-sample\setup\FSR.  You can copy this directory to another location if required e.g. c:\FSR.  The C:\surf-sample\setup\FSR\application-context.xml file has an example configuration which will need to be edited to match your file system locations depending upon where the surf-sample app is located.  See the dir locations in bold below:


<!-- Target Configuration. Modify for your site. -->
<property name="targetData">
<map>
<entry key="alfresco">
<map>
<entry key="root"><value>C:\surf-sample\sample\deploy\alfresco</value></entry>
<entry key="user"><value>admin</value></entry>
<entry key="password"><value>admin</value></entry>
</map>
</entry>
<entry key="content">
<map>
<entry key="root"><value>C:\surf-sample\sample\deploy\webroot</value></entry>
<entry key="user"><value>admin</value></entry>
<entry key="password"><value>admin</value></entry>
</map>
</entry>
</map>
</property>

Once complete, you should be able to start the surf-sample Tomcat and give the site a test.  Create some content using the web forms and deploy it to the surf-sample app.  Start the Tomcat using C:\surf-sample\sample\bin\startup.bat and hit http://localhost/surf/page?p=index

Static Content Example

The Home Page of the site includes a static HTML file that is created using the article.xsd web form.  This creates the latestNews.html file within the repository to ROOT\content\news which is then deployed to the C:\surf-sample\sample\deploy\webroot\ROOT\content\news.  The Surf web application then includes the latestNews.html at request time.

The HTML include import is done by the Surf component, however before this will function, we need to configure Surf (using Spring) to look into the C:\surf-sample\sample\deploy directory for the static content and web scripts.  If you open C:\surf-sample\sample\shared\classes\alfresco\web-extension\custom-web-framework-application-context.xml you will see the example configuration:


<!-- Local Store Abstract  -->
<bean id="webframework.localstore" class="org.alfresco.web.scripts.LocalFileSystemStore" abstract="true" init-method="init">
<property name="root">
<value>/surf-sample/sample/deploy</value>
</property>
</bean>
<!-- Web Scripts: Local Store -->
<bean id="webframework.localstore.webscripts" parent="webframework.localstore"> <property name="path">
<value>alfresco/site-webscripts</value></property>
</bean>

Once this is configured, components can access this static content.  The component that is used on the Home Page is C:\surf-sample\sample\deploy\alfresco\site-data\components\page.main.index.xml and looks like:

<?xml version='1.0' encoding='UTF-8'?>
<component>
<scope>page</scope>
<region-id>main</region-id>
<source-id>index</source-id>
<component-type-id>/component/common/include</component-type-id>
<properties>
<container>div</container>
</properties>
<resources>
<resource id="source" type="webapp">/content/news/latestNews.html</resource>
</resources>
</component>


You can see that we are using one of the web scripts that comes bundled with Surf which is referenced by  /component/common/include.  The resource id is then passed in i.e. the html fragment.

Finally, it is also worth noting at this point that we have mapped a Tomcat alias to point to the “deploy” directory also.  This allows us to reference files such as CSS and images if required, using the “/files” alias.  Here is the server.xml extract:

<Context path="/files" docBase="${catalina.home}/deploy/webroot/ROOT" reloadable="true" crossContext="true"/>

Dynamic Content Example

The second example is the Products page which dynamically loads content from the Alfresco repository.  A list of products is dynamically generated using a web script connecting top the remote Alfresco repository.  When a link is clicked, the relevant content item is dispatched and loaded from the local file system.

The first part of this is a web script that is called to list all of the product items.  This web script is actually located on the remote Alfresco server and therefore we have to configure Surf to search this location for web scripts.

Like configuring the local file store, there is a custom Spring file located in C:\surf-sample\sample\shared\classes\alfresco\web-extension.  Open the web-framework-config-custom.xml file and if you scroll to the bottom, you will see the following extract:


<config evaluator="string-compare" condition="Remote">
<remote>
<endpoint>
<id>alfresco-system</id>
<name>Alfresco - System access</name>
<description>System account access to Alfresco</description>
<connector-id>alfresco</connector-id>
<endpoint-url>http://localhost:8080/alfresco/s</endpoint-url>
<identity>declared</identity>
<username>admin</username>
<password>admin</password>
<unsecure>true</unsecure>
</endpoint>
<!-- The default endpoint -->
<default-endpoint-id>alfresco-system</default-endpoint-id>
</remote>
</config>

This extract configures the remote Alfresco repository as an end-point.  You may also notice just above this that there is another entrance as follows:

<!-- Webapp Resource Resolver -->
<resource-resolver>
<id>webapp</id>
<name>Alfresco Web Application Resource Resolver</name>
<description>Resolves data access for web application assets</description>
<class>org.alfresco.web.framework.resource.AlfrescoWebProjectResourceResolver</class>
<alias-uri>/files</alias-uri>
<store-id>demo</store-id>
</resource-resolver>


This lets Surf bind to web application resources, like static files, in this case, the actual product XML item we wish to view.

With the end-point and resource resolver in place we can call the remote web script.  So the process is fairly straight forward – the Surf component calls the remote web script that returns a list of products via JSON.  We then need a way to load an appropriate template to display each product, and that is done by a page-association item.  This tells Surf that there is an association between the content that is being loaded and the template we would like to use to display it.  Take a look at C:\surf-sample\sample\deploy\alfresco\site-data\page-associations\products.xml:

<?xml version="1.0" encoding="UTF-8"?>
<content-association>
<source-id>{http://www.alfresco.org/model/wcmmodel/1.0}avmplaincontent</source-id>
<dest-id>products</dest-id>
<assoc-type>content-type</assoc-type>
<format-id>default</format-id>
</content-association>

You can see here that the source-id is “{http://www.alfresco.org/model/wcmmodel/1.0}avmplaincontent” and that the dest-id is “products” meaning that all content of the type avmplaincontent would be rendered via the “products” template.

Summary

Hopefully this provides a preview of how nicely WCM content will integrate with Surf powered websites, and Web Studio is also on the horizon to complete the suite.  As noted previously, this Surf configuration and setup is based on the Surf Deployment Configurations wiki article which I would highly recommend reading.  This provides a really good and detailed overview of other possible Surf configurations.

Thanks to Michael Uzquiano for all the assistance!