xdocs/services/ui-service.xml - turbine-core - Git at Google

 <?xml version="1.0"?>

 <!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
 -->

 <document>

  <properties>
   <title>Turbine Services - UI Service</title>
   <author email="seade@backstagetech.com.au">Scott Eade</author>
  </properties>

 <body>

 <section name="UI Service">

 <p>
 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.
 </p>

 <p>
 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):
 </p>
 <ul>
 <li>Skin properties are shared between all users with lazy loading.</li>
 <li>Non-default skin files inherit properties from the default skin</li>
 <li>Access to skin properties from screen and action classes is now provided for</li>
 <li>Access is provided to the list of available skins</li>
 </ul>

 </section>

 <section name="Configuration">

 <source><![CDATA[
 # -------------------------------------------------------------------
 #
 #  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
 ...
 ]]></source>

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

 <source><![CDATA[
 checkedImage = check.gif
 checkedImageAltText = Tick
 label_Introduction = Introduction
 l10n_label_introduction = introduction
 ]]></source>

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

 <source><![CDATA[
 checkedImage = check-blue.gif
 checkedImageAltText = Blue tick
 label_Introduction = Summary
 l10n_label_introduction = summary
 ]]></source>

 </section>

 <section name="Usage">

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

 <source><![CDATA[
 TurbineUI.get(user.getSkin(), "label_Introduction")
 ]]></source>

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

 <source><![CDATA[
 $ui.label_Introduction
 ]]></source>

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

 <source><![CDATA[
 #set($imageurl = $ui.image($imageName))
 ## Filename is skin.css
 #set($cssurl = $ui.getStylecss())
 #set($jsurl = $ui.getScript($filename))
 ]]></source>

 <p>
 You can retrieve an array containing the names of the available skins thus:
 </p>

 <source><![CDATA[
   String[] availableSkins = TurbineUI.getSkinNames();
 ]]></source>

 <p>
 or in a template:
 </p>

 <source><![CDATA[
   #set($availablekins = $ui.SkinNames)
 ]]></source>

 <p>
 You can combine skinning and <a href="localization-service.html">localization</a>
 thus:
 </p>

 <source><![CDATA[
 ## Retrieve the localized label_introduction or label_summary depending on the
 ## selected skin
 $l10n.get("label_$ui.l10n_label_introduction")
 ]]></source>

 <p>
 Please refer to the JavaDocs for the org.apache.turbine.services.ui package for
 further details.
 </p>

 </section>

 <section name="Properties">
 <p>
 You can configure the UI Service using the following properties:
 </p>

 <table>
 <tr>
 <th>Property</th>
 <th>Default</th>
 <th>Function</th>
 </tr>
 <tr>
 <td>tool.ui.dir.skin</td>
 <td>/ui/skins</td>
 <td>The name of the skin directory that is to be used for the web application.</td>
 </tr>
 <tr>
 <td>tool.ui.skin</td>
 <td>default</td>
 <td>The name of the default skin that is to be used for the web application.</td>
 </tr>
 <tr>
 <td>tool.ui.dir.image</td>
 <td>/images</td>
 <td>The name of the image directory inside the skin that is to be used for the
  web application.</td>
 </tr>
 <tr>
 <td>tool.ui.css</td>
 <td>skin.css</td>
 <td>The name of the css file that is to be used for the web application.</td>
 </tr>

 <tr>
 <td>tool.ui.want.relative</td>
 <td>false</td>
 <td>You can configure the UI Service to return relative links for the web
  application by setting this to <code>true</code>.</td>
 </tr>
 </table>

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

 </section>

 </body>
 </document>
	<?xml version="1.0"?>

	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<document>

	<properties>
	<title>Turbine Services - UI Service</title>
	<author email="seade@backstagetech.com.au">Scott Eade</author>
	</properties>

	<body>

	<section name="UI Service">

	<p>
	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.
	</p>

	<p>
	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):
	</p>
	<ul>
	<li>Skin properties are shared between all users with lazy loading.</li>
	<li>Non-default skin files inherit properties from the default skin</li>
	<li>Access to skin properties from screen and action classes is now provided for</li>
	<li>Access is provided to the list of available skins</li>
	</ul>

	</section>

	<section name="Configuration">

	<source><![CDATA[
	# -------------------------------------------------------------------
	#
	# 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
	...
	]]></source>

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

	<source><![CDATA[
	checkedImage = check.gif
	checkedImageAltText = Tick
	label_Introduction = Introduction
	l10n_label_introduction = introduction
	]]></source>

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

	<source><![CDATA[
	checkedImage = check-blue.gif
	checkedImageAltText = Blue tick
	label_Introduction = Summary
	l10n_label_introduction = summary
	]]></source>

	</section>

	<section name="Usage">

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

	<source><![CDATA[
	TurbineUI.get(user.getSkin(), "label_Introduction")
	]]></source>

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

	<source><![CDATA[
	$ui.label_Introduction
	]]></source>

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

	<source><![CDATA[
	#set($imageurl = $ui.image($imageName))
	## Filename is skin.css
	#set($cssurl = $ui.getStylecss())
	#set($jsurl = $ui.getScript($filename))
	]]></source>

	<p>
	You can retrieve an array containing the names of the available skins thus:
	</p>

	<source><![CDATA[
	String[] availableSkins = TurbineUI.getSkinNames();
	]]></source>

	<p>
	or in a template:
	</p>

	<source><![CDATA[
	#set($availablekins = $ui.SkinNames)
	]]></source>

	<p>
	You can combine skinning and <a href="localization-service.html">localization</a>
	thus:
	</p>

	<source><![CDATA[
	## Retrieve the localized label_introduction or label_summary depending on the
	## selected skin
	$l10n.get("label_$ui.l10n_label_introduction")
	]]></source>

	<p>
	Please refer to the JavaDocs for the org.apache.turbine.services.ui package for
	further details.
	</p>

	</section>

	<section name="Properties">
	<p>
	You can configure the UI Service using the following properties:
	</p>

	<table>
	<tr>
	<th>Property</th>
	<th>Default</th>
	<th>Function</th>
	</tr>
	<tr>
	<td>tool.ui.dir.skin</td>
	<td>/ui/skins</td>
	<td>The name of the skin directory that is to be used for the web application.</td>
	</tr>
	<tr>
	<td>tool.ui.skin</td>
	<td>default</td>
	<td>The name of the default skin that is to be used for the web application.</td>
	</tr>
	<tr>
	<td>tool.ui.dir.image</td>
	<td>/images</td>
	<td>The name of the image directory inside the skin that is to be used for the
	web application.</td>
	</tr>
	<tr>
	<td>tool.ui.css</td>
	<td>skin.css</td>
	<td>The name of the css file that is to be used for the web application.</td>
	</tr>

	<tr>
	<td>tool.ui.want.relative</td>
	<td>false</td>
	<td>You can configure the UI Service to return relative links for the web
	application by setting this to <code>true</code>.</td>
	</tr>
	</table>

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

	</section>

	</body>
	</document>