How To Add Content To An Alfresco Share Page

[ddraper]

Introduction

This is the first in a series of blogs that is going to describe some of the new extensibility features that are now available in the latest Alfresco Community source code and will later appear in Alfresco Enterprise 4.0.

A complaint that we sometimes hear about Alfresco Share is that it is not particularly easy to customize. So for Alfresco Enterprise 4.0 we're going to provide a number of different ways in which to make customization easier. One of the ways that it will be possible to do this is by taking advantage of new extensibility features that have been added into the Spring Surf framework upon which Alfresco Share is built.

The primary goal of these features was to ensure that it wasn't necessary to completely re-write Alfresco Share. Although we wanted to introduce new concepts, we didn't want to force developers to completely re-learn how Alfresco Share is put together.

In later blogs I'm going to explore the new framework in detail and describe all the features and exactly what's changed, but as an introduction I'd like to demonstrate how to add some new content to an existing Alfresco Share page.

Tutorial

The quickest way to add content to an Alfresco Share page is to create the content as a Web Script and then add a new Sub-Component an existing Component on the page.

The content is going to be provided by an Extension Module deployed into Alfresco Share as a JAR file. The JAR file needs to contain the following packages:

• alfresco.site-data.extensions
• alfresco.site-webscripts

First of all, let's create some content as a Web Script, the actual content isn't important so we'll  keep it simple. A Web Script needs a minimum of 2 files; a descriptor and a template (this isn't a blog on Web Scripts so I'm going to assume you know about them, but if you don't - there's lots of information available here.

Create a new file called 'new-content.get.desc.xml' containing the following:

<webscript>
    <shortname>New Content</shortname>
    <url>/blog/demo/new-content</url>
    <family>Blog Demo</family>
</webscript>

Create a new file called 'new-content.get.html.ftl' containing the following:

<div>
    Hello World!
</div>

Build your JAR file so that files are in the 'alfresco.site-webscripts' package. Copy the JAR file into the 'webapps/share/WEB-INF/lib' folder in Tomcat (or the equivalent location in whatever web server you're using) and start (or restart) the server.  It should be noted that placing a JAR in this folder means that the it won't survive an upgrade or WAR re-deploy - but placing it there is sufficient for the purposes of this tutorial.

Open a browser at the URL http://localhost:8080/share/service/index (assuming you're running the server on your local machine and you haven't tinkered with the port and application context settings) and you will be taken to the Web Scripts Home page. Check that you can see a link for 'Browse 'Blog Demo' Web Scripts' (this indicates that your new Web Script has been successfully registered).

We now want to select a location to add our new content - to help with this we're going to use a new tool called 'SurfBug' (which I'll cover in greater detail in a later blog). Log onto Alfresco Share (http://localhost:8080/share) in a separate browser window or tab, then switch back to the 'Web Scripts Home' page and scroll to the bottom and click the button labelled 'Enable SurfBug' (the page should refresh and the button should have changed to say 'Disable SurfBug'.

Switch back to the Alfresco Share window and refresh the page. You should now see that the user dashboard now has some red boxes shown on it indicating the Sub-Components that are present on the page. Click in any of the boxes and a pop-up will be displayed providing information about that Sub-Component and its parent Component.

Click on the title bar and make a note of the 'Component Details', in particular the 'region-id', 'source-id' and 'scope' values which (if you've logged in as 'Admin') will be:

• title
• user/admin/dashboard
• page

This is the information that you'll need to add a new Sub-Component to that existing Component. Create a new file called 'blog-demo.xml' containing the following:

<extension>
    <modules>
        <module>
            <id>Blog Module (New Content)</id>
            <components>
                <component>
                    <region-id>title</region-id>
                    <source-id>user/admin/dashboard</source-id>
                    <scope>page</scope>
                    <sub-components>
                        <sub-component id='New_Content' index='25'>
                            <url>/blog/demo/new-content</url>
                        </sub-component>
                    </sub-components>
                </component>
            </components>
        </module>
    </modules>
</extension>

Note how the target Component is specified using the data taken from SurfBug and how the Sub-Component specifies the URL of the new Web Script created.

Re-build the JAR so that file is placed in the 'alfresco.site-data.extensions' package, copy the new JAR over the old one in the 'webapps/share/WEB-INF/lib' folder and restart the web server.

In order for the new content to be displayed the module needs to be deployed. Module deployment is a new feature in Alfresco 4.0 that is done through a Web Script found at: http://localhost:8081/share/service/modules/deploy. Navigate to this page and you should see a list of 'Available Modules' and a list of 'Deployed Modules'. Initially you should see the following 2 modules available:

• Alfresco Portlet Extension
• Blog Module (New Content)

Select 'Blog Module (New Content)' and click the 'Add' button to move it into the 'Deployed Modules' list, then click the 'Apply Changes' button (you should notice that the 'Last update' time stamp changes). This action only needs to be done once as Module Deployment data is saved into the Alfresco Repository.

Now log back into Alfresco Share and you should see that the content from the new Web Script is displayed above the title bar: