Auto-Readme Extension Example

Showing results for 
Search instead for 
Did you mean: 

Auto-Readme Extension Example

Intermediate II
0 8 5,494


In my earlier blogs describing the new extensibility features my samples have not been particularly practical. Earlier this week I was asked how to extend the Document Library for a site to automatically display the content of any 'readme' files in the current folder. This blog will take you through how I implemented it. This post is not intended to explain the extensibility features but simply to show how they can be applied to achieve a more practical result. These features are currently available in the latest Alfresco Community source and will be in Alfresco Enterprise 4.0.


The extension that we're going to create will automatically display the contents of the first file called 'readme.txt' found in the currently selected folder in a site Document Library.

The JavaScript widgets that back the Document Library are probably the most complex in the in Alfresco Share client source code. Making anything but the simplest of changes to it is always going to require a reasonable understanding of how it works.  This means that you're need a good understanding of JavaScript and a reasonable about of YUI knowledge (or at least have a browser handy with access to the YUI documentation).

The standard Document Library (that you'll find on a regular site) is made up of the following Components: filter, tree, tags, toolbar and document list. If you want to change the behaviour of these widgets then you'll to take the following approach:

  1. Create a new JavaScript object that extends the JavaScript widget and store it in a .js file.

  2. Override the WebScript that backs the Component and ensure that the *.head.ftl loads your library and that the .html.ftl instantiates your widget.

This approach is not ideal because it requires that you override (rather than extend) a WebScript - however, we are looking at solutions to make this easier. Also, it's important to note that there are other options for specifically extending the Document Library that haven't been blogged about..... yet!

Fortunately this task is possible with the extensibility functions at our disposal because it only requires that we insert something between the toolbar and document list widgets. Using SurfBug we can identify that the Document List is rendered by the Component 'template.documentlist.documentlibrary' and it's Sub-Component 'default' (which was generated from legacy configuration).

We can insert some new content by defining a new Sub-Component in an extension module. Our Sub-Component needs to be backed by a Web Script which will render some new HTML to display the contents of a 'readme.txt' file if one exists. If you've used the Document Library you will have noticed that changing the path does not reload the entire page and inspection of the code reveals that AJAX requests to refresh the Document List are made on receipt of a 'filterChanged' event. This means that we will need to create our own JavaScript widget to listen for those events and respond accordingly.

The full list of files we'll need are as follows:

  • A configuration file defining a module that adds a new Sub-Component ('doclib-extension.xml')

  • A descriptor file for a new WebScript that will display 'readme.txt' content ('auto-readme.get.desc.xml')

  • A new JavaScript file defining our widget that will listen for the 'filterChanged' event ('auto-readme.js')

  • A new CSS file with the styling for our Sub-Component ('auto-readme.css')

  • A  WebScript .head.ftl file that will ensure that our JavaScript and CSS imports gets added to the HTML <head> element ('auto-readme.get.head.ftl')

  • A WebScript .html.ftl file that will define the HTML for displaying the 'readme.txt' content and instantiate our JavaScript widget ('auto-readme.get.html.ftl')

The files will need to go in the following locations in a JAR file:

  • /alfresco/site-data/extensions/doclib-extension.xml

  • /webscripts/auto-readme.get.desc.xml

  • /webscripts/auto-readme.get.head.ftl

  • /webscripts/auto-readme.get.html.ftl

  • /META-INF/doclib/extensions/auto-readme.css

  • /META-INF/doclib/extensions/auto-readme.js

(Note: the JavaScript and CSS files can live anywhere under the META-INF... any resources that are not picked up by the Spring Surf configuration or WebScript classloader code need to be placed in the META-INF path in order to be loadable).

Once you've created your JAR, copied it to 'webappsshareWEB-INFlib', restarted Alfresco Share and deployed the module you should be able to see results like those shown below:

Screenshot Showing Readme Contents

Screenshot Of Path With No Readme File
Active Member
Hi David,

Thanks a lot for your tutorial/example!
After I deployed the JAR file, the extension still not worked correctly.

In your file auto-readme.get.head.ftl I corrected the path for including the .css and .js file into 'extensions' instead of 'extension'.
After the modification your example worked fine!!

Again thanks a lot!,

Active Member
The vital link to the code is broken

Gives an error:

404 — File not found.
Active Member
Further, gives a WordPress Error:

This site has been archived or suspended.
Intermediate II
@Alex - the individual developer blogs were consolidated into a single Alfresco developer blog and it looks like that file has been lost and I don't appear to have a copy myself anymore Smiley Sad

I've removed the link from the page to avoid confusion - I appreciate that this isn't the solution you were looking for. Sorry.
Active Member
Thanks Dave. Yes, it would be nice if the code is reproduced, perhaps one day when you have time.

In general I've found your series very useful as a way of gradually learning about how to customize Alfresco Share. I'm sure it will be useful for others too, if each post clearly outlines the code (like it does in most cases) and includes the code where it's too long.
Active Member
Hey Dave.

Would you mind to try to take the time to rewrite this example?

It seems to be really useful to be able to reproduce your idea.

Thank you.
Intermediate II
@Douglas - as you can probably imagine we're all a bit busy working on 5.0 at the moment, but maybe I can take a look at this once it's been released. However, realistically if I was going to re-implement this extension again I'd be doing it against the Aikau based version of the Document Library. Also, I'm  going to have quite a lot of blog posts/samples/docs to write after 5.0 is released so this probably won't be high on my priority list - just thought I should set some realistic expectations on me getting this done any time soon! Smiley Happy
Active Member
Yeah... that's what I thought... but don't worry

Thank you