Tag: customization

5 rules you must follow on every Alfresco project

I know that people are often thrown into an Alfresco project having never worked with it before. And I know that the platform is broad and the learning curve is steep. But there are some rules you simply have to follow when you make customizations or you could be creating a costly mess.

The single most important one is to use the extension mechanism. Let me convince you why it’s so important, then I’ll list the rest of the top five rules you must follow when customizing Alfresco.

All-too-often, people jump right in to hacking the files that are part of the distributed WARs. I see examples of it in the forums and other community channels and I see it in client projects. Not every once-in-a-while. All. Of. The. Time.

If you’ve stumbled on to this blog post because you are embarking on your first Alfresco project, let this be the one thing you take to heart: The extension mechanism is not optional. You must use it. If you ignore this advice and begin making changes to the files shipped with Alfresco you are entering a world of pain.

The extension points in Alfresco allow you to change just about every aspect of Alfresco Share and the underlying repository without touching a single file shipped with the product. And you can do so in a way that can be repeated as you move from environment to environment or when you need to re-apply your customizations after an upgrade.

“But I am too busy,” you say. “This needs to be done yesterday!”, you say. “I know JavaScript. I’m just going to make some tweaks to these components and that’s it. What’s the big deal?”

Has your Saturday Morning Self ever been really angry at things your Friday Night Self did without giving much consideration to the consequences? That’s what you’re doing when you start making changes to those files directly. Yes, it works, but you’ll be sorry eventually.

As soon as you change one of those files you’ve made it difficult or impossible to reliably set up the same software given a clean WAR. This makes it hard to:

  • Migrate your code, because it is hard to tell what’s changed across the many nooks and crannies of the Alfresco and Share WARs.
  • Determine whether problems you are seeing are Alfresco bugs or your bugs, because you can’t easily remove your customizations to get back to a vanilla distribution.
  • Perform upgrades, because you can’t simply drop in the new WARs and re-apply your customizations.

People ask for best practices around customizing Alfresco. Using the extension mechanism isn’t a “best practice”–it’s a rule. It’s like saying “Don’t cross the foul line” is a “best practice” when bowling. It’s not a best practice, it’s a rule.

So, to repeat, the first rule that you have to abide by is:

  1. Use the extension mechanism. Don’t touch a single file that was shipped inside alfresco.war or share.war. If you think you need to make a customization that requires you to do that I can almost guarantee you are doing it wrong. The official docs explain how to develop extensions.

Rounding out the top five:

  1. Get your own content model. Don’t add to Alfresco’s out-of-the-box content model XML or the examples that ship with the product. And don’t just copy-and-paste other models you find in tutorials. Those are just examples, people!
  2. Get your own namespace. Stay out of Alfresco’s namespace altogether. Don’t put your own web scripts in the existing Alfresco web script package structure. Don’t put your Java classes in Alfresco’s package structure. It’s called a “namespace”. It’s for your name and it keeps your stuff separate from everyone else’s.
  3. Package your customizations as an AMP. Change the structure of the AMP if you want–the tool allows that–but use an AMP. Seriously, I know there are problems with AMPs, but this is what we’re all using these days in the Alfresco world. Ideally you’ll have one for your “repo” tier changes and one for your “share” tier changes. An AMP gives you a nice little bundle you can hand to an Alfresco administrator and simply say, “Apply this AMP” and they’ll know exactly what to do with it.
  4. Create a repeatable build for your project. I don’t care what you use to do this, just use something, anything, to automate your build. If a blindfolded monkey can’t produce a working AMP from your source code you’re not done setting up your project yet. It’s frustrating that this has to be called out, because it should be as natural to a developer as breathing, but, alas, it does.

The Alfresco Maven SDK can really help you with all of these. If you use it to bootstrap your project, and then only make changes to the files in your project, you’re there. If you need help getting started with the Alfresco Maven SDK, read this.

These are the rules. They are non-negotiable. The rest of your code can be on the front page of The Daily WTF but if you stick to these rules at a minimum, you, your team, and everyone that comes after you will lead a much less stressful existence.

You might also be interested in my presentation, “What Every Developer Should Know About Alfresco“. And take a look at the lightning talk Peter Monks gave at last year’s Alfresco Summit which covers advice for building Alfresco modules.

 

List of Alfresco Dashlet Challenge 2011 Entries

The Alfresco Dashlet Challenge contest has been over for quite a while and our winner, Florian Maul, has received his iPad and has already racked up some impressive Fruit Ninja scores, but I’m just now getting around to posting the entire list of entries. I’ve put the list on the Alfresco wiki.

Please do take a look at these projects and try them in your own installations. In many cases, it’s a single JAR you drop in, then restart and you’re done. If you find problems, don’t hesitate to log issues or maybe even crack open your editor, fix it, and contribute it back to the author.

I should take this opportunity to mention a little project we’ve got brewing. If you’ve heard any of my “State of the Community” talks you may already know about Alfresco Add-Ons. It’s a site we’re building that will do a better job of helping you find and rate add-ons the community is creating for the Alfresco platform. An Add-On might be a dashlet, like the Dashlet Challenge entries, or it might be an integration, or an API, or just about anything else that works with Alfresco.

Add-Ons isn’t meant to be a project hosting site. There are already a lot of those available. Instead, think of it as a directory or index with some social features to help the cream rise to the top. This will give everyone (Community & Enterprise users) a one-stop shop for add-ons and extensions.

We’re hoping to have a minimum viable product ready by DevCon. If it gets done and enough people want to see it, we’ll have an ad hoc session so we can look at it together. We’d obviously like to get feedback from the community for the next sprint.

Custom Data Lists in Alfresco Share Community 3.3

One of the new features of Alfresco 3.3 Community is Data Lists. The ability to create an arbitrary list within a team collaboration site is a feature so loved by SharePoint users, it is often cited as one of the things holding back a migration to Alfresco. I agree that it’s a useful feature and I’m glad to see it making its way into Alfresco Share. Let’s take a look at the new feature, then we’ll lift up the hood to see how it works so you can implement your own custom data lists.

Quick Review of Data Lists in Alfresco Share

First, take a look at this screencast. It shows the new Data List feature in action as well as the high-level steps needed to create your own custom Data Lists.

As you can see, Data Lists let you keep track of team information that lends itself to being managed by classic web form interactions and displayed in sortable columns. You can probably think of a lot of examples of things your team needs to track that don’t make sense in a blog or a document library or maybe need a little more structure than the wiki. The screencast showed To Do’s and Issues but it could really be anything.

In the Community 3.3 releases, Alfresco Share includes To Do Lists. It sounds like more Data List examples are coming in the 3.3g release. But if you want to add your own custom data list type, it’s really easy, especially if you’re familiar with Alfresco content models (tutorial). However, right now, this still requires XML editing. SharePoint allows lists to be defined on-the-fly, so while Alfresco’s roadmap does have this as something to address in the future, right now this is still a gap between the two products.

If you are interested in just the end-user functionality of Data Lists in Alfresco Share, this is where you should bail. If you want details on what’s going on behind the scenes, keep reading…

How Data Lists are Implemented

Data Lists are persisted as nodes in the repository. One node represents the list itself–it contains child nodes for each item in the list. The data values for each list item are stored as metadata on the node–sometimes we call these “content-less objects” because there is no file content associated with them. The nodes live in the DM repository just like data from the other tools in your Share site.

If you want to see this for yourself, go into the Explorer Client. In the Sites folder, there is a folder for Share site and within that, a folder for each site tool. Data List nodes reside in the one called dataLists. In the back of your mind you should be thinking that this means items in a Data List can trigger rules and be routed through workflows just like any other node. In fact, any API call that can work with a node can work with an entry in a Data List, including CMIS. (Shameless plug: “Heck, you could even create Data Lists with Python using cmislib!”)

You know from working with data models that each Alfresco data model has an XML file that describes it. If you go look at the out-of-the-box model directory you’ll see a new content model XML file called datalistModel.xml. If you take a look at that file, you’ll see that the node that represents the container of list items is an instance of dl:dataList which inherits from cm:folder.

The nodes that represent each item on the data list are instances of specific data list types. So, for example, the out-of-the-box To Do List has items that are of type dl:todoList. In my Issues example, Issue items are instances of scidl:issuesList. All data list item types must inherit from dl:dataListItem. For one thing, that’s how the Share user interface knows what to offer as an available data list type.

The form that’s displayed when you create and edit new Data List items is configured through the Alfresco Form Service. In my example I didn’t do anything fancy with the form, but you’ve got the full power of the new Alfresco Form Service behind you so you’re not limited to simply listing one field after another.

So, creating your own custom Data List types involves two steps:

  1. Define and deploy a custom content model for your new Data List type, making sure it inherits from dl:dataListItem.
  2. Configure the Alfresco Form Service in the Alfresco Share application to display the metadata from the custom Data List in the create and edit forms as well as in the browse grid.

In my example, I used an AMP to deploy the content model to the repository tier (my Alfresco WAR) and a JAR to deploy the form service configuration to the presentation tier (the Share WAR).

If you want to try this example in your own environment, you can download the Eclipse project here. It includes an Ant build file, the content model, and the form configuration. Note that I deployed the Forms Development Kit to both the Alfresco and Share WARs prior to deploying my Data List form configuration. The example assumes you’ve done the same. If you don’t want to fool with the FDK, that’s cool, it’s not required for data lists. You may want to look at the Forms Development Guide for tips.