Improve the Wiki with Share Extras

[alfresco]

Written by Richard Esplin‌

Background

The wiki in Alfresco Share is one of the most used collaboration features in Alfresco. Yet people who have experience with other wiki tools might notice that the wiki within Share lacks some convenient features. Thankfully the team behind the Share Extras project implemented some of those features and made them available to add to your Alfresco deployment. The Wiki Rich Content add-on is one of the most widely deployed Alfresco add-ons.

Main Functionality

The most frequently used functionality in the add-on is the ability to add dynamic table of contents based on the headings in an article. After installation, each time a wiki page that contains multiple headings is saved a table of contents will be generated for that page. This is an essential capability for making long and complex pages navigable. All preformatted text gets highlighted as if it were snippets of code. By adding the class "datatable" to a table on a wiki page, it will be rendered as a YUI Datable with useful features such as resizable and sortable columns. The original author of the add-on, Will Abson (@wabson), thinks that the most under-appreciated feature in the add-on is the ability to embed a document preview into a wiki page, rather than just linking to it. This can help a page stay up-to-date or it can be used to include rich content. To embed a document preview, use the Document Link dialog and then editing the link to change the target to one of the options that start "Embedded". (Images are embeddable out-of-the-box.) Datalists can be embedded by adding a class with the datalist ID to a standard table and if you specify columns that match the names of properties used in the datalist, then only those columns will be displayed. The add-on also provides the ability to embed into a wiki page external videos from YouTube and Vimeo by using the link dialog and selecting one of the "Embedded" targets. I found that HTTPS links were not recognized for inclusion, but after removing the "S" the video preview was properly embedded. The option to "Embed the preview with no link" will remove from the page the text that would otherwise link to the video, otherwise it shows up just above the preview.

Compatibility, Installation, Configuration, and Removal

I tested the Add-on in both Enterprise Edition 4.0.2 and Community Edition 4.2.b. Everything worked great in both versions with the exception of document link previews. Due to changes to the wiki sanitization, the add-on will have to be updated for that feature to work in 4.2. As with other add-ons in the Share Extras project, installation is as simple as adding a JAR to your Alfresco classpath (see digression). The add-on requires no configuration; after installation each page you edit that has multiple headings will have a table of contents generated for it. The instructions mention needing to deploy the module, but that isn't necessary in versions of Alfresco newer that 4.0.2. However, each function in the add-on conveniently displays as a separate Share module, so it is easy to disable parts of the add-on by browsing to http://[server]:[port]/share/page/modules/deploy. I didn't notice any negative effect from removing modules like the table of contents, except that the enhanced content does not show up.

A Digression on Installation

There are lots of different ways to get your code into Alfresco. The most comprehensive documentation is currently a page in the wiki. The Wiki Rich Content add-on is distributed as a JAR file, and the instructions recommend that you put the JAR into tomcat/shared/lib. But that directory is not part of the standard classpath in Tomcat 6 which is shipped with Alfresco 4. That means you either need to add it to the classpath (best to add the jar to shared.loader in tomcat/conf/catalina.properties), or you need to use a different deployment mechanism. The recommended mechanism is to put the JAR into a custom AMP such that it is deployed into share/WEB-INF/lib, then use the apply_amps script to install it into the Share WAR. In future releases we may tweak the packaged tomcat install to add the shared library loader back to the classpath for convenience, but using it is not the recommended approach. To install on my demo system, I dropped it into tomcat/webapps/share/WEB-INF/lib and restarted Tomcat. I think this is the easiest approach for evaluation, but it is not recommended for production use because the add-on will be deleted on upgrade or redeployment of the WAR. I also don't recommend this approach because it makes it hard to differentiate between stock-Alfresco libraries and add-ons.

Customization

The add-on is relatively simple, as it is a grouping of discrete Share webscripts with some front-end CSS and JavaScript. Customizing the look of the elements provided by the add-on is a clean process: unzip the JAR, edit the relevant CSS files in jar/META-INF/extras/components/wiki, rezip the directory into a JAR, and install. Other customizations require a basic understanding of webscripts. The add-on only contains Share webscripts; it does not modify the repository.

Future

The engineering team has been discussing how best to incorporate the most widely used features of Wiki Rich Content into the standard Alfresco Share install. The CSS improvements were added to core Share in 4.2.c. It is likely that the Table of Contents functionality will be merged into core Share in a future release. Development has slowed on the add-on. There has been talk of exposing similar capabilities in the Share site blogging component, but no work has been done on that yet. Most of the current efforts have been on an experimental project to re-implement the entire wiki component using the core Document Library code. That effort has yielded some promising results. As with all Share Extras projects, your contributions are appreciated. The maintainers accept all sort of quality contributions, but patches attached to issues in the tracker are the easiest to work with.

Conclusion

The Wiki Rich Content add-on augments the default Share wiki with important features for making complex pages useful.