Share Custom Pages

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Table of Contents

• 1 Overview


• 2 Create a Custom Static Webpage in Share
  
  
  
  • 2.1 Define the Page
  
  
  • 2.2 Define the Template Instance
  
  
  • 2.3 Define the Template
  
  
  • 2.4 Regions and Scope
  
  
  • 2.5 Components
    
    
    
    • 2.5.1 Component Declaration
    
    
    • 2.5.2 Component Definition
    
    
  
  


• 3 References

Overview

Static pages on Alfresco use an MVC-type pattern. A Page uses a Template-Instance which references a Template, which defines the page layout as Regions. Components are bound to Regions. When a Page is rendered, the Template's Regions act as containers for Components, which are displayed on the page.

Components can be (and often are) WebScripts.

This writeup puts all customizations into the tomcat/shared/classes/alfresco/web-extension/ folder so that it does not interfere with the regular Alfresco codebase.

Create a Custom Static Webpage in Share

Define the Page

The Page is the most basic component. Let's create the Home page:

tomcat/shared/classes/alfresco/web-extension/site-data/pages/home.xml:

<page>
<title>Home</title>
<description>My Home Page</description>
<template-instance>home</template-instance>
<authentication>none</authentication>
</page>

Define the Template Instance

The Template-Instance references a Template. Let's create that reference:

tomcat/shared/classes/alfresco/web-extension/site-data/template-instances/home.xml

<template-instance>
  <template-type>com/myco/home</template-type>
</template-instance>

I like to put all my customizations and pages into my own path (com/myco) under web-extension/templates/. But you can put the template directly into the templates/ folder if you wish. In this case set <template-type>home</template-type>.

Define the Template

tomcat/shared/classes/alfresco/web-extension/templates/home.ftl

Note the ftl extension. Alfresco uses the FreeMarker Template system by default. (I'm not sure if it's possible to use a different templating system, but it seems like it may be - something to explore.)

The following template uses a 3-column layout.

The template defines 'regions' which are containers for components. The 'scope' of a region defines the visibility of the component. Components can be defined to be within Page, Template or Global scope.

Regions and Scope

Components

Components are defined within a region and scope. In the template above, we have:

• Region = header; Scope = global
  
• Region = title; Scope = global
  
• Region = left; Scope = page
  
• Region = center; Scope = page
  
• Region = right; Scope = page
  

Component Declaration

We now need to create the components to put into these regions. Components are declared in the web-extension/site-data/components folder as <scope>.<regionid>.<page>.xml. <page> is not relevant for global scope. In this case we would have the following files:

• global.title.xml
  
• global.header.xml
  
• page.left.home.xml
  
• page.center.home.xml
  
• page.right.home.xml
  

Just to show a mix of locations, I'm going to leave the global.title.xml as the default that Alfresco creates, which is located in tomcat/webapps/share/WEB-INF/classes/alfresco/site-data/components/global.header.xml. No need to customize this for now.

Following are the declarations for each of the components:

• global.title.xml
  

<component>
  <scope>global</scope>
  <region-id>title</region-id>
  <source-id>global</source-id>
  <url>/com/myco/components/global/title</url>
</component>

• page.left.home.xml
  

<component> 
  <scope>page</scope>  
  <region-id>left</region-id>  
  <source-id>home</source-id>  
  <url>/com/myco/components/home/left</url>  
  <guid>page.left.home</guid>  
  <properties> 
    <height>434</height>
  </properties> 
</component>

Component Definition

Components are finally webscripts. A webscript consists of a collection of files:

• .get.desc.xml - the descriptor file
  
• .get.head.ftl - header declarations for JS and CSS includes (for example)
  
• .get.html.ftl - freemarker template that renders the HTML
  
• .get.js - server-side javascript for this component
  
• .get.properties - properties to be rendered with variables in the freemarker template
  

There may also be client-side javascript, which is defined in the .get.head.ftl file, and usually stored in the webapps/share/components/ folder. To start off, let's have the left component be exactly the same as the my-sites dashlet. Do the following:

cp tomcat/webapps/share/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/dashlets/my-sites.* \
 tomcat/shared/classes/alfresco/web-extension/site-webscripts/com/myco/components/home/
cd tomcat/shared/classes/alfresco/web-extension/site-webscripts/com/myco/components/home/
rename -v 's/my-sites/left/' my-sites.*

You'll now have all the pieces from which to tinker. Keep in mind that the my-sites dashlet has some dependencies (component.head.inc, alfresco-template.ftl, etc.) which you'll need to copy over to the appropriate places. OR you can pare down the dashlet to bare-bones.

References

The following sites were very helpful for understanding how Alfresco's Share interface works:

• Ed Loves Java's Adding New Pages to Share
  
• Getting Started with Alfresco Surf series
  

Customizing and Extending