Views
Share Custom Pages
From alfrescowiki
Contents |
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.
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:
<?xml version='1.0' encoding='UTF-8'?> <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
<?xml version='1.0' encoding='UTF-8'?> <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.
<@templateHeader "transitional">
<@link rel="stylesheet" type="text/css" href="${page.url.context}/themes/${theme}/header/header.css" />
<@link rel="stylesheet" type="text/css" href="${page.url.context}/themes/${theme}/style.css" />
</@>
<@templateBody>
<div id="alf-hd">
<@region id="header" scope="global" protected=true />
<@region id="title" scope="global" />
</div>
<div id="bd">
<div id="content">
<div id="left" class="sidebar">
<@region id="left" scope="page" />
</div>
<div id="center">
<@region id="center" scope="page" />
</div>
<div id="right">
<@region id="right" scope="page" />
</div>
</div>
</div>
</@>
<@templateFooter>
<div id="alf-ft">
<@region id="footer" scope="global" />
</div>
</@>
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
<?xml version='1.0' encoding='UTF-8'?> <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
<?xml version="1.0" encoding="UTF-8"?>
<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:
