I have recently been involved with a few projects that involved Share customization. I think there are two approaches to Share customization, one, to modify Share using custom dashlets and themes, and two, to modify Share by adding Surf pages, templates, and components. Of course you could take a hybrid approach if it suits your needs as well. In this article I will be talking about the latter and cover how you add a new page to Share. If you want to learn how to create a Share Eclipse project, see my previous post Alfresco Share Customization – Sample Eclipse Project.


First lets go over the high level steps that will be required to add a new page to Share. Share is a Spring Surf application built on top of the Alfresco repository. In order to build a new page we will need to add a Surf page, template instance, and template. It is a best practice to allow easy localization and internationalization by using a properties file for application messages, so we will add a properties file and load it via a custom Spring context file. And finally, in order to add our new page to Share we will need to add it to the current site pages and site template presets file.

Adding the Surf Page

Pages are found in our sample project in /Demo-Share/config/web-extension/site-data/pages. We are going to create a file called home.xml which defines our "home" Surf page. The contents of the file look like this:
<?xml version='1.0' encoding='UTF-8'?> <page> <title>Demo Home</title> <title-id>page.demoHome.title</title-id> <description>Demo Home Description</description> <description-id>page.demoHome.description</description-id> <template-instance>home-three-column</template-instance> <authentication>none</authentication> </page>
The XML is pretty self explanatory here. There is a page element which includes a few elements describing the Surf page. The title element is what is displayed in the web browser and is used in the navigation in Share. The title-id element replaces the title element and is loaded from the properties file. The description and description-idare analogous to the title and title-id. The template-instance element contains the name of the template instance XML definition file, which is discussed next. And finally theauthentication element defines what authentication is required to access the page. Valid values are none, user, and admin.

Adding the Surf Template Instance

Template instances are found in our sample project in /Demo-Share/config/web-extension/site-data/template-instances. We are going to create a file called home-three-column.xml which defines our "home" Surf template instance. The template instance effectively ties the Surf page to the Surf template. The contents of the file look like this:
<?xml version='1.0' encoding='UTF-8'?> <template-instance> <template-type>com/tribloom/demo/home</template-type> <properties> <pageFamily>home</pageFamily> <container>home</container> </properties> </template-instance>
Again, the XML is pretty self explanatory. Inside the template-instance element is a series of elements describing the Surf template instance. The template-type element points to the location of our Freemarker home.ftl file which we will discuss in more detail shortly. The properties element contains a pageFamily element and containerelement, both of which are used by Share for navigation related functions (i.e. highlighting the current page in the navigation component).

Adding the Surf Template

Templates are found in our sample project in /Demo-Share/config/web-extension/templates/com/tribloom/demo. We are going to create a file called home.ftl which defines our "home" Surf template using Freemarker. You could user plain HTML in yourhome.ftl template and ignore Freemarker altogether which is essentially what we do in this example. The contents of the file look like this:
<head></head> <body><h1>This is just a test page. Hello World!</h1></body>
This is a very simple example with a "hello world" HTML snippet to demonstrate adding a page to Alfresco Share rather than the complexities of Surf and creating and adding Surf components.

Adding the Properties File

Properties files are found in our sample project in /Demo-Share/config/web-extension/messages. We are going to create a file called demo.properties. The contents of the file look like this:
## Custom Messages for Demo Share Site page.demoHome.title=Demo Home (from Properties) page.demoHome.description=Demo Home Description (from Properties)
You may notice that the title-id and description-id elements in the page definition,home.xml, match the keys in our properties file. These will be picked up and used for the title and description by the application. In order for the new properties file to be loaded by Spring we need to add it to a new file located in /Demo-Share/config/web-extension called custom-slingshot-application-context.xml. The contents of the file look like this:
<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'> <beans> <!-- Override - Add in the custom Demo Site Messages --> <bean id="webscripts.resources"> <property name="resourceBundles"> <list> <value>webscripts.messages.webscripts</value> <value>alfresco.messages.common</value> <value>alfresco.messages.slingshot</value> <value>alfresco.web-extension.messages.demo</value> </list> </property> </bean> </beans>
You will note that the last value element contains the path to our new demo properties file.

Adding the Page to Current Site Pages

We will need to create a file called share-custom-config.xml file, located in our sample project in /Demo-Share/config/web-extension. The contents of the file look like this:
<share-config> <!-- Add a custom page type --> <config evaluator="string-compare" condition="SitePages" replace="true"> <pages> <page id="calendar">calendar</page> <page id="wiki-page">wiki-page?title=Main_Page</page> <page id="documentlibrary">documentlibrary</page> <page id="discussions-topiclist">discussions-topiclist</page> <page id="blog-postlist">blog-postlist</page> <page id="links">links</page> <page id="tasks">tasks</page> <page id="home">home</page> </pages> </config> </share-config>
This file is actually overriding the file share-config.xml found in the share.war file in /WEB-INF/classes/alfresco. Note the replace="true" attribute of the config element. This is saying that we are replacing the contents of the share-config element in share-config.xml with the new share-config element in share-config-custom.xml. The only change is the addition of the new page element <page id="home">home</page>which adds our new home page into Share. If we have an existing site and want to manually add the home page to it, we can go to the site as an admin user, click on the more drop down box in the upper right, select customize site, click the add pages button, and select our new home page. You should see something like the image below.Adding a new page to Share

Modifying the Presets File

The presets file is used by Share as a template for creating new Share sites. The presets file is found in /Demo-Share/config/web-extension/presets. We are going to create a file calledpresets.xml. Most of the content will be copied from the original Share version of the file and we are making just s small edit. You can find the original file at /Share/WEB-INF/classes/alfresco/site-date/presets/presets.xml. You will want to copy the presetelement with the id attribute "site-dashboard". Here is an excerpt of the contents of the new file:
<?xml version='1.0' encoding='UTF-8'?> <presets> <!-- Well known preset used to generate the default Collaboration Site dashboard --> <preset id="site-dashboard"> ... <pages> <page id="site/${siteid}/dashboard"> <title>Collaboration Site Dashboard</title> <title-id>page.siteDashboard.title</title-id> <description>Collaboration site's dashboard page</description> <description-id>page.siteDashboard.description</description-id> <template-instance>dashboard-3-columns</template-instance> <authentication>user</authentication> <properties> <sitePages>[{"pageId":"home"}, {"pageId":"wiki-page"}, {"pageId":"blog-postlist"}, {"pageId":"documentlibrary"}, {"pageId":"calendar"}, {"pageId":"links"}, {"pageId":"discussions-topiclist"}] </sitePages> </properties> </page> </pages> </preset> </presets>
What we added is {"pageId":"home"}, in the site-pages element. This adds our new home page to the site preset and when a new Share site is created our page will be included in the navigation. (On recent testing a server restart was required after the site is created in order for new page to show up in the navigation)

Wrap Up

Now that everything is in place you may point your browser tohttp://localhost:8080/share/page/user/admin/home (the default host, port and application context, modify this if your installation uses a different host, port or application context). Since our Surf page definition used none for the authentication element, you do not need to login to Share in order to see your new page. What you should see in your browser is a simple page that displays:

This is just a test page. Hello World!

Unless you are doing some very heavy Share customization, you will want your new page to look like Share with the same header, navigation, and footer components as the rest of the Share site. We are going to cover this in a future article along with writing your own components.

Here is a link to the sample Alfresco Share Customization Eclipse project for adding a new page to Share.


Loading Conversation