WebWork 2 : 主题

This page last changed on Dec 14, 2004 by casey.

主题是一组用于定制使用UI标签开发的页面的模版. 它提供了一个强大的机制允许web开发人员使用混合风格(颜色, 字体等)为用户界面增添亮色. 例如, 你可能希望表单中一半文本框使用蓝色背景而另一半使用白色背景. 注意:

Webwork附带两个已定义的主题; "simple"和"xhtml"(缺省的). WebWork缺省在应用的/template目录下查找主题. 缺省主题是xhtml. 这意味着如果你没有在UI标签中指定theme属性的话, 将使用缺省主题. 注意: 你可以在webwork.properties文件中修改webwork.ui.theme=和webwork.ui.templateDir=来改变缺省值.

也可以创建定制主题以适合自己的需要. 我们推荐参考已定义的模版作为起点.

每次使用UI标签时, 标签都引用一个模版来绘制HTML. 因此模版决定了字段外观和它在页面上的位置. 目前, 仅支持velocity模版. 无论如何, 希望在未来版本中支持创建JSP模版.

注意: 在继续之前, 推荐你复查WebWork模版系统的工作原理. (参见模版)

xhtml

xhtml是WebWork附带的缺省主题. 它扩展了simple主题并提供内建的错误报告, 表格定位和添加文本标签的功能. 然我们看看最常用的UI标签, textfield, 并展示使用XHTML主题创建视图的正确方法.

你可能已经知道, textfield标签使用的缺省模版是/template/xhtml目录下的text.vm.

#*
   -- text.vm
*#
## notice the re-use of the simple theme template text.vm
#parse("/template/xhtml/controlheader.vm")
#parse("/template/simple/text.vm")
#parse("/template/xhtml/controlfooter.vm")

该模版加载时, 将首先解析并绘制/template/xhtml/controlheader.vm. 在controlheader.vm中可以看到错误报告, 表格定位和添加文本标签的功能. 如果ActionSupport返回了错误, 将使用这个模版绘制成HTML. 还能看到如何获取parameter.label的值并使用表格元素tr和td进行定位.

#*
   -- controlheader.vm
*#
## Only show message if errors are available.
## This will be done if ActionSupport is used.

#if( $fieldErrors.get($parameters.name) )
  #set ($hasFieldErrors = $fieldErrors.get($parameters.name))
  #foreach ($error in $fieldErrors.get($parameters.name))
    <tr>
        #if ($parameters.labelposition == 'top')
            <td align="left" valign="top" colspan="2">
        #else
            <td align="center" valign="top" colspan="2">
        #end
            <span class="errorMessage">$!webwork.htmlEncode($error)</span>
            </td>
    </tr>
  #end
#end

## Provides alignment behavior with table tags
## if the label position is top,
## then give the label it's own row in the table
## otherwise, display the label to the left on same row

<tr>
    #if ($parameters.labelposition == 'top')
        <td align="left" valign="top" colspan="2">
    #else
        <td align="right" valign="top">
    #end

        #if ($hasFieldErrors)
            <span class="errorLabel">
        #else
            <span class="label">
        #end

## If you want to mark required form fields with an asterisk, 
## you can set the required attribute
## Ex. <ui:textfield label="'mylabel'" name="'myname'" required="'true'" /> 
        #if ($parameters.label)
            #if ($parameters.required) <span class="required">*</span> #end 
               $!webwork.htmlEncode($parameters.label):
        #end
            </span>
        </td>

## add the extra row
#if ($parameters.labelposition == 'top')
</tr>
<tr>
#end
    <td>

下一个被/template/xhtml/text.vm解析的模版是/template/simple/text.vm. 这里可以看到实际的HTML的text元素如何绘制以及参数如何传递的.

#*
  -- text.vm
  --
  -- Required Parameters:
  --   * label      - The description that will be used to identfy the control.
  --   * name       - The name of the attribute to put and pull the result from.
  --                  Equates to the NAME parameter of the HTML INPUT tag.
  --
  -- Optional Parameters:
  --   * labelposition   - determines were the label will be place in relation
  --                       to the control.  Default is to the left of the control.
  --   * size       - SIZE parameter of the HTML INPUT tag.
  --   * maxlength  - MAXLENGTH parameter of the HTML INPUT tag.
  --   * disabled   - DISABLED parameter of the HTML INPUT tag.
  --   * readonly   - READONLY parameter of the HTML INPUT tag.
  --   * onkeyup    - onkeyup parameter of the HTML INPUT tag.
  --   * tabindex  - tabindex parameter of the HTML INPUT tag.
  --   * onchange  - onkeyup parameter of the HTML INPUT tag.
  --
    *#
<input type="text"
                                   name="$!webwork.htmlEncode($parameters.name)"
#if ($parameters.size)             size="$!webwork.htmlEncode($parameters.size)"            #end
#if ($parameters.maxlength)        maxlength="$!webwork.htmlEncode($parameters.maxlength)"  #end
#if ($parameters.nameValue)        value="$!webwork.htmlEncode($parameters.nameValue)"      #end
#if ($parameters.disabled == true) disabled="disabled"                                      #end
#if ($parameters.readonly)         readonly="readonly"                                      #end
#if ($parameters.onkeyup)          onkeyup="$!webwork.htmlEncode($parameters.onkeyup)"      #end
#if ($parameters.tabindex)         tabindex="$!webwork.htmlEncode($parameters.tabindex)"    #end
#if ($parameters.onchange)         onchange="$!webwork.htmlEncode($parameters.onchange)"    #end
#if ($parameters.id)               id="$!webwork.htmlEncode($parameters.id)"                #end
#if ($parameters.cssClass)         class="$!webwork.htmlEncode($parameters.cssClass)"       #end
#if ($parameters.cssStyle)         style="$!webwork.htmlEncode($parameters.cssStyle)"       #end
/>

最后, 解析controlfooter.vm, 关闭controlheader.vm中输出的tr和td.

#*
   -- controlheader.vm
*#

  </td>
</tr>

在我们的视图中, 由于tr和td元素已经创建好了, 我们只需要简单的用table元素将它们包装起来. 出于学习的缘故, 我们仅使用普通的table对象, 但也可以看看table.vm的内容.

<%@ taglib uri="webwork" prefix="ui" %>
<link rel ="stylesheet" type="text/css" href="template/xhtml/styles.css" title="Style">
<html>
<head><title>JSP PAGE</title></head>
<body>
<form>
  <table>
	<!-- we can set the required attribute to true if we want to 
	     display and asterisk next to required form fields
	 -->

	<ui:textfield label="'Username'" required="'true'" name="'user'" /> 
	<ui:textfield label="'Email'" name="'email'"/> 
  </table>
</form>
</body>
</html>

<link rel ="stylesheet" type="text/css" href="template/xhtml/styles.css" title="Style">
<html>
<head><title>VM PAGE</title></head>
<body>
<form>
  <table>
    #tag( TextField "label='Username'" "name='user'" )<br>
    #tag( TextField "label='Email'" "name='email'" )<br>
  </table>
</form>
</body>
</html>

simple

simple仅提供HTML标签而不包含附加功能(与struts类似). 该主题只考虑底层结构, 可以像xhml那样复用以增加额外的功能或行为. 你可以很容易的扩展该主题来创建你自己的主题, 以便建立更复杂的页面来满足要求.
使用已定义的主题simple

<%@ taglib uri="webwork" prefix="ui" %>
<link rel ="stylesheet" type="text/css" href="template/xhtml/styles.css" title="Style">
<html>
<head><title>JSP PAGE</title></head>
<body>
  <form>
	<ui:label name="'userlabel'" label="'user" theme="'simple'"/>
                <ui:textfield name="'user'" theme="'simple'"/>

	<ui:label name="'emaillabel'" label="'user" theme="'simple'"/>
                <ui:textfield name="'email'" theme="'simple'"/>
  </form>
</body>
</html>

<link rel ="stylesheet" type="text/css" href="template/xhtml/styles.css" title="Style">
<html>
<head><title>VM PAGE</title></head>
<body>
  <form>
#tag( Label  "name='userlabel'" "label='user'" "theme='simple'" )
#tag( TextField  "name='user'" "theme='simple'" )<br>

#tag( Label  "name='emaillabel'" "label='email'" "theme='simple'" )
#tag( TextField  "name='email'" "theme='simple'" )<br>
  </form>
</body>
</html>

创建你自己的主题

创建主题非常简单, 并能在创建复杂UI页面时帮助你节省时间, 最小化代码. 在继续之前推荐你理解WebWork的模版系统(参见模版). 使用一个模版需要下列步骤.

定义主题的名字并在/template目录下创建一个子目录. 子目录的名字应当和你在UI标签theme属性中指定的值相同.
```
/template/myTheme
```
```
<ui:textfield label="'foo'" name="'bar'" theme="'myTheme'" />
```
为每一个想使用UI标签创建一个velocity模版. 例如, 如果表单中只有textfield没有其他控件, 你的子目录下只需要一个text.vm模版. 注意: 如果你创建一个text.vm并用parse标签引用其他模版, 你必须确保这些模版已经定义好了(例如, controlheader.vm).
如果想把新的主题作为缺省主题, 从而不需要在UI标签中指定theme属性, 这需要修改webwork.properties中的webwork.ui.theme. 否则, 你只能在所有UI标签中指定theme属性.

把xhtml的内容复制到新的目录中是一个好的开始. 这样, 你可以修改模版, 并仍然可以把原始内容作为参考点.