Help

Auto-Readme Extension Example

cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 

Auto-Readme Extension Example

ddraper
Intermediate II
0 8 6,263
‎2 Sep 2011 3:29 PM

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:



  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
0 Kudos
8 Comments
Alfresco Content Services Blog

Ask for and offer help to other Alfresco Content Services Users and members of the Alfresco team.

Related links:

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.