============
xhtml
xhtml
comes configured as the default theme for Webwork. It extends the simple theme providing built in functionality for error reporting, table positioning, and labeling. Lets look at one of the most common UI tags used, textfield
, and show the proper way to write your views with the xhtml theme.
As you may already know, the default UI template used for the textfield tag is text.vm located under the directory /template/xhtml.
Code Block |
---|
#*
-- 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")
|
When this template is loaded, it will first parse and render the /template/xhtml/controlheader.vm. Within controlheader.vm you will notice functionlity for error reporting, labeling and table positioning. If ActionSupport is returning with some errors, they are rendered into html using this this template. Also you will notice how it grabs the parameter.label value and positions it with the textfield using the table elements tr and 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>
The next template being parsed in /template/xhtml/text.vm is /template/simple/text.vm. Here you see the actual html input text tag being rendered and how the parameters are passed in.
...
#*
-- 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
/>
And finally, the controlfooter.vm is parsed to close up the td and tr tags that were previously opened in controlheader.vm
...
#*
-- controlheader.vm
*#
</td>
</tr>
In our view, since the tr and td elements are already created for us, we can simply wrap them with table elements. For the sake of learning, we will just use normal html table objects, but feel free to look into how the table.vm tag gets rendered and possibly use that.
...
<%@ 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>
The xhtml provides all the basics that the simple theme provides and adds several features.
- Standard two-column table layout for the HTML Struts Tags (form, textfield, select, and so forth)
- Labels for each of the HTML Struts Tags on the left hand side (or top, depending on the
labelposition
attribute) - Validation and error reporting
- Pure JavaScript Client Side Validation using 100% JavaScript on the browser
Wrapping the Simple Theme
The xhtml theme uses the "wrapping" technique described by Extending Themes. Let's look at how the HTML tags are wrapped by a standard header and footer. For example, in the text.ftl
template, the controlheader.ftl
and controlfooter.ftl
templates are wrapped around the simple template.
...
The
controlheader.ftl
is referenced using ${parameters.theme} so that the code can be reused by the ajax theme.
XHTML Theme Header
Now let's look at the controlheader.ftl
and controlheader-core.ftl
. Again, these are split up for easy re-use with the ajax theme) contents:
...
The header used by the HTML tags in the xhtml theme is complicated. However, a close look reveals that the logic produces two behaviors: either a two-column format or a two-row format. Generally the two-column approach is what we want, so that is the default option. To use the two-row approach, change the labelposition
parameter to top
.
...
The fieldErrors
, usually caused by Validation, are printed out as a row above the HTML form element. Some people prefer that the errors display elsewhere, such as in a third column. If you wish to place these elsehwere, overriding the headers is easy, allowing you to continue to use the other features provided by this theme. See Template Loading for more information on how to do this.
...
XHTML Theme Footer
The primary objective of controlfooter.ftl
is to close the table. But, before the table closes, the template checks for an after
parameter.
...
While "after" isn't an attribute supported by any of the Struts Tags, if you are using FreeMarker Tags, Velocity Tags, or the param tag in any template language, you can add an after
parameter to place any content you like after the simple theme template renders. The after
attribute makes it easier to fine-tune HTML forms for your specific environment.
Special Interest
Two xhtml templates of special interest are head
and form
.
head template
The xhtml head template extends the simple head template and provides an additional CSS that helps render the xhtml theme form elements.
...
The head template imports a style sheet.
...
form template
The xhtml form template sets up the wrapping table around all the other xhtml theme form elements. In addition to creating this wrapping table, the opening and closing templates also, if the validate
parameter is set to true, enable Pure JavaScript Client Side Validation.
...
The closing template, form-close.ftl*
:
...