Tag: User Interface

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?

Alfresco User Interface: What are my options?

People often need to build a custom user interface on top of the Alfresco repository and I see a lot of people asking general questions about how to do it. There are lots of options to consider. Here are four options for creating a user interface on top of Alfresco, at a high level:

Option 1: Use your favorite programming language and/or framework to talk to Alfresco via REST or Web Services. PHP? Python? Java? Flex? Whatever, it’s up to you. The REST API is nice because if you can’t find a URL that does what you need it to out-of-the-box, you can always roll-your-own with the web script framework. This option offers the most flexibility and creative freedom, but of course you might end up building constructs or components that you may have gotten “for free” from a higher-level framework. Optaros‘ streamlined web client, DoCASU, built on Ext-JS, is one freely-available example of a custom UI on top of Alfresco but there are others.

Option 2: Use Alfresco’s Surf framework. Alfresco’s Surf framework is just that–it’s a framework. Don’t confuse it with Alfresco Share which is a team-centric collaboration client built on top of Surf. And, don’t assume that just because a piece of functionality is in Share it is available to you in the lower-level Surf framework. You may have to do some extra work to get some of the cool stuff in Share to work in your pure Surf app. Also realize that Surf is brand new and still maturing. You’ll be quickly disappointed if you hold it to the same standard as a more widely-used, well-established framework like Seam or Django. Surf is a good option for quick, Alfresco-centric solutions, especially if you think you might want to leverage Alfresco’s browser-based site assembly tool, Web Studio, at some point in the future. (See Do-it-yourself Alfresco Surf Code Camp).

Option 3: Customize the Alfresco “Explorer” web client. There are varying degrees to which you can customize the web client. On one end of the spectrum you’ve got Freemarker “presentation templates” followed closely by XML configuration. On the other end of the spectrum you’ve got more elaborate enhancements you can make using JavaServer Faces (JSF). Customizing the Alfresco Explorer web client should only be considered if you can keep your enhancements to an absolute minimum because:

  1. Alfresco is moving away from JSF in favor of Surf-based clients. The Explorer client will continue to be around, but I wouldn’t expect major efforts to be focused on that client going forward.
  2. JSF-based customizations of the web client can be time-consuming and potentially complex, particularly if you are new to JSF.
  3. For most solutions, you’ll get more customer satisfaction bang out of your coding buck by building a purpose-built, eye-catching, UI designed with your specific use cases in mind than you will by starting with the general-purpose web client and extending from there.

Option 4: Use a portal, community, or WCM platform. This includes PHP-based projects like Drupal (Drupal CMIS Screencast) or Joomla as well as Java-based projects like Liferay and JBoss Portal. This is a good option if you have requirements that match up well with the built-in (or easily added-on) capabilities of those platforms.

It’s worth talking about Java portal servers specifically. I think people are struggling a bit to find The Best Way to integrate Alfresco with a portal. Of course there probably is no single approach that will fit every situation but I think Alfresco (with help from the community) could do more to provide best practices.

Here are the options you have when integrating with a portal:

Portal Option 1: Configure Alfresco to be the replacement JSR-170 repository for the portal. This option seems like more trouble than it is worth. If all you need is what you can get out of JSR-170, you might as well use the already-integrated Jackrabbit repository that most open source portals ship with these days unless you have good reasons not to. I’m open to having my mind changed on this one, but it seems like if you want to use Alfresco and a portal, you’ve got bigger plans that are probably going to require custom portlets anyway.

Portal Option 2: Run Alfresco and the portal in the same JVM (post). This is NOT recommended if you need to scale beyond a small departmental solution and, really, I think with the de-coupling of the web script engine we should consider this one deprecated at this point.

Portal Option 3: Run the Alfresco web script engine and the portal in the same JVM. Like the previous option, this gives you the ability to write web scripts that are wrapped in a portlet but it cuts down on the size of the web app significantly and it frees up your portal to scale independently of the Alfresco repository tier. It’s a fast development cycle once you get it set up. But I haven’t seen great instructions for setting it up yet. Alfresco should document this on their wiki if they are going to support this pattern.

Portal Option 4: Write your own portlets that make services calls. This is the “cleanest” approach because it treats Alfresco like any other back-end you might want to integrate with from the portal. You write custom portlets and have them talk to Alfresco via REST or SOAP. You’ll have to decide how you want to handle authentication with Alfresco.

What about CMIS?

CMIS fits under the “Option 1: Use your favorite programming language” and “Portal Option 4: Write your own portlets” categories. You can make CMIS calls to Alfresco using both REST and SOAP from your own custom code, portlet or otherwise. The nice thing about CMIS is that you can use it to abstract the underlying repository so that (in theory) your front-end code will work with different CMIS-compliant back-ends. Just realize that CMIS isn’t a fully-ratified standard yet and although a CMIS implementation is in the Enterprise version of Alfresco, it isn’t clear to me whether or not you’d be supported if you had a problem. (The last response I saw on this specific question was a Peter Monks tweet saying, “I don’t think so”).

The CMIS standard should be approved by the end-of-the-year and if Alfresco’s past performance is an indicator of the future, they’ll be the first to market with a production-ready, fully-supported CMIS implementation based on the final spec.

Pick your poison

Those are the options as I see them. Each one has trade-offs. Some may become more or less attractive over time as languages, frameworks, and the state of the art evolve. Ultimately, you’re going to have to evaluate which one fits your situation the best. You may have a hard time making a decision, but you have to admit that having to choose from several options is a nice problem to have.