In the previous post I explained how to configure uploader-plus to prompt for the metadata of the cm:content type. This was a simplified example because cm:content is a standard type and its forms are already configured in the basic Alfresco installation. Not much work left for us to do other than just use it!
But if you’re interested in metadata during the upload, cm:content is certainly too generic and you’re probably already looking at custom content types (like “invoice”, “order”, “appraisal” or “record”) that make more sense in your application domain. In this post I’ll show how to setup a form for this kind of content.
Step 1: install the example content model
To use a content model that both you and I can refer to, I recommend that you install the sample HR content model found in Alfresco Workdesk:
- download Alfresco Workdesk community 4.2.0-2014-06-30
- unzip the file
- read the instructions at bin/SampleApplication/HumanResourcesApplication/readme.txt
- install the custom model (using the install-workdesk-hr.bat or install-workdesk-hr.sh script)
The model will be installed in
tomcat/shared/classes/alfresco/extension/workdeskHRContentModel.xml of your Alfresco installation. In this post I’m going to use “owd:hrdocument”, one of the provided content types.
Step 2: set up an upload folder
Following the instructions of the previous post, set up an upload folder anywhere you like (e.g. /Sites/swsdp/documentLibrary/Agency Files) and choose owd:hrdocument as the allowed type.
Navigate to the folder and upload a document. The following form will be shown.
A rather long form! This form is generated automatically by Alfresco. Alfresco simply looks at the content type, finds all the properties and creates a field for each property. Borrowing the concept from Java, Alfresco can generate a form by performing some kind of “reflection” on the content type. No configuration is necessary other than defining the content model.
This automatic generation may sound good at first but is has its limits. A closer inspection of the form reveals that the properties are in random order and that some properties (modified/created date, creator/modifier) should not be offered to the user but kept hidden and populated by the system behind the scenes.
All these considerations make a case for configuring the form explicitly, rather than relying on Alfresco’s automatic generation.
Step 3: inspect the content type
tomcat/shared/classes/alfresco/extension/workdeskHRContentModel.xml and find the definition for owd:hrdocument. For convenience, the relevant fragment is shown below:
The type defines three properties:
- owd:documentPersonnelNumber (“Personnel Number”)
- owd:hrDocumentType (“Type”)
- owd:documentComment (“Comment”)
It also imports the mandatory aspect owd:AspectDate, from which it gains two other properties:
- owd:EntryDate (“Entry Date”)
- owd:DispatchDate (“Dispatch Date”)
Owd:hrdocument inherits from cm:content and, following the inheritance chain, from cm:cmobject and sys:base. Through inheritance, owd:hrdocument acquires approximately 10 more properties.
Also Alfresco automatically attaches the cm:titled an cm:author aspects to any content uploaded on the system, which provide three more properties.
Some of the properties are system properties (sys:store_protocol, etc) and should never be displayed. Some other properties are populated automatically (cm:created, etc) and should not be offered for input to the user. Other properties may make sense to your underlying application logic but are of little value in the user interface.
Your task is to choose the subset of properties that must really be entered by the user and so should be displayed in a form. Here, let’s assume we want to display the following properties:
We’re now ready to define a form.
Step 4: define the form
share-config-custom.xml configuration file under
The core of the form definition is the
field-visibility element, which lists the six properties that we decided to show. Other details about the xml are the following:
force="true"attribute is required on cm:title and cm:description because these belong to the cm:titled aspect, which is attached with a special mechanism.
appearanceelements is optional and is required only if you want to customise the appearance of some of the fields.
- The appearance of cm:name is customised to limit the input to 255 characters, a constraint of file names.
- The appearance of cm:title (which is of type mltext – multilingual text) is customised to be displayed using a text field instead of the default text area.
Fields can be customised in many other ways and it is even possible to use a completely custom form template. The subject is broad, for more information see the community wiki.
Step 5: test the form
share-config-custom.xml and restart Alfresco. Go to the upload folder and start an upload. This time you’ll be prompted by a nice, compact form:
Notice that the form definition is used not only by uploader-plus during the upload, but also by Alfresco during other operations where an owd:hrdocument is involved. To test this, upload a document, then select “Edit properties” from the document’s list of operations: the same form will be used.
Attaching metadata to documents is an important factor in maintaining a high quality repository. Documents without metadata are easily misclassified or lost. Documents with metadata are better classified and are more easily available for later retrieval.
Uploader-plus encourages this good practice by presenting users with effective, visually pleasant, customisable forms.