As discussed in Chapter 5, a content model defines content types, aspects, and constraints. It is defined in an XML file that declares a namespace and all its members. These members belong to the namespace and an associated prefix. For example, the prefix cm refers to the formal namespace www.alfresco.org/model/content/1.0. You can find a list of namespaces and prefixes at the following wiki page: http://wiki.alfresco.com/wiki/Alfresco_Namespaces

A content type has metadata on it, which comprises properties and associations. Properties have names and values (either single or multi-value). Associations define relationships to other content nodes in the repository. Child associations define associations to objects that are considered part of the parent object. When the parent object is deleted, so are the child-associated objects.

Aspects are similar to content types in that they are containers of properties and associations. Aspects are implemented using the Aspect-Oriented Programming (AOP) framework within Spring. Aspects let you define metadata and behavior that cuts across one or more nodes in the repository. You can apply aspects at any time as you see fit. Aspects can be applied arbitrarily to content types as well as content instances.

Both content types and aspects feature inheritance. When a content type or aspect inherits from a parent, it incorporates all the parent's properties, associations, and aspects. If a content type has an aspect applied, the inheriting content type will also have the aspect applied.

A content model can also define one or more constraints. Constraints allow you to ensure the validity of your content ahead of persisting it (for example, when the object is saved). For instance, you may specify a regular expression that must be evaluated against a property to ensure that a property's value is in a valid format.

Content models are defined in an XML file. You bootstrap the XML file into the Alfresco repository using a Spring bean, which is defined in its own XML file (see Figure 13-2). You can define content types, aspects, and constraints as part of a content model using these two XML files that are placed into <installLocation> omcatsharedclassesalfrescoextension.

Figure 13.2. FIGURE 13-2

When Alfresco starts up, it finds the sample-model-context.xml file that declares the Spring bean responsible for bootstrapping the model into the repository model registry. This may appear as follows:

<bean id="extension.dictionaryBootstrap" parent="dictionaryModelBootstrap"
depends-on="dictionaryBootstrap">
<property name="models">
<list>
<value>alfresco/extension/sample-model.xml</value>
</list>
</property>
</bean>

That's all there is to it. All the things described inside the sample-model.xml file will be available to the repository and accessible to your end users from any of the Alfresco service interfaces.

One of the most powerful features of the Alfresco repository is the ability to inject behavior into your content. You may want to enforce certain policies on your content or have your own custom business logic execute when a content object is accessed, modified, or saved.

Aspects make this possible. They let you describe additional metadata, such as properties and associations. They also let you override and inject your own handlers for events that occur to the content instance that has the aspect applied. Using aspects, you can inject your own business logic as method handlers for events that are raised, such as when a content property is modified.

You can write your own business logic using JavaScript files or Java beans. You then need to register these files or beans with your aspect in the Alfresco repository. The basic registration pattern is shown in Figure 13-3.

Figure 13.3. FIGURE 13-3

You can declare the aspect available to the system using a Spring bean that might be defined like this:

<bean id="extension.sampleaspect" class="org.alfresco.sample.SampleAspect"
      init-method="init">
  <property name="policyComponent">
    <ref bean="policyComponent" />
  </property>
  <property name="serviceRegistry">
    <ref bean="ServiceRegistry"/>
  </property>
</bean>

When the aspect code's init method is called, it registers itself with the Alfresco repository using the same namespace as defined in the content model. That way, Alfresco knows how to invoke the aspect's interceptors.

Here is a sample aspect that intercepts the onUpdateProperties event and injects its own method to log the event to the Java console or log file. The aspect identifier is {http://www.alfresco.org/module/sample/1.0}sample, the same identifier used in the content model to define properties and metadata.

public class SampleAspect extends AbstractPolicyServiceBean
  implements NodeServicePolicies.OnUpdatePropertiesPolicy
{
  public void init()

{
    this.policyComponent.bindClassBehaviour(
      QName.createQName(NamespaceService.ALFRESCO_URI, "onUpdateProperties"),
      QName.createQName("http://www.alfresco.org/model/sample/1.0", "sample"),
      new JavaBehaviour(this, "onUpdateProperties",
      NotificationFrequency.TRANSACTION_COMMIT));
  }

  public void onUpdateProperties(NodeRef nodeRef, Map<QName, Serializable> before,
    Map<QName, Serializable> after)
  {
    System.out.println("onUpdateProperties heard for " + nodeRef.toString());
    System.out.println("before: " + before + ", after: " + after);
  }
}

Several aspects are provided out of the box for managing things such as content lifecycle, locking, and auditing.

You looked at the Alfresco workflow engine in Chapter 7. Alfresco provides the jBPM workflow engine out of the box, which empowers solution developers to model business processes around their content. Workflow provides you with the ability to design lifecycle management around your content.

A process definition is written in jPDL. A separate Spring bean is then responsible for bootstrapping the process definition into the Alfresco repository at startup. Along with the process definition, the Spring bean can also optionally bootstrap a workflow content model as well as any I18N resource bundles (properties files) in support of localization.

This process is illustrated in Figure 13-4 for a sample process definition that defines a content lifecycle.

The lifecycle-workflow-context.xml file defines the Spring bean that bootstraps the three other files into the repository:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/
dtd/spring-beans.dtd'>

<beans>
  <bean id="lifecycle.workflowBootstrap" parent="workflowDeployer">
    <property name="workflowDefinitions">
      <list>
        <props>
          <prop key="engineId">jbpm</prop>
          <prop key="location">
            alfresco/extension/lifecycle_processdefinition.xml
          </prop>
          <prop key="mimetype">text/xml</prop>
          <prop key="redeploy">false</prop>
        </props>
      </list>
    </property>

<property name="models">
      <list>
        <value>alfresco/extension/lifecycleModel.xml</value>
      </list>
    </property>
    <property name="labels">
      <list>
        <value>alfresco/extension/lifecycle-messages</value>
      </list>
    </property>
  </bean>
</beans>

Code snippet lifecycle-workflow-context.xml

Figure 13.4. FIGURE 13-4

These files are available from the book's Web site in case you would like to try them in your own Alfresco repository.

Workflow models allow you to wrap forms and property sheets around your jBPM workflow processes. They inform the Alfresco repository how to map content contained within the in-flight processes to display elements for the end user. This includes mapping end-user input into process variables as well as mapping process variables back into display elements.

You can think of the raw process definition as a graph or a mathematical construct that links together different task nodes via transitions. The in-flight process transitions from node to node either automatically or based on external interaction from an end user. With Alfresco, this external interaction is usually facilitated through forms or workflow wizards.

The workflow content model informs these forms of how to render. It draws from the I18N resource bundles to provision text elements (like labels) that are meaningful for many languages and geographies.

How might you use this? Imagine a scenario where you may want to have multilingual support for your workflow tasks, such as forms automatically localized for Italian versus French. A workflow model makes this possible. It informs Alfresco how to retrieve and persist information from the underlying in-flight process while providing an Italian-localized interface for the Italian users and a French-localized interface for the French users.

Actions are Spring beans that act upon a content node. You develop actions using Java and register them with the repository through a Spring configuration file. Actions provide the ideal place to put your common, highly reusable business logic. You can then call these actions from within the repository for any number of content objects.

Most of the cool and interesting things you can do with the Alfresco repository are actually implemented as actions. For example, you might wire in a rule behind a space that tells the space to automatically make copies of incoming content. The rule triggers an action.

Writing actions is a developer-level task. You essentially just have to implement one method that tells the action what to do. Your method is given the action parameters as well as the node upon which the action is being called. You could write a very simple copy action that might look something like this:

public void executeImpl(Action action, NodeRef node)
{
  if (this.nodeService.exists(node) == true)
  {
    // we take in two parameters
    NodeRef parent = (NodeRef) action.getParameterValue("destination_folder");
    String name = (String) action.getParameterValue("destination_name");

    // association type and associated content name
    QName assocType = (QName) ContentModel.ASSOC_CONTAINS;
    Qname assocName = QName.createQName(ContentModel.CONTENT_MODEL_1_0_URI, name);

    // Create a new copy of the node
    this.copyService.copyAndRename(node, parent, assocType, assocName, true);
  }
}

You register your Java bean via Spring configuration. It is then registered with the repository under a specified ID. For the example above, you might select the ID "my-copy-action."

If you have written other Java backing classes for Alfresco (such as aspects, transformers, or other actions), you could reuse this action from within those. You may also reuse it from within any server-side scripting files you may have. Here is an example of JavaScript that copies a document to the Company Home folder by using your custom action:

var myCopyAction = actions.create("my-copy-action");
myCopyAction.parameters["destination_folder"] = companyhome;
myCopyAction.parameters["destination_name"] = "Copy of " + document.name;
myCopyAction.execute(document);

In addition, you can invoke this action from the user interface directly if you so choose. You can configure Alfresco Explorer and Alfresco Share to participate in providing buttons to trigger actions directly. You will look at some extensions to Alfresco Explorer and Alfresco Share in the coming chapters.

The Alfresco repository features many additional extension points that are beyond the scope of this book.

You can define custom transformers that are responsible for converting a document of a source file type to a destination file type. For example, you might plug in a transformer that converts an MPEG video file to an audio output stream. You could then push both of these files to a Web server for delivery.

You can define custom metadata extractors responsible for interrogating the content and pulling out metadata fields. For example, you can write a metadata extractor that extracts values from a custom file format and places it onto Alfresco metadata properties. You can then search on these properties or fire off custom business logic.

You can also define custom template and scripting variables that you can provision to developers who wish to extend the Alfresco repository using server-side JavaScript or FreeMarker.

All these extension points and more can be achieved using the very same pattern shown here. An implementation Spring bean is developed and then declared or bootstrapped through configuration.

You typically access Alfresco Explorer using the following URL:

http://localhost:8080/alfresco

You can then log in using your credentials (see Figure 13-5). The default administrator account has a user name of admin and a password of admin.

Figure 13.5. FIGURE 13-5

Once inside Alfresco Explorer, you will see a simple dashboard that serves as a landing page for users (see Figure 13-6). Each user can customize this dashboard to their liking by arranging the out-of-the-box dashlets or custom dashlets that you build using Web scripts.

Figure 13.6. FIGURE 13-6

Clicking on Company Home takes you to the root of the content repository. Here, you will see a navigable view of nodes in the repository.

Nodes consist of spaces and content items:

Spaces and content items are implemented using Alfresco's content model facilities. Therefore, you can extend their definitions and add in your own business logic. You may wish to add new metadata, bind in content rules, or wire in new behaviors using aspects.

Alfresco Explorer provides default icons for these object types, but you can plug in as many of your own as you like. Figure 13-7 shows an example of a default space and a content item with the extension ftl.

Figure 13.7. FIGURE 13-7

Alfresco Explorer lets you define the specific actions that users will have available to them when they interact with nodes in the repository. These actions appear as clickable icons next to either the space or the content item, as shown in Figure 13-7, or they can appear along the menu at the top of the page. You can associate different actions to different types of objects. You can also have role-based actions where actions are only available to certain users.

For any given space with Alfresco Explorer, you will have several actions available to you by default for creating new content and new spaces. These actions are available along the top of the page, as shown in Figure 13-8.

Figure 13.8. FIGURE 13-8

From this menu, you can upload new content items or perform actions against the current space. You can also create new content items or spaces inside of this space from scratch. The Create Space option brings up the Create Space dialog box (see Figure 13-9). A form is presented for setting the properties of your new space. You can define forms within Alfresco Explorer for all of your custom content types for both spaces and content items. You have complete control over the end-user content contribution experience.

If you create new spaces, they will appear alongside the default spaces shown in Figure 13-6. If you want to see what is inside a space, just click on its icon or its name. This will navigate you into that space. Once there, you can click on the View Details icon to bring up the Details page for your space. Figure 13-10 shows the Details page for the Data Dictionary space.

Figure 13.9. FIGURE 13-9

Figure 13.10. FIGURE 13-10

You can view the properties for any node in the repository, whether it is a space or a content item. On the right side of the page is a list of actions you can perform against this node.

Alfresco Explorer provides many more features and extension points. You will look at some of these as you explore and build out the sample application.

Alfresco Explorer provides you with an interface for assigning permissions to nodes in the repository. Permissions themselves are actually a repository-level feature; Alfresco Explorer simply provides an elegant interface for assigning and working with permissions.

You can modify permissions for a space by selecting Manage Space Users in the More Actions menu (see Figure 13-11).

Figure 13.11. FIGURE 13-11

By clicking on Invite, you begin the process of inviting users or groups of users into the space (see Figure 13-12). You invite users or groups to participate in the space in one or more roles.

Roles are groupings of permissions. When you assign a user or a group to a role against a node, you grant them a set of permissions against that node. Alfresco ships with a number of predefined roles. These roles are described in Chapter 6.

Figure 13.12. FIGURE 13-12

Alfresco Explorer provides a convenient way to define repository rules wired into your content spaces. A rule is a bit of business logic configured to trigger when something happens to or with content inside of the space. There are three types of triggers:

You can define rules directly within the user interface. If you navigate into a space using Alfresco Explorer, you will see several options listed under More Actions (see Figure 13-11).

Clicking on Manage Content Rules brings up the Content Rules page, which lists all the rules currently wired to execute behind that space. As shown in Figure 13-13, three rules are wired into the space with the name My Sample Space. These rules will automatically execute when users interact with this space. For example, when a user drops a Word document into this space, the document will automatically be converted to PDF.

Figure 13.13. FIGURE 13-13

Let's look at how to set up a new rule. Clicking Create Rule at the top of the Content Rules page lets you create a brand new rule. A preliminary page appears that lets you define the conditions by which your new rule will be fired (see Figure 13-14).

Figure 13.14. FIGURE 13-14

You can select from many different kinds of conditions, including the following:

Many more conditions are available. In addition, Alfresco Explorer allows you to plug in your own conditions. Once you have specified a condition, click Next to advance to the next page, where you can define what actions should occur if the condition is satisfied (see Figure 13-15).

Figure 13.15. FIGURE 13-15

The actions shown in Figure 13-15 are repository actions. As mentioned previously, you can build your own or choose from the list of actions available out of the box. You can have the rule automatically apply aspects to your content, transform your content, fire off emails about your content, or move it to an entirely different space in the repository. You can have these rules run in the background or execute while the user waits.

Clicking Next takes you to the next step of the wizard, where you define which type of event will trigger the execution of the rule (see Figure 13-16).

Figure 13.16. FIGURE 13-16

You might want the rule to trigger when content is added to the folder (inbound) or when it is updated within the folder (update). Give your rule a name and description, and click Finish to save it.

That's all there is to it. You can be very descriptive with rules and the business logic that they invoke. A single rule can fire off many repository actions and can even execute server-side JavaScript. You are also free to define many different rules, each configured to trigger under slightly different conditions. Rules allow you to implement simple processes on the fly by moving content between spaces while triggering email notifications, metadata updates, and scriptable actions to modify the content-item lifecycle state.

Alfresco Explorer features many additional extension points that are beyond the scope of this chapter.

You can add new user interface actions, customize icons, plug in custom templates, and build new behaviors using server-side JavaScript. You will look at some of these in more detail in the chapters that follow.

Users typically access Alfresco Share using the following URL:

http://localhost:8080/share

This directs the browser to the Alfresco Share Web client.

Alfresco Share features an Alfresco authenticator that informs Surf how to authenticate and interact with the Alfresco repository.

On the Login page (see Figure 13-17), you can log in using the same authentication credentials as with the underlying repository and Alfresco Explorer (admin/admin).

Once logged in, the current user's dashboard displays (see Figure 13-18). This provides a single place to see all the content and activity touch points for the projects in which the user is involved.

The user dashboard contains a series of dashlets arranged onto the page according to a prescribed layout. Each user will have a slightly different preference as to which dashlets are most useful to them. They may also prefer different layouts. For this reason, Alfresco Share lets you configure your user's dashboard layout and preferred dashlets through the Customize Dashboard feature (located in the top-right corner of the dashboard).

Figure 13.17. FIGURE 13-17

Figure 13.18. FIGURE 13-18

Users can participate in public projects either by discovering content activities through their dashboard or by searching for sites explicitly. You search for sites by typing the name of the site in the search box on the top right of the page. You then click the search icon to start your search.

Sites may also be marked as private, in which case the user must be explicitly invited. Users can also create new sites using the Create Site Wizard (see Figure 13-19). You launch the Create Site Wizard by clicking on the Create Site link under the My Sites dashlet. The Create Site Wizard will pop up in a modal dialog.

Figure 13.19. FIGURE 13-19

The wizard creates a new project site preconfigured with a set of default pages that appear along the top of the page. Each page offers collaboration tools around the project. See Figure 13-20 for a sample of how a project might appear.

Figure 13.20. FIGURE 13-20

The default pages that appear along the top of the page are:

You can change these default pages, add new pages, or even define new types of project sites. The administrator of the site can set up the site dashboard page to offer unique project-specific functionality for the users of the site. A site administrator may, for example, wish to customize the site dashboard and remove some of the default pages or add in their own custom pages and dashlets.

Figure 13-21 shows an example of the Document Library page, one of the default project pages. It offers document thumbnails, a left-hand navigation tree, and in-context document preview.

The site administrator can also add members to the site. All site members take on roles; some may be contributors, others collaborators. When users interact with content in the site, these interactions are tracked as activities. At any point, you can view the list of recent activities for a given site. These are shown in the Site Activities dashlet on your site dashboard (see Figure 13-20).

Figure 13.21. FIGURE 13-21

Alfresco Share provides a user dashboard to which each user has full access and control. The user dashboard is the very first thing that users see when they log into Alfresco Share. It provides a quick view into all the user's touch points within the Alfresco Share content store.

A dashboard consists of dashlets plugged into the dashboard's layout. A dashlet is a miniature view or application that can be snapped into the dashboard. Users can configure the layout of their dashboard, which lets them place their dashlets in a variety of different places.

Figure 13-22 shows an example of a three-column layout with a few dashlets plugged into the columns. The left column has three dashlets assigned to it, whereas the middle and right columns only have a single dashlet each.

Figure 13.22. FIGURE 13-22

Alfresco Share allows users to customize their user dashboards by simply clicking on the Configure Dashboard button at the top of their user dashboard page. They can then pick from alternative layouts using the Change Layout button. Alfresco Share comes pre-stocked with a few common and useful layouts. You can also add your own; however, that is beyond the scope of this discussion.

At the bottom of the page, users can discover new dashlets. They can drag and drop them into their dashboard. If you add new custom dashlets to the system, they will appear here for users to select and place onto their user dashboard.

Alfresco Share allows you to set up sites (or workspaces) for collaborative projects. Each site also has a dashboard. Site dashboards behave very similarly to user dashboards, except that site administrators are the ones to configure them, rather than the end user. Site administrators can set site dashboard layout and pre-configure which dashlets are available to their site users.

Dashlets are Web scripts that belong to a specific family. Dashlets that you intend to make available for placement onto the user dashboard should be placed into the user-dashlet family. Dashlets that you intend to make available for placement onto a site dashboard should be placed into the site-dashlet family. As discussed in the previous section, this can be accomplished by simply dragging the dashlets from the bottom of the page onto the dashboard.

Dashlet Web scripts must provide GET handlers. This means you should define a scriptable controller for the HTTP GET method, and your template view should output to the HTML format.

If your dashlet is added to a user dashboard or a site dashboard, Alfresco Share will render it in the context of the entire page. You will look at dashlets in more detail in the next chapter.