Hyland Connect

resplin · ‎06-05-2015

The official documentation is at: http://docs.alfresco.com

Content Modeling Web Client Customization
Back to Web Client Customisation Guide

Note

The following documentation is applicable for the 1.3 release onwards.

For the releases between 1.2RC2 and 1.2.1 refer here and for previous releases refer here.

Introduction

This page describes how to configure the Web Client for use with custom Types and Aspects. To define your own custom Types and Aspects, refer to the Data Dictionary Guide. The file we're going to modify (web-client-config-custom.xml ) is located at:

Tomcat - TOMCAT_HOME/shared/classes/alfresco/extension
JBoss - JBOSS_HOME/server/default/conf/alfresco/extension

Viewing Aspect Properties in the Web Client Properties Page

The content of the Web Client properties page is data driven. Configuration allows the list of visible properties (and their order) to be specified on an Aspect by Aspect basis (and also Content Type basis).

To add the 'ImageClassification' aspect that was defined in the Data Dictionary Guide to the list of properties shown for a node with the aspect applied, the following XML is introduced...


   <config evaluator='aspect-name' condition='my:imageClassification'>
      <property-sheet>
         <show-property name='my:width'/>
         <show-property name='my:height'/>
         <show-property name='my:resolution'/>
      </property-sheet>
   </config>

There are 3 options for specifying the display label. If nothing is specified (as in the example above) the display label will be taken from the data dictionary title for the property. To override the display label directly specify a 'display-label' attribute or to override using a localized string, specify the lookup key via the 'display-label-id' attribute.

When the Properties page is displayed for a content object, the object is introspected and its aspects determined. A lookup in the configuration files is then made to retrieve all the <property-sheet> elements defined for the aspects applied to the object. It is not necessary to define a <property-sheet> for every aspect.

A list of properties to display for the object is then formulated from all the matching <property-sheet> definitions. Properties are displayed in the order they are defined in the configuration file. If a 'display-label-id' is provided, the 'display-label' tag is ignored.

Editing Aspect Properties in the Web Client Properties Page

Properties defined to display as explained in the previous section will automatically appear when editing properties of a node. To stop a property from appearing in the edit properties screen add the show-in-edit-mode attribute with a value of false. For example to hide the resolution property on the image classification aspect the configuration would be as follows:


   <config evaluator='aspect-name' condition='my:imageClassification'>
      <property-sheet>
         <show-property name='my:width'/>
         <show-property name='my:height'/>
         <show-property name='my:resolution' show-in-edit-mode='false' />
      </property-sheet>
   </config>

Furthermore, properties can be configured to be hidden in view mode, but show up in edit mode. For example to only show the resolution property when the property sheet is in edit mode use the following configuration:


   <config evaluator='aspect-name' condition='my:imageClassification'>
      <property-sheet>
         <show-property name='my:width'/>
         <show-property name='my:height'/>
         <show-property name='my:resolution' show-in-view-mode='false' />
      </property-sheet>
   </config>

Content Type Properties in the Web Client

The viewing and editing of content type properties may be configured in exactly the same manner as Aspect properties. The only difference is in the xml configuration; specify 'node-type' instead of 'aspect-name'.

For example, to add the 'SOP' type that was defined in the Data Dictionary Guide, the following XML is introduced...


   <config evaluator='node-type' condition='my:sop'>
      <property-sheet>
         <show-property name='name' show-in-edit-mode='false' />
         <show-property name='mimetype' display-label-id='mimetype' 
                        converter='org.alfresco.faces.MimeTypeConverter' 
                        show-in-edit-mode='false' />
         <show-property name='title' show-in-edit-mode='false' />
         <show-property name='description' show-in-edit-mode='false' />
         <show-property name='size' display-label-id='size' 
                        converter='org.alfresco.faces.ByteSizeConverter' 
                        show-in-edit-mode='false' />
         <show-property name='my:publishedDate' />
         <show-association name='my:signOff' />
         <show-property name='my:authorisedBy' />
         <show-child-association name='my:processSteps' />
      </property-sheet>
   </config>

Creating Custom Content Types in the Web Client

When content is added via the 'Add Content' or 'Create Content' wizard a drop down list gives the user the choice of what type to create the content as. This list is configurable so custom types can be added easily.

Again, using the custom 'SOP' content type defined in the Data Dictionary Guide, the following XML can be added...


   <config evaluator='string-compare' condition='Content Wizards'>
      <content-types>
         <type name='my:sop' [display-label='SOP'] [display-label-id='sop'] />
      </content-types>
   </config>

There are 3 options for specifying the display label. If nothing is specified the display label will be taken from the data dictionary title for the type. To override the display label directly specify a 'display-label' attribute or to override using a localized string, specify the lookup key via the 'display-label-id' attribute.

Creating Custom Space Types in the Web Client

When spaces are created via the 'Advanced Space Wizard' a list of space types are displayed. This list is configurable so custom types can be added easily.

For example if there was a custom space type to represent a wiki the XML to configure this may look like the following...


   <config evaluator='string-compare' condition='Space Wizards'>
      <folder-types>
         <type name='my:wikiSpace' [icon='/images/icons/wikiSpace_large.gif']
               [description-id='wikispace_desc'] [description='Inline description of a wiki space'] 
               [display-label='Wiki Space'] [display-label-id='wikispace'] />
      </folder-types>
   </config>

The icon attribute, if supplied, indicates which icon to use in the Advanced Space Wizard space type selection panel. If it omitted a default space icon will be used.

The description attributes indicates what should be inserted into the description panel of the Advanced Space Wizard space type page. The 'description' attribute allows an inline description to be supplied whereas 'description-id' allows a lookup key for a localised string to be specified.

There are 3 options for specifying the display label. If nothing is specified the display label will be taken from the data dictionary title for the type. To override the display label directly specify a 'display-label' attribute or to override using a localized string, specify the lookup key via the 'display-label-id' attribute.

Associations in the Web Client

The viewing and editing of associations and child associations for types and aspects can be configured in the same manner as properties.

To display an association on a type or aspect add the following XML snippet to the property-sheet element.


   <show-association name='my:signOff'/>

To display a child association on a type or aspect add the following XML snippet to the property-sheet element.


   <show-child-association name='my:processSteps'/>

The same rules for viewing/editing properties and the display-label applies to associations and child associations. The show-in-edit-mode attribute will hide the association from the edit page and the absence or presence of any display-label/display-label-id will determine what label is used.

Advanced Property Sheet Configuration

There are a few advanced features to mention, converters and component generators and separators.

Converters

By default the property sheet will display the raw contents of the property value (what is stored in the repository). If that raw form does not make sense i.e. the size of content is stored as an unformatted number, it can be converted for display purposes.

To assign a simple converter (one not requiring any parameters) to a property use the 'converter' attribute. For example to display a human readable content size add the following XML...


<show-property name='size' display-label-id='size' 
               converter='org.alfresco.faces.ByteSizeConverter' 
               show-in-edit-mode='false' />

Component Generators

By default the property sheet will render a control appropriate for the property type i.e. for a d:text property a text field will be rendered. This is not always desirable. Take, for example, an icon property, in the repository this will be stored as the name of the file or a path, but the user will want to see the actual icon.

To assign a control other than the default to a property use the 'component-generator' attribute. This relates to a bean registered with the Component_Generator_Framework. The named component generator is responsible for generating the JSF component required to represent the property.

In the default configuration, the cm:folder type uses the 'component-generator' attribute to specify that the property should be edited with the 'SpaceIconPickerGenerator'.


<show-property name='app:icon' show-in-view-mode='false' display-label-id='icon'
                        component-generator='SpaceIconPickerGenerator' />

Separators

Release 1.4 introduced the ability to add separators to property sheets.

To add a simple separator i.e. a HTML <hr> element add the following configuration:


<separator name='sep' />

When multiple separators are defined in the XML file, only the first separator will be used. Two other types of separator are available out of the box, a Label separator and a Header separator.

Label Separator

The label separator displays the text defined by the standard 'display-label' or 'display-label-id' attributes. For example to show 'General Properties' as a separator use the following configuration:


<separator name='sep' display-label='General Properties' component-generator='LabelSeparatorGenerator' />

or to use a string from a message bundle using the following configuration:


<separator name='sep' display-label-id='general_props' component-generator='LabelSeparatorGenerator' />

If display-label-id is used, the 'display-label' is ignored regardless of an available properties file.

Header Separator

The header separator is similar to the label generator in that it allows the text to be supplied via the 'display-label' or 'display-label-id' attributes but the text is shown in bold with the standard header background colour. To use the header separator the examples above would become:


<separator name='sep' display-label='General Properties' component-generator='HeaderSeparatorGenerator' />

<separator name='sep' display-label-id='general_props' component-generator='HeaderSeparatorGenerator' />

Implemention Details

The LabelSeparatorGenerator is implemented by org.alfresco.web.bean.generator.LabelSeparatorGenerator. This component generator allows the HTML 'style' and 'class' attributes to be configured thus allowing control over the appearance of the separator.

The default value for the 'style' property is 'margin-top: 6px; margin-bottom: 6px;', the default value for the 'styleClass' property is null.

The HeaderSeparatorGenerator is just an instance of this class with the HTML class (styleClass) set to 'wizardSectionHeading mainSubTitle' (defined in Alfresco's main.css file).

To configure a custom label based separator the following configuration would be added to the JSF config files (see Packaging And Deploying Extensions for more information on this).


<managed-bean>
   <managed-bean-name>MyHeaderSeparatorGenerator</managed-bean-name>
   <managed-bean-class>org.alfresco.web.bean.generator.LabelSeparatorGenerator</managed-bean-class>
   <managed-bean-scope>request</managed-bean-scope>
   <managed-property>
      <property-name>style</property-name>
      <value>margin-top: 10px;</value>
   </managed-property>
   <managed-property>
      <property-name>styleClass</property-name>
      <value>myHeading</value>
   </managed-property>
</managed-bean>

The label separator itself subclasses org.alfresco.web.bean.generator.HtmlSeparatorGenerator. The HTML separator generator allows configuration of the HTML to be displayed.

For example, if some instructional text was required at the bottom of a property sheet containing links an HtmlSeparatorGenerator could be used. To define the component generator the following configuration would be added to the JSF config files.


<managed-bean>
   <managed-bean-name>MyHtmlSeparatorGenerator</managed-bean-name>
   <managed-bean-class>org.alfresco.web.bean.generator.HtmlSeparatorGenerator</managed-bean-class>
   <managed-bean-scope>request</managed-bean-scope>
   <managed-property>
      <property-name>html</property-name>
      <value>
         <a href='#'>here</a> for full details.]]>
      </value>
   </managed-property>
</managed-bean>

Then to add this to a property sheet the following configuration would be used in web-client-config-custom.xml.


<separator name='sep' component-generator='MyHtmlSeparatorGenerator' />

Troubleshooting

If you run into problems configuring property sheets it may be that the property is not being found. There is a special debug flag called alfresco.missingProperties you can enable to see any properties that have been ignored if they are missing. The flag is found in log4j.properties and is enabled by default.