Web Client Customisation FAQ

[resplin]

Obsolete Pages{{Obsolete}}

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

Back to Web Client Customisation Guide

Table of Contents

• 1 Introduction


• 2 Adding Languages


• 3 From Email Address


• 4 Topic View Sorting Direction


• 5 Adding Aspects to the Run Action & Create Rule Wizards


• 6 Transformation Mime type


• 7 Handling Required Properties


• 8 Adding Custom Icons


• 9 Adding Custom Menu Items


• 10 Change Size Of Text Fields


• 11 Using A TextArea


• 12 Changing Year Ranges


• 13 Resetting Date Picker Behaviour


• 14 Changing the Default View in Web Client


• 15 Changing the default Sidebar component from the Navigator Tree to the Shelf


• 16 Allowing the Guest User to modify the start location


• 17 Adding Properties to Simple Search


• 18 Changing Breadcrumb Mode

Introduction

This page shows how a series of very simple customisations can be applied to the Alfresco Web Client via configuration changes alone.

Adding Languages

To add another language to the drop down list in the login page add the following to web-client-config-custom.xml:

<config evaluator='string-compare' condition='Languages'>
   <languages>
      <language locale='fr_FR'>French</language>
   </languages>
</config>

From Email Address

To change the from email address used when users are invited to a space add the following to web-client-config-custom.xml:

<config>
   <client>
      <from-email-address>someone@your-domain.com</from-email-address>
   </client>
</config>

Topic View Sorting Direction

By default the topic view in the forums functionality lists the posts in descending order i.e. the last post is at the top of the list. If you wish to change this add the following to web-client-config-custom.xml:

<config evaluator='string-compare' condition='Views'>
   <views>
      <view-defaults>
         <topic>
            <sort-direction>ascending</sort-direction>
         </topic>
      </view-defaults>
   </views>
</config>

Adding Aspects to the Run Action & Create Rule Wizards

In the Run Action and Create/Edit Rule Wizards the aspect related actions and conditions feature a list of aspects the user can select from. This list is driven from the 'Action Wizards' configuration section.

To add the 'ImageClassification' aspect that was defined in the Data Dictionary Guide, add the following to web-client-config-custom.xml:

   <config evaluator='string-compare' condition='Action Wizards'>
      <aspects>
         <aspect name='my:imageClassification' 
                 [display-label='Image Classification'] 
                 [display-label-id='image_classification']/>
         ...

There are three options for specifying the display-label to display for each aspect (the same applies for the other items you can configure i.e. types, transformers). If no display-label is given it is retrieved from the data dictionary. To override the data dictionary title directly specify a 'display-label' attribute or to override using a localized string, specify the lookup key via the 'display-label-id' attribute.

Transformation Mime type

All mime types have to be registered within the repository.  Read the server configuration section on how to add a mime type to the server.

The mime type can be added to the list of supported transformations by adding the following to web-client-config-custom.xml:

<config evaluator='string-compare' condition='Action Wizards' replace='false'>
   <transformers>
      <transformer name='my_new_mimetype'/>
   </transformers>
</config>

Handling Required Properties

After content is added via the web client the edit properties dialog is displayed to encourage users to enter properties that are required. 

A message is shown on the add and create content wizards allowing the user to skip the edit properties page if they want to.

Whether the message appears and the initial state of the checkbox is driven by the configuration below.  You can change the default behaviour to suit your needs.

<config evaluator='string-compare' condition='Content Wizards'>
   <other-properties user-choice-visible='true' user-choice-default='true' /> 
</config>

To turn off the message completely set the user-choice-default attribute to false.

Adding Custom Icons

To add another space icon to the list of available icons to choose from when creating or editing a space, add the following to web-client-config-custom.xml:

<config evaluator='string-compare' condition='cm:folder icons'>
   <icons>
      <icon name='space-icon-custom' path='/images/icons/space-icon-custom.gif' />
   </icons>
</config>

Make sure that space-icon-custom.gif and space-icon-custom-16.gif exist in your /images/icons directory in order for everything to display properly.  The former is used for large icon rendering (32x32) and the latter is used for small icon rendering (16x16), such as in the navigation tree. Optionally you can add a 64x64 icon named space-icon-custom-64.gif.

If you would like to use a different image name, simply make sure that the icon name matches the name of your file.

<config evaluator='string-compare' condition='cm:folder icons'>
   <icons>
      <icon name='space-icon-custom' path='/images/icons/space-icon-custom.gif' />
      <icon name='another-custom-icon' path='/images/icons/another-custom-icon.gif' />
   </icons>
</config>

To support this, make sure that another-custom-icon.gif and another-custom-icon-16.gif exist in your /images/icons directory.

A similar approach can be used to add icons for the fm:forums, fm:forum and fm:topic space types.  This can additionally be applied to your own custom types!  Simply change the condition attribute to match the prefixed names of your custom space and content types. The conditions should end with icons i.e. 'fm:forums icons'.

Adding Custom Menu Items

In 1.3 it is now very easy to add your own menu items. For example, to launch a fictional addAspect dialog from the more actions menu associated with each space, add the following to web-client-config-custom.xml:

<config>
   <actions>
      <action id='add_aspect'>
         <label>Add Aspect</label>
         <image>/images/icons/add.gif</image>
         <action>dialog:addAspect</action>
      </action>
         
      <action-group id='space_browse_menu'>
         <action idref='add_aspect' />
      </action-group>
   </actions>
</config>

The space_browse_menu defines where in the webclient the action will be shown, here is a list with the allowed values. Each space will now have an 'Add Aspect' menu item as shown in the screenshot below.

Custom-menu-item.gif

To see all the options available for configuring client actions refer to Externalised Client Actions.

Change Size Of Text Fields

If the size of the text fields rendered in property sheets is too small, it can be overriden.   This is handled by overriding TextFieldGenerator managed bean definition. As stated in Packaging And Deploying Extensions the following configuration must be placed in the faces-config-custom.xml file.

<managed-bean>
   <managed-bean-name>TextFieldGenerator</managed-bean-name>
   <managed-bean-class>org.alfresco.web.bean.generator.TextFieldGenerator</managed-bean-class>
   <managed-bean-scope>request</managed-bean-scope>
   <managed-property>
      <property-name>size</property-name>
      <value>50</value>
   </managed-property>
</managed-bean>

The configuration above will render all text fields (those used in a property sheet) with a size of '50'.

If a specific text field size needs to be changed an additional text field generator can be configured and applied to a specific property. For example if a 'name' property needed to have a text field size of '75' the following configuration would be used.

JSF configuration:

<managed-bean>
   <managed-bean-name>NameTextFieldGenerator</managed-bean-name>
   <managed-bean-class>org.alfresco.web.bean.generator.TextFieldGenerator</managed-bean-class>
   <managed-bean-scope>request</managed-bean-scope>
   <managed-property>
      <property-name>size</property-name>
      <value>75</value>
   </managed-property>
</managed-bean>

web-client-config-custom.xml:

<property name='name' component-generator='NameTextFieldGenerator' />

NOTE: As this example configured a new managed bean it can either be entered in the faces-config-custom.xml or a faces-config.xml file within a JAR, see Packaging And Deploying Extensions for full details.

Using A TextArea

If a property requires a lot of information to be entered a text area may be more applicable. From the 1.4 release onwards a TextAreaGenerator is available.

For example to use a text area for a description property use the following configuration in web-client-config-custom.xml.

<property name='name' component-generator='TextAreaGenerator' />

The default value for rows is '3' and the default values for columns is '32'.

To change these defaults the TextAreaGenerator managed bean definition needs to be overridden. As stated in Packaging And Deploying Extensions the following configuration must be placed in the faces-config-custom.xml file.

<managed-bean>
   <managed-bean-name>TextAreaGenerator</managed-bean-name>
   <managed-bean-class>org.alfresco.web.bean.generator.TextAreaGenerator</managed-bean-class>
   <managed-bean-scope>request</managed-bean-scope>
   <managed-property>
      <property-name>rows</property-name>
      <value>10</value>
   </managed-property>
   <managed-property>
      <property-name>columns</property-name>
      <value>75</value>
   </managed-property>
</managed-bean>

The configuration above will render all text areas (those used in a property sheet) with '10' rows and '75' columns.

Alternatively, a custom text area generator can be defined and applied to an specific property. For example if a 'description' property needed to have a text area with '5' rows and '50' columns the following configuration would be used.

JSF configuration:

<managed-bean>
   <managed-bean-name>DescriptionTextAreaGenerator</managed-bean-name>
   <managed-bean-class>org.alfresco.web.bean.generator.TextAreaGenerator</managed-bean-class>
   <managed-bean-scope>request</managed-bean-scope>
   <managed-property>
      <property-name>rows</property-name>
      <value>5</value>
   </managed-property>
   <managed-property>
      <property-name>columns</property-name>
      <value>50</value>
   </managed-property>
</managed-bean>

web-client-config-custom.xml:

<property name='description' component-generator='DescriptionTextAreaGenerator' />

NOTE: As the last example configured a new managed bean it can either be entered in the faces-config-custom.xml or a faces-config.xml file within a JAR, see Packaging And Deploying Extensions for full details.

Changing Year Ranges

From the 1.4 release the start year and number of years displayed in the date picker controls can be configured.

The default value for 'yearCount' is '30' and the default value for 'startYear' is '2008'.

To change these defaults the DatePickerGenerator or DateTimePickerGenerator managed bean definitions need to be overridden. As stated in Packaging And Deploying Extensions the following configuration must be placed in the faces-config-custom.xml file.

<managed-bean>
   <managed-bean-name>DatePickerGenerator</managed-bean-name>
   <managed-bean-class>org.alfresco.web.bean.generator.DatePickerGenerator</managed-bean-class>
   <managed-bean-scope>request</managed-bean-scope>
   <managed-property>
      <property-name>startYear</property-name>
      <value>2020</value>
   </managed-property>
   <managed-property>
      <property-name>yearCount</property-name>
      <value>20</value>
   </managed-property>
</managed-bean>

The configuration above would show the years 2000 to 2020 for all d:date properties (those used in a property sheet). To show the same range for d:datetime properties also override the DateTimePickerGenerator in the same manner.

Alternatively, a different year range can be defined and applied to an specific property. For example if a 'publishedOn' property needed to have a year range of 2005 to 1980 the following configuration would be used.

JSF configuration:

<managed-bean>
   <managed-bean-name>MyDatePickerGenerator</managed-bean-name>
   <managed-bean-class>org.alfresco.web.bean.generator.DatePickerGenerator</managed-bean-class>
   <managed-bean-scope>request</managed-bean-scope>
   <managed-property>
      <property-name>startYear</property-name>
      <value>2005</value>
   </managed-property>
   <managed-property>
      <property-name>yearCount</property-name>
      <value>25</value>
   </managed-property>
</managed-bean>

web-client-config-custom.xml:

<property name='publishedOn' component-generator='MyDatePickerGenerator' />

NOTE: As the last example configured a new managed bean it can either be entered in the faces-config-custom.xml or a faces-config.xml file within a JAR, see Packaging And Deploying Extensions for full details.

Resetting Date Picker Behaviour

The 1.4 release changed the behaviour of the date and date/time picker control. Now, if the underlying date is null the picker will display the word 'None'. The text can be clicked to set a date, buttons also appear now to allow the date to be set back to null.

If this behaviour is undesired it can be reset to that of 1.3.1 and lower releases (with the exception of the Today button, that is seen as a useful usability enhancement so will remain). This means if a date is set to null today's date will be shown automatically.

To change these defaults the DatePickerGenerator or DateTimePickerGenerator managed bean definitions need to be overridden. As stated in Packaging And Deploying Extensions the following configuration must be placed in the faces-config-custom.xml file.

<managed-bean>
   <managed-bean-name>DatePickerGenerator</managed-bean-name>
   <managed-bean-class>org.alfresco.web.bean.generator.DatePickerGenerator</managed-bean-class>
   <managed-bean-scope>request</managed-bean-scope>
   <managed-property>
      <property-name>initialiseIfNull</property-name>
      <value>true</value>
   </managed-property>
</managed-bean>

To do the same for d:datetime properties override the DateTimePickerGenerator in the same manner.

The same technique outlined in the previous examples can be used to apply this behaviour to individual properties.

This feature allows date fields to be initialised when the underlying model value is null. However, enabling this property will hide the None button meaning users will not be able to reset the date to null. If this behaviour is required it's recommended that the underlying model is set with a default value and the 'initialiseIfNull' property is left in it's default state of 'false'.

Changing the Default View in Web Client

You can change the default view in the web client by editing web-client-config-custom.xml and overriding the default view.  Options are list, details and icons.

<config evaluator='string-compare' condition='Views'>
      <views>
         <view-defaults>
            <browse>
               <view>details</view>
               <page-size>
                  <list>20</list>
                  <details>20</details>
                  <icons>20</icons>
               </page-size>
            </browse>
         </view-defaults>
      </views>
</config>

Changing the default Sidebar component from the Navigator Tree to the Shelf

You can change the default component displayed in the Sidebar panel of the web-client from the default Tree Navigator to the Shelf by editing web-client-config-custom.xml and overriding the default plugin:

   <config evaluator='string-compare' condition='Sidebar'>
      <sidebar>
         <default-plugin>shelf</default-plugin>
      </sidebar>
   </config>

Allowing the Guest User to modify the start location

By default the Guest user cannot modify their start location, however this can be enabled by adding this section to your web-client-config-custom.xml:

   <config>
      <client>
         <allow-guest-config>true</allow-guest-config>
      </client>
   </config>

The Guest user can then modify the start location in the User Console screen.

Adding Properties to Simple Search

By default the the simple search box in the UI will search full-text indexes and the 'name' property of files and folders. In Alfresco 2.1 it is possible to change the configuration to search additional attributes such as 'description' and 'title', for example add this section to your web-client-config-custom.xml:

   <config>
      <client>
         <simple-search-additional-attributes>
            <qname>{http://www.alfresco.org/model/content/1.0}description</qname>
            <qname>{http://www.alfresco.org/model/content/1.0}title</qname>
         </simple-search-additional-attributes>
      </client>
   </config>

The fully qualified QName of the d:text property to search must be provided.

Changing Breadcrumb Mode

From 2.9 onwards the breadcrumb mode can be changed. The breadcrumb supports two modes 'path' (the default) and 'location'. To change the breadcrumb into 'location' mode i.e. to show you the full path of the current space add the following to your web-client-config-custom.xml:

   <config>
      <client>
         <breadcrumb-mode>location</breadcrumb-mode>
      </client>
   </config>

Web Client Customization
FAQ
Alfresco Explorer
Customizing and Extending