Looking at Alfresco Share 3.2 Community - Part 3 - Customizing forms

This blog will look at how to display custom types and aspects in Share in the edit metadata feature. The previous blog article showed how to associate content with predefined aspects and show them in the edit metadata form.

This example requires Alfresco 3.2 Labs (currently Preview).

Resources:
* Alfresco forms engine wiki page
* Alfresco forms engine examples wiki page

Also see my previous blog entries showing how forms are used in Alfresco Share 3.2

I will use the example project structure offered by Jeff Potts' great article - Extending the Alfresco Content model to extend the content model in Alfresco. For the share customization, I will base my project on the Share extension project example in my blog.

Creating the new Custom content type

For this example, I will create a custom content type and modify the edit metadata form shown in Alfresco Share. The content type I will create will center around a custom type called MarketingContent, with an additional Aspect called Brandable. This custom metadata will add the ability to identify the 'brand' to which the Marketing content should be associated, and will require a custom single-select drop down.

Step 1 - Setup the project to extend Alfresco with custom content

1. Download Jeff Potts' custom content example source
2. Import into Eclipse - assume you already downloaded the Alfresco SDK and imported SDK AlfrescoRemote
3. Fix project references as needed
4. Update build.properties for ant build (alfresco.sdk.remote.home and alfresco.web.root)

Step 2 - Modify project for new custom content model

Four files to modify:
* PROJECT_HOME/src/alfresco/extension/someco-model-content.xml
* PROJECT_HOME/src/alfresco/extension/scModel.xml
* PROJECT_HOME/src/alfresco/extension/web-client-config-custom.xml
* PROJECT_HOME/src/alfresco/extension/webclient.properties

someco-model-content.xml (renamed to 'orbitz-model-content.xml')

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

<beans>
<!-- Registration of new models -->
<bean id="extension.dictionaryBootstrap" parent="dictionaryModelBootstrap" depends-on="dictionaryBootstrap">
<property name="models">
<list>
   <value>alfresco/extension/orbModel.xml</value>
</list>
</property>
</bean>
</beans>

scModel.xml (renamed to 'orbModel.xml')

<?xml version="1.0" encoding="UTF-8"?>
<!-- Definition of new Model -->
<model name="orb:orbitzmodel" xmlns="http://www.alfresco.org/model/dictionary/1.0">

<!-- Optional meta-data about the model -->
<description>Orbitz Marketing Model</description>
<author>Ed Wentworth</author>
<version>1.0</version>

<!-- Imports are required to allow references to definitions in other models -->
<imports>
  <!-- Import Alfresco Dictionary Definitions -->
  <import uri="http://www.alfresco.org/model/dictionary/1.0" prefix="d" />
  <!-- Import Alfresco Content Domain Model Definitions -->
  <import uri="http://www.alfresco.org/model/content/1.0" prefix="cm" />
</imports>

<!-- Introduction of new namespaces defined by this model -->
<namespaces>
  <namespace uri="http://www.orbitz.com/model/content/1.0" prefix="orb" />
</namespaces>
<constraints>
  <constraint name="orb:brands" type="LIST">
      <parameter name="allowedValues">
          <list>
              <value>Orbitz</value>
              <value>CheapTickets</value>
              <value>eBookers</value>
          </list>
      </parameter>
      <parameter name="caseSensitive"><value>true</value></parameter>
  </constraint>
</constraints>

<types>
  <!-- Enterprise-wide generic document type -->
  <type name="orb:doc">
      <title>Orbitz Document</title>
      <parent>cm:content</parent>
      <mandatory-aspects>
        <aspect>cm:generalclassifiable</aspect>
      </mandatory-aspects>
  </type>

  <type name="orb:marketing_content">
      <title>Orbitz Marketing Content</title>
      <parent>orb:doc</parent>
      <properties>
          <property name="orb:effective_from">
              <type>d:date</type>
          </property>
          <property name="orb:effective_to">
              <type>d:date</type>
          </property>
      </properties>
  </type>
</types>

<aspects>
  <aspect name="orb:brandable">
      <title>Orbitz Brandable</title>
      <properties>
          <property name="orb:brand">
              <type>d:text</type>
              <mandatory>true</mandatory>
              <constraints>
                  <constraint ref="orb:brands"/>
              </constraints>
          </property>          
      </properties>
  </aspect>

</aspects>
</model>

web-client-config-custom.xml

<alfresco-config>

<!--  add webable aspect properties to property sheet -->
<config evaluator="aspect-name" condition="orb:brandable">
  <property-sheet>
      <show-property name="orb:brand" display-label-id="brand" />
  </property-sheet>
</config>

<!-- show related documents association on doc property sheet -->
<config evaluator="node-type" condition="orb:doc">
  <property-sheet>
  </property-sheet>
</config>

<!-- show related documents association on whitepaper property sheet -->
<config evaluator="node-type" condition="orb:marketing_content">
  <property-sheet>
      <show-property name="orb:effective_from" display-label-id="effective_from" />
      <show-property name="orb:effective_to" display-label-id="effective_to" />
  </property-sheet>
</config>

<!--  add orbitz types to add content list -->
<config evaluator="string-compare" condition="Content Wizards">
  <content-types>
      <type name="orb:doc" />
      <type name="orb:marketing_content" />
  </content-types>
</config>

<config evaluator="string-compare" condition="Action Wizards">
  <!-- The list of aspects to show in the add/remove features action -->
  <!-- and the has-aspect condition -->
  <aspects>
      <aspect name="orb:brandable"/>
  </aspects>

  <!-- The list of types shown in the is-subtype condition -->
  <subtypes>
      <type name="orb:doc" />
      <type name="orb:marketing_content" />
  </subtypes>  

  <!-- The list of content and/or folder types shown in the specialise-type action -->
  <specialise-types>
      <type name="orb:doc" />
      <type name="orb:marketing_content" />
  </specialise-types>  
</config>

<config evaluator="string-compare" condition="Advanced Search">
  <advanced-search>
      <content-types>
          <type name="orb:doc" />
          <type name="orb:marketing_content" />
      </content-types>
      <custom-properties>
          <meta-data aspect="orb:brandable" property="orb:brand" display-label-id="brand" />
      </custom-properties>
  </advanced-search>
</config>
</alfresco-config>

webclient.properties

#orb:marketing_content
effective_from=Effective From
effective_to=Effective To

#orb:brandable
brand=Brand

Step 3 - Deploy

Make sure that build.properties is properly configured

1. Run ant deploy

Step 4 - Test Model
As a prerequisite, you should go to Share client and create a new site (i.e. 'Merchandising')

1. In Alfresco Explorer client - Upload content as type 'Marketing Content'
2. Apply 'Brandable' aspect
3. Modify content propertis -- should look like picture below

In order for this form to render, we need to modify the forms configuration to let Share know how to render our custom type and aspect. For details on this, see the forms wiki and forms examples wiki pages.

Step 5: Configure share to render the orb:market_content type and orb:brandable aspect

Create a file named 'web-framework-config-custom.xml' and deploy it to the share/WEB-INF/classes/alfresco/web-extension directory with the contents:

<alfresco-config>

 <config evaluator="node-type" condition="orb:marketing_content">
    <forms>
       <form>
          <field-visibility>
             <!-- inherited from cm:content -->
             <show id="cm:name" />
             <show id="cm:title" force="true" />
             <show id="cm:description" force="true" />
             <show id="mimetype" />
             <show id="cm:author" force="true" />
             <show id="size" for-mode="view" />
             <show id="cm:creator" for-mode="view" />
             <show id="cm:created" for-mode="view" />
             <show id="cm:modifier" for-mode="view" />
             <show id="cm:modified" for-mode="view" />
           
             <!--  specific for orb:marketing_content -->
             <show id="orb:effective_from" />
             <show id="orb:effective_to" />

             <!--  aspect orb:brandable -->             
             <show id="orb:brand" />
           
          </field-visibility>
          <appearance>
             <field id="orb:effective_from" label="Effective From"/>
             <field id="orb:effective_to" label="Effective To"/>
             <field id="orb:brand" label="Brand">
                <control template="controls/selectone.ftl">
                   <control-param name="options">Orbitz,CheapTickets,eBookers</control-param>
                </control>
             </field>
          </appearance>
       </form>
    </forms>
 </config>
</alfresco-config>

As we see here, we needed to copy all of the default properties from cm:content as well as add our unique properties for orb:marketing_content, and add the orb:brands aspect. This gives us very fine-grained control, but we can see there could be a lot of repeated configurations if we use types with aspects in complex ways.

Step 5: Run the example

Now we can go ahead and restart share and log in and select 'edit metadata' of our content previously checked in with the type orb:marketing_content and set with the orb:brandable aspect.

Now we should see the following:



We customized the selectone.ftl control template to provide our list of brands. One can consider an extension to this control would be to look up this list from a data web-script.

We should create our own selectone lookup from an external source in an ajax way. We will do so in a further blog article.

Looking at Alfresco Share 3.2 Community - Part 2 - Edit Custom Metadata

This series of blog entries is intended to walk through the new features of Alfresco Share 3.2 Labs. In the previous blog entry, I built the community version from source, and looked at the new Admin Console feature. This blog, I will look at how Share exposes Custom metadata, and allows users to assign aspects to uploaded content.

Viewing and Editing Custom Metadata

I have Alfresco 3.2 Labs running on my Windows XP Laptop, built from source updated June 23, 2009, and I have deployed both Alfrsco.war and share.war to an instance of Tomcat 6.

In previous versions of Share, it wasn't possible to view or edit custom metadata. Share 3.2 Labs addresses this deficit. Further, it leverages Surf's new forms architecture to render the metadata form dynamically. We will look at this in detail later. First, I will walk through the user interface for metadata.

In order to show Share's ability to view custom metadata, we need to create a new Site and Upload some content. Here are the steps briefly:

1. Log into Share (as admin/admin) --> The User Dashboard renders with the 'My Sites' dashlet.
2. Click on 'Create Site' in the My Sites dashlet (or select 'create site' from the 'Sites' drop down in the top menu) --> The Create Site popup will render.
3. Enter the Name, URL name, and Description (optional) of this new site. (In my example I created a site with Name=Merchandising, URL name=Merchandising).
4. Press 'Ok' when complete and the new site will be created, returning you to the user dashboard.
   
5. Select the new site from the 'My Sites' dashlet, or the top menu's Sites dropdown --> the Site dashboard will render.
6. Navigate to the 'Document Library' page to upload new content --> the Document Library page renders.
7. Click on 'Upload' button to upload some content to the default documents folder.
   

Now that we have content, we should be able to view the metadata.

Here I am looking at Document Library in the merchandising site, where have uploaded an XML file and a couple of image files...


Hovering over one of the files in the list renders the actions that can be performed on that file.
Actions include:

• Download
• Edit Metadata
• Upload new Version
• More > (we will look at some of these later)
  

This list of actions is very configurable. We may show how to do this in a later blog.
The 'Edit Metadata' action is what we want. Select the 'Edit Metadata' action for the uploaded document.

Here I selected edit metadata for an XML ddocument named 'Article.EnableCookies.xml'...



This looks pretty normal. It is the same popup as with previous version of Share allowing edit of basic metadata properties like Name, Title, Description and tags. But notice in the Upper right corner 'Full metadata Edit page...'. Selecting this will render a full screen rendering all of the document's metadata.

Here I am showing the full metadata page of the xml file I uploaded...


In this example, two new fields are rendered: the Mimetype, and the Author.

This full page renders the metadata form in 'Edit' mode using the new forms engine. The form is rendered by obtaining a form configuration from the remote alfresco repository. This form configuration is dynamically generated from the available metadata on the content item being viewed. The form archtiecture is capable of rendering the following types of controls (see more detail in the forms service wiki:

• mimetype -- <select> <option> from a list of mime types (i.e. application/pdf, ...)
• size -- display file size
  
• textarea -- <textarea> field configurable to r rows and c columns
  
• slectone -- <select> field with <option> tags dynamically rendered
  
• textfiled -- <input type="text"> field
  
• category -- picker selecting one or more categories to associate with the content
  
• endocding -- <select> field to choose <option> from list of encoding types (i.e. UTF-8, ISO-8859-1, ...)
  
• association -- picker selecting one or more other content items to associate this content item too
  
• checkbox -- <input type="checkbox"> field
  
• readonly -- <input type="text"> rendered as read only
  
• date -- renders a date picker setting value to an <input type="text"> field
  
• period -- selecting x days, weeks, etc.
  

Associating Aspects

To really show the custom metadata feature, we will look at another great feature added to Share 3.2, the ability to associate new aspects to documents. When we associate a new aspect, new properties can be added to the document and the edit metadata full form should reflect those changes. To do this, let us add the 'dublin core' aspect to the document we just looked at.

1. Hover over the document --> the actions should render
2. Select the 'more' option --> the more options should render
3. Select the 'manage aspects' option --> the manage aspects popup will render
4. Select the '+' by the 'Dublin Core' aspect in the 'Available to Add' list --> The 'Dublin core' should be removed from the 'Available to Add' and added to the 'Currently Selected' list
5. Select the 'Apply changes' button to save the changes

Now we can look at the edit metadata again and see the new metadata properties added via the Dublin Core aspect

Here we see the edit metadata full page with the dublin core properties



The next blog entry will look at customizing share to display our own content types and aspects.

Looking at Alfresco Share 3.2 Community

Building Alfresco Labs 3.2 from Community

This blog and others to follow will walk through the new features of Alfresco Share 3.2 Labs. First, I will walk through some of the key features. Then I will open up the box and look in side at a few choice features. Finally, I will show examples of the extensibility of this new version of Share.

Building from source was fairly straight forward. I use Tortoise SVN as my svn client (on my Windows XP laptop). I 'updated' to the latest code (as of 23 June 09). I used ant to build, with my environment setup as recommended in the Alfresco SVN Development environment wiki.

When attempting to deploy to tomcat using 'ant build-tomcat' and 'ant incremental-tomcat', the ant task complained that I needed to use tomcat 6. I downloaded Apache tomcat 6.0.20. I noticed that tomcat 6 doesn't create a 'shared' folder by default, which is used by alfresco for extension. But I found a wiki page for configuring tomcat 6 that explains how to configure tomcat 6 for this purpose.

Because I have multiple versions of alfresco on this machine, I didn't want to sacrifice the default db (mysql database named alfresco). I had problems with configuring other db vendor, however. I followed the configuring db wiki page for 3.2 and tried boty Derby and HSQL as alternatives. However, various problems occurred. HSQL and Derby didn't seem to have corrected hibernate mappings and/or sql build scripts. So I chose to create another db instance on mysql named alfresco2. I'm sure with a little more patience, I would have succeeded. But I'm impatient.

In order to configure to this new db (and as described on the database configuration wiki page), I found that there is now a file 'alfresco-global.properties' that you can copy from your TOMCAT_HOME/webapps/alfresco/WEB-INF/classes directory (named 'alfresco-global.properties.sample') to TOMCAT_HOME/shared/classes directory, renamed to 'alfresc-global.properties'. I noted that this did NOT go into an 'alfresco/extensions' subdirectory as in the past with 'custom-repository.properties'.

Starting up tomcat on my windows xp with the default configurations caused a problem with out of heap space and, later PermGen. I changed the startup parameters to add more heap and PermGen (-Xms256M -Xmx512M -XX:MaxPermSize=256m) and finally I was in business.

First Impressions of Share 3.2

After logging in to share (i.e. http://localhost:8080/share) with the default user account admin/admin, the admin user dashboard is rendered first. Nothing new here. However in the header, right justified I saw a 'Admin Console' button. Clicking it, I see you can now create new users and groups from Share directly!

Here I logged in as admin/admin...




Admin Console

It seems there is a new role for Share users, that of 'Manager'. This role is described in the forums. The 'Manager' role has permisions to expose the new 'admin console.'

The Admin Console is accesssed by clicking the 'Admin Console' button on the top menu. This console is configured with an extensible list of console 'tools'. The console opens up showing the first tool: Groups.

Groups Tool

Here, I clicked on the 'Admin Console' button...



The 'Groups' tool allows a user to drill down through the hierarchy of groups, and create new groups, edit them and remove them. To represent the hierarchy, the user interface represents levels of groups by showing child groups in a new list panel created to the right of the group list panel with the selected group. The successive levels of group lists all have similar functionality (recursively rendered) to add, edit and remove groups and their children. This UI approach is a bit odd, but effective.

Clicking 'new group' opens the 'Create Group' form, prompting the user to enter the required fields for: Identifier and Display name. Once entered, the buttons 'Create Group', 'Create and Create Another' are enabled. The 'Create Group' creates a group with the given Identifier and Display name, and returns back to the 'Groups' tool main page. The 'Create and Create Another' creates a group as the 'Create Group' button but clears the form to enter another group. The labels of these buttons might be a bit confusing at first.

Here I clicked the 'New group' button ...


I tried creating a new group and the group called 'testg', but it wasn't added to the list immediately. Reopening the admin console later, I saw the group I created listed correctly (see https://issues.alfresco.com/jira/browse/ALFCOM-3110).

In the Groups tool of the Admin Console, hovering over an item indicates other actions that can be performed on that item, including 'edit' and 'delete'.

Users tool

The users tool of the 'Admin Console' allows the manager to create new users and edit users. The search box requires at least one character entered before search works. (Perhaps adding a note on this screen or disabling/enabling the 'search' button might help.) This search text seems to be a partial match to find anything with the text entered 'in' the user's name.

Here I typed 'a' and pressed 'Search'...


A new user can be created from the users tool main page by clicking the 'New User' button upper right, or an existing user details can be viewed, and later edited, by clicking on the user name in the list.

Here I clicked on the 'Jane Smith' name in the users list...

From the user profile view page there are two buttons: Edit User and Delete User. From the Edit User page, you can enter basic information, assign the user to groups, set a quota, change passwords and select photos.

Next blog entry -- look at edit metadata feature.