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!)
31 Comments
We use cookies on this site to enhance your user experience
By using this site, you are agreeing to allow us to collect and use cookies as outlined in Alfresco’s Cookie Statement and Terms of Use (and you have a legitimate interest in Alfresco and our products, authorizing us to contact you in such methods). If you are not ok with these terms, please do not use this website.