Modeling Best Practices
Now that you know the building blocks of a content model, it makes sense to consider some best practices. Here are the top ten:
- Don't change Alfresco's out of the box content model. If you can possibly avoid it, do not change Alfresco's out of the box content model. Instead, extend it with your own custom content model. If requirements call for several different types of content to be stored in the repository, create a content type for each one that extends from
cm:contentor from an enterprise-wide root content type. - Consider implementing an enterprise-wide root type. Although the need for a common ancestor type is lessened through the use of aspects, it still might be a good idea to define an enterprise-wide root content type such as
sc:docfrom which all other content types in the repository inherit, if for no other reason, than it gives content managers a "catch-all" type to use when no other type will do. - Be conservative early on by adding only what you know you need. A corollary to that is to be prepared to blow away the repository multiple times, until the content model stabilizes. Once you get content in the repository (that implements the types in your model), making model additions is easy, but subtractions aren't. Alfresco will complain about "integrity errors" and may make content inaccessible when the content's type or properties don't match the content model definition. When this happens to you (and it will happen), you can choose one of these options:
- Leave the old model in place
- Attempt to export the content, modify the exported data (see "ACP Files" in the Appendix), and re-import
- Drop the Alfresco tables, clear the data directory, and start fresh
As long as everyone in the team is aware of this, option three is not a big deal in development. But make sure expectations are set appropriately and have a plan for handling model changes once you get to production. This might be an area where Alfresco will improve in future releases, but for now it is something you have to watch out for.
- Avoid unnecessary content model depth. There don't seem to be any Alfresco Content Modeling Commandments that say, "Thou shall not exceed X levels of depth in thine content model, lest thou suffer the wrath of poor performance". But it seems logical that degradation would occur at some point. If your model has several levels of depth beyond
cm:content, you should at least do a proof-of-concept with a realistic amount of data, software, and hardware to make sure you aren't creating a problem for yourself that might be very difficult to reverse down the road. - Take advantage of aspects. In addition to the potential performance and overhead savings through the use of aspects, aspects promote reuse across the model, the business logic, and the presentation layer. When working on your model, you may find that two or more content types have properties in common such as
sc:webableandsc:clientRelated. Ask yourself if those properties are being used to describe some higher-level characteristic common across the types that might be modeled better as an aspect. - It may make sense to define types that have no properties or associations. You may find yourself defining a type that gets everything it needs through either inheritance from a parent type or from an aspect (or both). In the SomeCo model
sc:marketingDocis the only type with a property. You might ask yourself if the empty type is really necessary. It should at least be considered. It might be worth it, just to distinguish the content from other types of content for search purposes, for example. Or, while you might not have any specialized properties or associations for the content type, you could have specialized behavior that's only applicable to instances of the content type. - Remember that folders are types to. Like everything else in the repository, folders are instances of types, which means they can be extended. Content that "contains" other content is common. In the earlier expense report example, one way to keep track of the expenses associated with an expense report would be to model the expense report as a sub-type of
cm:folder. - Don't be afraid to have more than one content model XML file. When it is time to implement your model, keep this in mind: It might make sense to segment your models into multiple namespaces and multiple XML files. Names should be descriptive. Don't deploy a model file called
customModel.xmlormyModel.xml. - Implement a Java interface that corresponds to each custom content model you define. Within each content model Java class, define constants that correspond to model namespaces, type names, property names, aspect names, and so on. You'll find yourself referring to the qualified name (
Qname, for short) of types, properties, and aspects quite often; so it helps to have constants defined in an intuitive way. The constants should beQNameobjects except in cases where the Web Services API needs to leverage them. The Web Services API doesn't have theQNameclass, so there will need to be a string representation of the names as well in that case. - Use the source! The out of the box content model is a great example of what's possible. The
forumModelandrecordsModelhave some particularly useful examples. In the next section you'll learn where the model files live and what's in each. So you'll know where to look later when you say to yourself, "Surely, the folks at Alfresco have done this before".
This last point is important enough to spend a little more time on. The next section discusses the out of the box models in additional detail.
Out of the Box Models
The Alfresco source code is an indispensable reference tool that you should always have ready along with the documentation, wiki, forums, and Jira. With that said, if you are following along with this chapter but have not yet downloaded the source, you are in luck. The out of the box content model files are written in XML and get deployed with the web client. They can be found in the alfresco.war file in |WEB-INF|classes|alfresco|model. The following table describes several of the model files that can be found in the directory:
The table lists the most often referenced models. Alfresco also includes two WCM-related model files, the JCR model and the web client application model, which may also be worth looking at, depending on what you are trying to do with your model.
In addition to the model files, the modelSchema.xsd file can be a good reference. As the name suggests, it defines the XML vocabulary Alfresco content model XML files must adhere to.