UI Service

The UI (User Interface) Service allows your Turbine application to be skinned using simple properties files that are located in the WEBAPP/resources/ui/skins/ directory hierarchy.

The service and its associated pull tool provide the following enhancements over the old UIManager pull tool (which has been deprecated as od Turbine 2.3.3):

  • Skin properties are shared between all users with lazy loading.
  • Non-default skin files inherit properties from the default skin
  • Access to skin properties from screen and action classes is now provided for
  • Access is provided to the list of available skins

Configuration

# -------------------------------------------------------------------
#
#  S E R V I C E S
#
# -------------------------------------------------------------------
...
services.UIService.classname = org.apache.turbine.services.ui.TurbineUIService
...

# -------------------------------------------------------------------
#
#  P U L L  S E R V I C E
#
# -------------------------------------------------------------------
...
## session scope allows us to pul the name of the selected skin from user.Temp
## If you wanted the same skin to apply for all users you could use global scope.
tool.session.ui = org.apache.turbine.services.pull.tools.UITool
tool.ui.skin = default
...

Skin properties are defined in WEBAPP/resources/ui/skins/, the following might exist in a file WEBAPP/resources/ui/skins/default/skin.props: 

checkedImage = check.gif
checkedImageAltText = Tick
label_Introduction = Introduction
l10n_label_introduction = introduction

and the following might exist in a file WEBAPP/resources/ui/skins/custom_skin_1/skin.props: 

checkedImage = check-blue.gif
checkedImageAltText = Blue tick
label_Introduction = Summary
l10n_label_introduction = summary

Usage

Retrieving a value from a skin is as simple as (where user.getSkin() returns the name of the currently selected skin): 

TurbineUI.get(user.getSkin(), "label_Introduction")

or in a template (the current skin is retrieved from user.Temp): 

$ui.label_Introduction

Images, css and javascript files are stored under the skin directory also and can be accessed thus: 

#set($imageurl = $ui.image($imageName))
## Filename is skin.css
#set($cssurl = $ui.getStylecss())
#set($jsurl = $ui.getScript($filename))

You can retrieve an array containing the names of the available skins thus: 

  String[] availableSkins = TurbineUI.getSkinNames();

or in a template: 

  #set($availablekins = $ui.SkinNames)

You can combine skinning and localization thus: 

## Retrieve the localized label_introduction or label_summary depending on the
## selected skin
$l10n.get("label_$ui.l10n_label_introduction")

Please refer to the JavaDocs for the org.apache.turbine.services.ui package for further details.

Properties

You can configure the UI Service using the following properties:

Property Default Function
tool.ui.dir.skin /ui/skins The name of the skin directory that is to be used for the web application.
tool.ui.skin default The name of the default skin that is to be used for the web application.
tool.ui.dir.image /images The name of the image directory inside the skin that is to be used for the web application.
tool.ui.css skin.css The name of the css file that is to be used for the web application.
tool.ui.want.relative false You can configure the UI Service to return relative links for the web application by setting this to true.

Note that the name of the file within the skin directory that actually contains the name/value pairs for the skin is fixed at skin.props.