Advanced Share Customization (part 1)

ddraper · ‎1 Nov 2011

Introduction

At DevCon in San Diego last week I got asked a number of times how possible it would be to either radically customize Share or add entirely new pages to it. I got the opportunity to demonstrate how easy this was and realised that it would probably be a good basis for a blog. In this first post I'm going to demonstrate how to add a new page to Alfresco Share (and have it protected by the standard authentication mechanism) and make it the application landing page. In the next post I'll show how to replace the default login form and provide a link to a stripped down document library page.

Step 1: Add a new page

Adding a new page into Alfresco Share is almost trivially easy and can be done in a minimum of three files:

A Page definition file
A Template-Instance definition file
A FreeMarker template file

Stripping these files to the bare minimum content these should look as follows:

Page definition ('home-page.xml')

This file defines the page to name (which is the file name) and a mapping to a Template-Instance that contains the content. It also defines the level of authentication required to view the page.

<page>
   <template-instance>home-page</template-instance>
   <authentication>user</authentication>
</page>‍‍‍‍

Template-Instance definition ('home-page.xml')

This creates a mapping to the actual FreeMarker template that contains the content for the page.

<template-instance>
   <template-type>blog/demo/home-page</template-type>
</template-instance>‍‍‍‍‍‍

FreeMarker template file ('home-page.ftl')

This contains the actual page content. The example shown here is trivial but this could also contain regions for binding Spring Surf components if required.

<html>
   <head>
      <title>Blog Application</title>
   </head>
   <body>
      Welcome To Extreme Share Customization!
   </body>
</html>‍‍‍‍‍‍‍‍

The files should be build into a JAR file in the following structure:

/alfresco/site-data/pages/home-page.xml
/alfresco/site-data/template-instances/home-page.xml

/alfresco/templates/blog/demo/home-page.ftl

Assuming that you are running on Tomcat, copy the JAR file into either 'webapps/share/WEB-INF/lib' or '<tomcat-home>/shared/lib'. If you're not running on Tomcat then you'll need to adjust the location to suit your specific web server. You'll need to ensure that your Tomcat server is correctly configured if you wish to use '<tomcat-home>/shared/lib' and you should be aware that the page you have defined will be available to all Spring Surf based applications running on that web server!!

Restart your web server and then open the following location in your browser to 'http://localhost:8080/share/page/home-page' (adjust the port as necessary for your application configuration!). You will be prompted with the standard Alfresco Share login screen - this is because the page has specified and authentication level of 'user'. If you want only your administrator to access the page then you could set this as 'admin' and if you want the page to be public you could set it to 'none'.

The key thing to note here is that although your page effectively belongs to the Alfresco Share application your FreeMarker template can contain any HTML/JavaScript/CSS that you wish - you are not tied into using YUI2 as is used in the implementation of Alfresco Share - should you wish to write a page a page in JQuery or Dojo or pure HTML (or anything else) then you are quite at liberty to do so.

Also, as well as being able to re-use the standard Alfresco Share authentication mechanism you are also able to easily access all the WebScripts available on both the Web and Repository tiers. This means you can easily build your own UI around existing Alfresco functionality.

When bringing in resources (such as images, JavaScript and CSS files) it's important to remember that you should place them under the META-INF folder in your JAR and use the '/res' prefix on the requests to access them (e.g. request the file 'META-INF/blog/demo/example.css' using the URL '/share/res/blog/demo/example.css'.

Step 2: Make the new page the landing page

PLEASE NOTE: Whilst writing this section I discovered a couple of bugs in the Spring Surf code which have been fixed. In order to make sure this example works you will either need to build the latest version of Alfresco or wait for version 4.0.c

Spring Surf supports the notion of a default page which is defined in the site configuration (that's site as in 'Web Site', rather than the Alfresco Share concept of site!). By default the default page is the 'site-index.jsp' which works out and redirects to the authenticated users dashboard page. A the site default page will be rendered when a request is mapped to the Spring MVC RequestDispatcher (which by default is at '/page' and '/p') but no page is included in the request (e.g. '/share/page'). This is also configured as the 'welcome-file' in the Share 'web.xml' file.

In order to change the landing page for the application you can simply override the default site configuration for Alfresco Share. The site configuration used is defined in 'surf.xml' and is set to 'slingshot.site.configuration' by default.

To customize Alfresco Share to use our new landing page you simply need to create a file called 'slingshot.site.configuration.xml' containing the following:

<configuration>
   <source-id>site</source-id>
   <properties>
      <root-page>home-page</root-page>
   </properties>
</configuration>‍‍‍‍‍‍

Build the file into your JAR at the following location:

/alfresco/web-extension/site-data/configurations

Note that the file needs to under the 'web-extension' path in order that it gets resolved before the Alfresco Share default!

After deploying your JAR file and restarting the web server you should find that when you point your browser at 'http://localhost:8080/share' you will be taken to your new page by default (after you login of course!)

Advanced Share Customization (part 1)

Advanced Share Customization (part 1)

Introduction

Step 1: Add a new page

Step 2: Make the new page the landing page

We use cookies on this site to enhance your user experience