Customizing Alfresco Share: Five things to watch out for

Alfresco Share is a team-centric collaboration tool. It’s really cool and our clients have been reacting very positively to it. When customers see the AJAXalicious UI, a common reaction is to want to take the next 5 projects on their list and “do them on Share”.

In cases where the functional requirements closely resemble team collaboration, that can be a great choice. In others, it’s an abuse of the tool. Just like a lot of things in software and life, just because you can doesn’t mean you should. (Remind me to tell you the story about building a tennis court reservation system in Lotus Notes some time).

Anyway, let’s assume you’ve got a set of requirements that reasonably resembles team-based collaboration, but some of Share’s tools (wiki, blog, document library, calendar, and recently, bookmarks) don’t work exactly the way you need them to. I’m not talking about adding new, self-contained custom components. This is specifically about customizing the out-of-the-box Share components. With that in mind, here are five areas where even simple Share customization efforts could take longer than you might think.

Custom Metadata

In its current incarnation, if you have custom metadata you want to display when looking at document detail, that’s code you have to write. Alfresco’s Mike Hatfield said, via Twitter, that the 3.2 Forms Service will make this better, so that’s good. If your Share sites contain simple documents that use only out-of-the-box metadata, this won’t be an issue for you.

Custom Workflows

Currently, in Share, there are a couple of places where the jBPM workflow engine is used. First, when you invite someone to a site, that kicks off a workflow. Second, you can “assign” an advanced workflow to a document in the document library.

The first issue is that the workflow submission dialog includes only the two out-of-the-box, document-centric workflows, “Ad hoc” and “Review and Approve”. It won’t show any custom workflows you’ve deployed. The workflow modal is not inspecting the workflow UI configuration like the web client does, so even if you got your workflows to show up in that list, the form wouldn’t have the custom workflow metadata you need to launch your custom workflow properly.

When you log in to Share, you’ll see a “My Tasks” dashlet. This gives you hope that maybe that dashlet could manage tasks for any workflow. Unfortunately, it only works with the “invite user” workflow and the two document-centric, OOTB workflows.

Long story short, Share isn’t set up to work with custom workflows out-of-the-box. If you’ve got custom workflows that need to work in the Share context, you’ll need to write your own dialogs for launching the workflow and your own component for managing workflow tasks.

YUI Bubbling Events

Share makes heavy use of YUI Bubbling Events. This results in a great end-user experience–the Share components communicate with each other and refresh themselves via AJAX without page refreshes. But it does mean there’s a bit of a learning curve when following the same pattern to implement your customizations if your team has never worked with the bubbling library before. It can get kind of thick in places.

Incidentally, all of the YUI stuff is part of Share, not Surf, which is the framework used to build Share. If you’re building your own Surf app you’ll need to grab the YUI libraries (or any other libraries you want to use) yourself. It’s the same for the Flash pieces (multi-document upload, document preview). It keeps Surf light, but if you want to incorporate that kind of functionality into your Surf app, some assembly will be required.

Code Sprawl

In Share, every module has as least one JavaScript file. For example, the Document Library has six different JavaScript files weighing in at about 136KB. Sometimes what should be a simple change (adding a button, creating a new modal) requires changes to every one of those files. This combined with grokking the bubbling events translates into potentially lengthy development cycles for stuff that you wish would be quick.


The main CSS file for Share is in the themes directory. But changing that will only affect the global dashboard header and the site dashboard header. If you want to change the theme for everything in Share, including individual tools, you have to change each tool’s CSS file. Those CSS files live in the “modules” directory. It would be nice if it were easier to implement site-wide or global themes.

Adding your own Components/Tools

The impact of these issues are lessened somewhat if you are adding your own components or tools instead of customizing what’s already there. It’s easy to write your own dashlets that show up on the global dashboard or the site dashboard. And with a little work, you can write dashlets that talk to each other using YUI Bubbling Events, just like the OOTB dashlets. The area for improvement is in skinning, configuring, and extending the out-of-the-box tools.

Share Your Thoughts on Share

There’s no doubt that Share is a cool application for team-based collaboration. I didn’t expect it to be configurable to the Nth degree right away, and we may be pushing the limits of its intended use. I’m curious to hear from others who have been tweaking the app: Have you worked through these issues? Are there other examples of specific extension points Alfresco could address to make your lives easier?