OverviewWhen adding a page to Share, you will probably want your page to match Share's look and feel. In order to do this we will need to discuss Surf Regions, Surf Components, and Alfresco Share's base template that is used to standardize the definition of a Share Surf template. If you want to learn how to add a page to Share, see my previous post Alfresco Share Customization – How To Add a New Page.
Surf RegionsConceptually a web site has pages. Similar layouts in the pages can be identified and standardized into Surf templates. Each region of the page can be defined as a Surf region. Regions are defined in templates using a Freemarker macro. They can have global, template, or page scope. Here are some examples of global, template and page scoped region tags that you might see in a Surf template:
<@region id="header" scope="global"> <@region id="navigation" scope="template"> <@region id="content" scope="page">You can see the idea from the ids of these regions that a global region is something that you would see on every page in the site like headers and footers. Template scoped regions are regions that are included in more than one page consistently like navigation. Page scope regions are unique to a single page.
ComponentsComponents are pieces of content that are defined by REST URL. Components are tied to Surf regions using component bindings, which are found in /web-extension/site-date/components. Components can be reused in any number of pages or templates. The URL that a component is tied to can be any RESTful API including webscripts. Here are several examples of component definitions for global, template, and page scoped components:
<?xml version='1.0' encoding='UTF-8'?> <component> <scope>global</scope> <region-id>header</region-id> <source-id>global</source-id> <url>/components/header/header</url> </component>This would be defined in a file located in /Demo-Share/config/web-extension/site-data/components and called global.header.xml. The scope element defines the scope of the page,
global, <code>template or
page. The <code>region-id element corresponds to the region id, as defined in your template region macro (examples given above in the Regions section). The
source-idelement corresponds to <code>global for global scoped components, the template instance id for template scoped components, or page id for page scoped components. Here is an example of a template scoped component:
<?xml version='1.0' encoding='UTF-8'?> <component> <scope>template</scope> <region-id>navigation</region-id> <source-id>home-three-column</source-id> <url>/demo/components/navigation/navigation</url> </component>Here is an example of a page scoped component:
<?xml version='1.0' encoding='UTF-8'?> <component> <scope>page</scope> <region-id>content</region-id> <source-id>home</source-id> <url>/demo/components/content/content</url> </component>You may notice that the URL defined in the url element seems repetitive. This is because more complicated websites will have webscripts with similar functionality grouped together into a single directory. An example is a blog. You might have a webscript that shows new blog posts, a webscript that shows popular blog posts, and a webscript that shows all blog posts. It makes sense to group these into a similar looking URL such as these:
/demo/components/blog/new /demo/components/blog/popular /demo/components/blog/allIt is a good practice to get into the habit of grouping your webscripts now so you don't have to go back and refactor and regroup them later.
<#include "/org/alfresco/include/alfresco-template.ftl" />The macros that are provided to us in the alfresco-template.ftl are
templateBody, and <code>templateFooterregions. These define areas in the page for header, body and content using HTML. We have included several
regiontags as well. The global scoped <code>region tags will pick up the Share components. The template scoped regions will need to have components defined. We can reuse the existing webscripts that back the components but we will have to write a bit of XML.
Adding ComponentsWe need to add a component definition for the title and navigation regions that are defined in our new Home template. These regions are defined as template scope in Alfresco's Share pages so we will do the same for our page. The component files should go into /Demo-Share/config/web-extension/site-data/components/. We are going to create two new filestemplate.navigation.home-three-column.xml template.title.home-three-column.xml. The files follows a naming convention of
<?xml version='1.0' encoding='UTF-8'?> <component> <scope>template</scope> <region-id>navigation</region-id> <source-id>home-three-column</source-id> <url>/components/navigation/collaboration-navigation</url> </component>The elements in the XML file are analogous the the file naming convention. The
scopeelement contains <code>global,
template, or <code>page. The
region-idelement contains the region id that you defined in your template file. The <code>source-id contains
global, the template id, or the page id depending on the scope of the component. The <code>url element contains the relative url to the webscript that backs the component. I will leave it up to you to write the other component file (or you can cheat and download the eclipse project).
Wrap UpWhen you deploy the new changes and restart your app server and navigate to the home page that we have added, you should get a page that looks very similar to the last project's page, except that this one has Alfresco's header, footer and navigation components!
Here is a link to the sample Alfresco Share Customization Eclipse project for making your pages look like Share.