Ben's Blog » wcm

Web Quick Start Videos

admin — Fri, 26 Nov 2010 15:27:03 +0000

The following are short (less than 10 minutes) introductory videos to features of the Alfresco Web Quick Start. I plan to record several over the next few weeks covering topics such as installation, renditions, asset collections, user generated content, publishing etc.

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.

SURF Part 3 – Alfresco WCM Content

admin — Mon, 09 Mar 2009 18:24:02 +0000

**NOTE: This articles uses features found in HEAD which are considered to be work-in-progress. This article is for demo purposes only.**

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:

C:\surf-sample\sample\deploy\alfresco admin admin C:\surf-sample\sample\deploy\webroot admin admin
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:

/surf-sample/sample/deployalfresco/site-webscripts

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:
page main index /component/common/include div /content/news/latestNews.html

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:

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:

alfresco-system Alfresco - System access System account access to Alfresco alfresco http://localhost:8080/alfresco/s declared admin admin true alfresco-system
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 Alfresco Web Application Resource Resolver Resolves data access for web application assets org.alfresco.web.framework.resource.AlfrescoWebProjectResourceResolver /files demo

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:
{http://www.alfresco.org/model/wcmmodel/1.0}avmplaincontent products content-type default
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!

Screencast – Deployment And Delivery Overview – Static Content

admin — Wed, 25 Feb 2009 12:16:19 +0000

This screencast covers the basics of Deployment And Delivery of Static Content using Alfresco WCM. It was written towards the end of 2008 and is available also on the Content Community for download, along with sample files.

Its designed as a basic introduction to the WCM product and provides information on :

Setting up a web project
Importing content
Basic content editing/authoring
Simple deployment using an File System Receiver (FSR)

SURF Part 2 – Pages and Navigation

admin — Thu, 19 Feb 2009 15:59:41 +0000

During part 1, the process of creating a simple web page using the SURF framework was discussed detailing creating a basic template and various components. Next I will look at adding additional pages and building some simple navigation utilising SURF’s “Page Association” features.

Setup

If you have not got the basic home page up and running from part 1, download the sample web application here and deploy to your local Tomcat (or any other web app server). Once installed and started you should be able to hit the home page using http://localhost:8080/surf/page?p=index as long as you are using your local machine and have not renamed the web app folder. You should then get the HTML template home page as follows:

Overview

The process of creating a new page is relatively simple. It basically involves creating a new “page” item, and the relevant components that will make up that page as covered in part 1. In this example I am also going to introduce a new template so that we have a different layout for our new page. Here is an overview of the steps involved:

Create the new FTL template file (for the different layout)
Create the new “template instance” so that the new template can be referenced from a page component
Create the new page component

I will then move on the introduce some simple navigation using the Page Association item.

Templates and Pages

As noted, the process for creating the new template and page is identical to that covered in part 1 and therefore I will not describe the code in detail. If you are in any doubt, refer to Part 1 accordingly.

I have decided to introduce a new template so that we can use a different page layout from that of the home page. I have called this template “content.ftl” as it is a generic page for displaying any type of content.

Start by preparing a basic HTML page that will be used as a generic “content” page. If you downloaded an HTML template for part 1, perhaps a second content page was also provided. If not, you can take a copy of the current home page template. It does not really matter at this stage what it looks like, as long as you can see it is different from your current home page layout. You can always come back later and make CSS and other layout changes. If you are using the template that is included as part of the download, you can use the following example content.ftl page:
<@region id="top" scope="global" />



<@region id="header" scope="global" />





Example list item


Example list item


Example list item


Example list item








Aliquam metus turpis, luctus ac, sagittis eget




Suspendisse egestas fringilla odio. Donec lacinia tristique ante. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Etiam 




<@region id="footer" scope="global" />

You will note above that I have included the different components that we have available using the tag. This just allows us to re-use the global components we require e.g. header and footers.

Create the new content.ftl file in the /WEB-INF/classes/alfresco/templates directory.
Copy in your source HTML for your new layout, or the above example code into the new content.ftl file.
Add in your global components where needed e.g. headers and footers using the tag.
Create a new template instance file in /WEB-INF/classes/alfresco/site-data/template-instances named content.xml. You can copy the current “index.xml” file and remember to amend the to point to the new content template.
Now create the new page. Lets create a page called “products“. Create the page xml item within /WEB-INF/classes/alfresco/pages named products.xml. Remember to reference the new content template instance.

Once this is complete, you should be able to manually request the page to test it using http://localhost/surf/page?p=products. Here is my example products page using the “content.ftl” template:

You can now go ahead and componentise the new page as you wish. Perhaps separate the main content from the left pane and create web scripts to return the HTML where required.

Is is important that the navigation pane is componentised, as this is what we will be working with. The image below shows the navigation component:

Here are the steps involved to create the navigation component:

Create the new component in /WEB-INF/classes/alfresco/site-data/components. I have named my example global.nav.xml as this will be a globally scoped/used component.
Create a new web script FTL and descriptor file within /WEB-INF/classes/alfresco/site-webscripts. Remember to match the same URL references as defined within the component.
Chop out the HTML for the header navigation into the web script FTL file.
Include the component using the region tag into both the index and content template files:

<@region id="nav" scope="global" />

Test the pages so that the new nav component is being included correctly on both the index and the products pages.

We can now go ahead and create some dynamic navigation using Page Associations.

Page Association

From the Alfresco Wiki page – The Page Association objects allows you to link two pages together. Most commonly, this link is of type child and is meant to depict a fixed structure like a navigation tree. However, other types are possible and there is no requirement to use Page Associations as a means to support only a single fixed tree.

Using associations, multiple trees are possible. The nature of the associations, when expanded beyond child, is very similar to that of classifiers, categories, or tags. In other words, Pages may be associated to other pages, but they may also be laterally associated to other elements. This allows for implementations of faceted navigation and tag clouds.

In this example, we will create a very simple navigation to link the Home page (index) to the new Products page. To do this we will create a page association item.

Create a new Page Association item within /WEB-INF/classes/alfresco/site-data/page-associations named index-products.xml
Add the following code. Note the source and destination id’s relate the pages together:

index products child 1

Once the association file is in place, we now need to modify the global nav web script to process the relationships and display the menu. You should already have in place the nav.get.desc.xml file and nav.get.html.ftl (or files of similar name and purpose) web script files which currently just return the example menu HTML code, nothing dynamic.

In order to process the menu items, we will need to include some logic making use of a JavaScript file as part of the web script.

Create a nav.get.js (or relative name if your nav web script is named differently) file within the web scripts directory – /WEB-INF/classes/alfresco/site-webscripts.

// renderer attribute var renderer = instance.properties["renderer"]; if(renderer == null) { renderer = "horizontal"; } model.renderer = renderer;
// set up rendering attributes model.rootpage = sitedata.getRootPage(); model.linkbuilder = context.getLinkBuilder();

This code makes use of an example basic navigation component with horizontal and vertical renderers. This is included as part of the surf starter war.

Edit the nav.get.html.ftl file and remove the static HTML content. Add the following code:

<#if renderer == "horizontal"> <@horizontal page=rootpage showChildren=true/> <#macro horizontal page showChildren>





<#assign href = linkbuilder.page(page.id, context.formatId)>

<#assign classId = ''>

<#if page.id == context.page.id>

<#assign classId = 'current'>



${page.title}



<#-- Children of Home Page -->

<#list sitedata.findChildPages(page.id) as parentPage>



<#assign href = linkbuilder.page(parentPage.id, context.formatId)>

<#assign classId = ''>

<#if parentPage.id == context.page.id>

<#assign classId = 'current'>



${parentPage.title}

The above code makes use of the findChildPages(sourceId) Surf API call which simply finds all child page objects for the given top level page id. It also demonstrates usage of the linkBuilder facility which dynamically creates the URL. You will also notice that a style is being applied if we are viewing the current page i.e. parentPage.id == context.page.

This example could easily be extended for second level navigation simply by passing in the parent item id:
<#-- Children of Home Page --> <#list sitedata.findChildPages(page.id) as parentPage> <#-- Sub Pages --> <#list sitedata.findChildPages(parentPage.id) as childPage>

This is a simplified version of the navigation code used within the Green Energy site which is part of the Alfresco Surf Code Camp material. Jeff Potts has kindly made this available for download, and I would recommend taking a look to learn more about Surf in general (including an example of second level navigation).

Refresh the web scripts using http://localhost:8080/surf/service/

You should now have working navigation showing the Home page and the Products page:

Summary

Here we have just created a new template (so we can alter the style of the page), and created a new page using the new template. We then created a simple page association so that the navigation item could build the links. You can probably start to see how useful Web Studio will be, allowing new pages and navigation to be created using a GUI rather than hand coding each new page.

Next I will look at using Alfresco WCM with Surf, along with some deployment options.

Download

The completed web application is available for download here – SURF Part 2 – Pages and Navigation.