Introduction
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.
Tutorial
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:
- Create a new JavaScript object that extends the JavaScript widget and store it in a .js file.
- Override the WebScript that backs the Component and ensure that the *.head.ftl loads your library and that the .html.ftl instantiates your widget.
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')
- /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
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:
8 Comments
