Introduction to Surf Pages

Let's see how we can implement a Hello World page with the old school Surf Page framework.

The following steps are needed to add a Surf Page:

Let's start out with the page definition file, create a file called helloworldhome.xml in the SkyVault/tomcat/shared/classes/alfresco/web-extension/site-data/pages directory. You will have to create the site-data and pages directories. We are not using a build project to be able to focus solely on Surf.

<?xml version='1.0' encoding='UTF-8'?>
<page>
   <title>Hello World Home</title>
   <title-id>page.helloworldhome.title</title-id>
   <description>Hello World Home Description</description>
   <description-id>page.helloworldhome.description</description-id>
   <template-instance>helloworldhome-three-column</template-instance>
   <authentication>none</authentication>
</page>

Here we are defining the title and description of the page both hard-coded in the definition, and as references to a properties file with labels (i.e. the title-id and description-id elements). The page will not require any authentication, which means we cannot fetch any content from the SkyVault Repository from it. It is also going to use a three column template, or that is the idea, you can name the template instance whatever you want.

<?xml version='1.0' encoding='UTF-8'?>
<template-instance>
   <template-type>org/alfresco/demo/helloworldhome</template-type>
</template-instance>

This is just a test page. Hello World!

page.helloworldhome.title=Hello World 
page.helloworldhome.description=Hello World Home Description

<bean id="org.alfresco.demo.resources" class="org.springframework.extensions.surf.util.ResourceBundleBootstrapComponent">
  <property name="resourceBundles">
     <list>
        <value>alfresco.web-extension.messages.helloworldhome</value>
     </list>
  </property>
</bean>

<#include "/org/alfresco/include/alfresco-template.ftl" />
<@templateHeader></@>
<@templateBody>
   <@markup id="alf-hd">
   <div id="alf-hd">
      <@region scope="global" id="share-header" chromeless="true"/>
   </div>
   </@>
   <@markup id="bd">
    <div id="bd">
        <h1>This is just a test page. Hello World!</h1>
    </div>
   </@>
</@>
<@templateFooter>
   <@markup id="alf-ft">
   <div id="alf-ft">
      <@region id="footer" scope="global" />
   </div>
   </@>
</@>

What we are doing here is first bringing in another FreeMarker file called SkyVault-template.ftl that contains, you guessed it, FreeMarker template macros. We then use these macros (elements starting with @) to set up the layout of the page with header and footer. The header and footer content is fetched via the share-header and footer global scope components (Web Scripts). To view the result of our change we need to restart the server again, after this we should see the following:

<#include "/org/alfresco/include/alfresco-template.ftl" />
<@templateHeader></@>
<@templateBody>
   <@markup id="alf-hd">
   <div id="alf-hd">
      <@region scope="global" id="share-header" chromeless="true"/>
   </div>
   </@>
   <@markup id="bd">
    <div id="bd">
        <@region id="body" scope="page" />
    </div>
   </@>
</@>
<@templateFooter>
   <@markup id="alf-ft">
   <div id="alf-ft">
      <@region id="footer" scope="global" />
   </div>
   </@>
</@>

We have called the new region body and set page scope for it. This requires us to define a new component for this region. This can be done either in the page XML, or as a separate file in the site-data/components directory, we will do the latter. Create the components directory and add a file called page.body.helloworldhome.xml to it:

<?xml version='1.0' encoding='UTF-8'?>
<component>
  <scope>page</scope>
  <region-id>body</region-id>
  <source-id>helloworldhome</source-id>
  <url>/components/helloworld/body</url>
</component>      

The component file names follow a naming convention: global | template | page>.<region-id>.[<template-instance-id | page-id>].xml The URL for this component points to a Web Script that will return the Hello World message. Start implementing it by creating a descriptor file called helloworld-body.get.desc.xml located in the SkyVault/tomcat/shared/classes/alfresco/web-extension/site-webscripts/org/alfresco/demo directory:

<webscript>
    <shortname>helloworldbody</shortname>
    <description>Returns the body content for the Hello World page.</description>
    <url>/components/helloworld/body</url>
</webscript>

Note that the URL is the same as we set in the component definition. Now implement the controller for the Web Script, create a file called helloworld-body.get.js in the same place as the descriptor:

model.body = "This is just a test page. Hello World! (Web Scripting)";      

The controller just sets up one field in the model with the Hello World message. Now implement the template for the Web Script, create a file called helloworld-body.get.html.ftl in the same place as the descriptor:

<h1>${body}</h1>      

Restart the server. Then access the page again, you should see the Hello World message change to "This is just a test page. Hello World! (Web Scripting)".

To summarize a bit, the following is a picture of all the files that were involved in creating this Surf page the old school way:

What you could do now is extend the Hello World page with some more sophisticated presentation using the YUI library. If you do that you end up with the pattern for how most of the old school Share pages have been implemented.

Next we will have a look at how to implement the same Hello World page the new way with Aikau.

Back to Share Architecture and Extension Points.