Source

webwork / docs / wikidocs / Themes.html

<html>
    <head>
        <title>WebWork 2 : Themes</title>
	    <link rel="stylesheet" href="styles/site.css" type="text/css" />
        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">	    
    </head>

    <body>
	    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
		    <tr>
			    <td valign="top" class="pagebody">
				    <div class="pageheader">
					    <span class="pagetitle">
                            WebWork 2 : Themes
                                                    </span>
				    </div>
				    <div class="pagesubheading">
					    This page last changed on Jun 16, 2004 by <font color="#0050B2">casey</font>.
				    </div>

				    <p class="paragraph">A Theme is a set of <a href="templates.html" title="Templates">templates</a> used to customize web page development with UI tags.  They provide a powerful mechanism to help web developers spice up the UI with a mixture of styles (colors, fonts, etc).  For example, you may want half your form textfields to have a blue background and half a white background.   A couple of notes:</p><ul class="star">
<li> Webwork comes with 2 pre-defined themes; <a href="#Themes-simple" title="simple on Themes">#simple</a> and <a href="#Themes-xhtml" title="xhtml on Themes">#xhtml</a> (default).  The default location webwork looks for themes in your web application is <tt class="monospaced">/template</tt>.  The default theme is <tt class="monospaced">xhtml</tt>.  Default, meaning that it will be used if you don&#039;t specify a theme attribute in your UI tag.  <ins class="inserted">Note:</ins> The default values can be overridden in your <a href="webwork.properties.html" title="webwork.properties">webwork.properties</a> file with <tt class="monospaced">webwork.ui.theme=</tt>  and <tt class="monospaced">webwork.ui.templateDir=</tt>.</li>
</ul>
<ul class="star">
<li> <a href="#Themes-custom" title="custom on Themes">Custom themes</a> can also be created to tailor your own needs.  We recommend you consult the pre-defined templates as a starting point before you create your own.</li>
</ul>
<ul class="star">
<li> Every time a UI tag is used, the tag is rendered into html by referencing a <a href="templates.html" title="Templates">template</a>.  So they play a key role in how fields look and are positioned in a page.  <ins class="inserted">Note:</ins> webwork uses only velocity templates (*.vm) to render both velocity and webwork tags, while ww1 defined templates in both jsp and vm.</li>
</ul><br/>
<ins class="inserted">Note:</ins> Before moving forward, it is recommended that you review how the webwork template system works.  (see <a href="Templates.html" title="Templates">Templates</a>)<p class="paragraph"><h3 class="heading3"><a name="Themes-xhtml%3Caname%3D%22Themesxhtml%22%3E%3C%2Fa%3E">  xhtml<a name="Themes-xhtml"></a></a></h3></p><tt class="monospaced">xhtml</tt> 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, <tt class="monospaced">textfield</tt>, and show the proper way to write your views with the xhtml theme.<p class="paragraph">As you may already know, the default UI template used for the textfield tag is text.vm located under the directory /template/xhtml.</p><div class="code"><div class="codeContent">
<pre>#&#42;&#10;   &#45;&#45; text.vm&#10;&#42;#&#10;## notice the re&#45;use of the simple theme template text.vm&#10;#parse(<span class="java&#45;quote">&quot;/template/xhtml/controlheader.vm&quot;</span>)&#10;#parse(<span class="java&#45;quote">&quot;/template/simple/text.vm&quot;</span>)&#10;#parse(<span class="java&#45;quote">&quot;/template/xhtml/controlfooter.vm&quot;</span>)</pre>
</div></div><br/>
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.<br/>

<div class="code"><div class="codeContent">
<pre>#&#42;&#10;   &#45;&#45; controlheader.vm&#10;&#42;#&#10;## Only show message <span class="java&#45;keyword">if</span> errors are available.&#10;## This will be done <span class="java&#45;keyword">if</span> ActionSupport is used.&#10;&#10;#<span class="java&#45;keyword">if</span>( $fieldErrors.get($parameters.name) )&#10;  #set ($hasFieldErrors = $fieldErrors.get($parameters.name))&#10;  #foreach ($error in $fieldErrors.get($parameters.name))&#10;    &lt;tr&gt;&#10;        #<span class="java&#45;keyword">if</span> ($parameters.labelposition == &#039;top&#039;)&#10;            &lt;td align=<span class="java&#45;quote">&quot;left&quot;</span> valign=<span class="java&#45;quote">&quot;top&quot;</span> colspan=<span class="java&#45;quote">&quot;2&quot;</span>&gt;&#10;        #<span class="java&#45;keyword">else</span>&#10;            &lt;td align=<span class="java&#45;quote">&quot;center&quot;</span> valign=<span class="java&#45;quote">&quot;top&quot;</span> colspan=<span class="java&#45;quote">&quot;2&quot;</span>&gt;&#10;        #end&#10;            &lt;span class=<span class="java&#45;quote">&quot;errorMessage&quot;</span>&gt;$&#33;webwork.htmlEncode($error)&lt;/span&gt;&#10;            &lt;/td&gt;&#10;    &lt;/tr&gt;&#10;  #end&#10;#end&#10;&#10;## Provides alignment behavior with table tags&#10;## <span class="java&#45;keyword">if</span> the label position is top,&#10;## then give the label it&#039;s own row in the table&#10;## otherwise, display the label to the left on same row&#10;&#10;&lt;tr&gt;&#10;    #<span class="java&#45;keyword">if</span> ($parameters.labelposition == &#039;top&#039;)&#10;        &lt;td align=<span class="java&#45;quote">&quot;left&quot;</span> valign=<span class="java&#45;quote">&quot;top&quot;</span> colspan=<span class="java&#45;quote">&quot;2&quot;</span>&gt;&#10;    #<span class="java&#45;keyword">else</span>&#10;        &lt;td align=<span class="java&#45;quote">&quot;right&quot;</span> valign=<span class="java&#45;quote">&quot;top&quot;</span>&gt;&#10;    #end&#10;&#10;        #<span class="java&#45;keyword">if</span> ($hasFieldErrors)&#10;            &lt;span class=<span class="java&#45;quote">&quot;errorLabel&quot;</span>&gt;&#10;        #<span class="java&#45;keyword">else</span>&#10;            &lt;span class=<span class="java&#45;quote">&quot;label&quot;</span>&gt;&#10;        #end&#10;&#10;## If you want to mark required form fields with an asterisk, &#10;## you can set the required attribute&#10;## Ex. &lt;ui:textfield label=<span class="java&#45;quote">&quot;&#039;mylabel&#039;&quot;</span> name=<span class="java&#45;quote">&quot;&#039;myname&#039;&quot;</span> required=<span class="java&#45;quote">&quot;&#039;<span class="java&#45;keyword">true</span>&#039;&quot;</span> /&gt; &#10;        #<span class="java&#45;keyword">if</span> ($parameters.label)&#10;            #<span class="java&#45;keyword">if</span> ($parameters.required) &lt;span class=<span class="java&#45;quote">&quot;required&quot;</span>&gt;&#42;&lt;/span&gt; #end &#10;               $&#33;webwork.htmlEncode($parameters.label):&#10;        #end&#10;            &lt;/span&gt;&#10;        &lt;/td&gt;&#10;&#10;## add the extra row&#10;#<span class="java&#45;keyword">if</span> ($parameters.labelposition == &#039;top&#039;)&#10;&lt;/tr&gt;&#10;&lt;tr&gt;&#10;#end&#10;    &lt;td&gt;</pre>
</div></div><br/>
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.
<div class="code"><div class="codeContent">
<pre>#&#42;&#10;  &#45;&#45; text.vm&#10;  &#45;&#45;&#10;  &#45;&#45; Required Parameters:&#10;  &#45;&#45;   &#42; label      &#45; The description that will be used to identfy the control.&#10;  &#45;&#45;   &#42; name       &#45; The name of the attribute to put and pull the result from.&#10;  &#45;&#45;                  Equates to the NAME parameter of the HTML INPUT tag.&#10;  &#45;&#45;&#10;  &#45;&#45; Optional Parameters:&#10;  &#45;&#45;   &#42; labelposition   &#45; determines were the label will be place in relation&#10;  &#45;&#45;                       to the control.  Default is to the left of the control.&#10;  &#45;&#45;   &#42; size       &#45; SIZE parameter of the HTML INPUT tag.&#10;  &#45;&#45;   &#42; maxlength  &#45; MAXLENGTH parameter of the HTML INPUT tag.&#10;  &#45;&#45;   &#42; disabled   &#45; DISABLED parameter of the HTML INPUT tag.&#10;  &#45;&#45;   &#42; readonly   &#45; READONLY parameter of the HTML INPUT tag.&#10;  &#45;&#45;   &#42; onkeyup    &#45; onkeyup parameter of the HTML INPUT tag.&#10;  &#45;&#45;   &#42; tabindex  &#45; tabindex parameter of the HTML INPUT tag.&#10;  &#45;&#45;   &#42; onchange  &#45; onkeyup parameter of the HTML INPUT tag.&#10;  &#45;&#45;&#10;    &#42;#&#10;&lt;input type=<span class="java&#45;quote">&quot;text&quot;</span>&#10;                                   name=<span class="java&#45;quote">&quot;$&#33;webwork.htmlEncode($parameters.name)&quot;</span>&#10;#<span class="java&#45;keyword">if</span> ($parameters.size)             size=<span class="java&#45;quote">&quot;$&#33;webwork.htmlEncode($parameters.size)&quot;</span>            #end&#10;#<span class="java&#45;keyword">if</span> ($parameters.maxlength)        maxlength=<span class="java&#45;quote">&quot;$&#33;webwork.htmlEncode($parameters.maxlength)&quot;</span>  #end&#10;#<span class="java&#45;keyword">if</span> ($parameters.nameValue)        value=<span class="java&#45;quote">&quot;$&#33;webwork.htmlEncode($parameters.nameValue)&quot;</span>      #end&#10;#<span class="java&#45;keyword">if</span> ($parameters.disabled == <span class="java&#45;keyword">true</span>) disabled=<span class="java&#45;quote">&quot;disabled&quot;</span>                                      #end&#10;#<span class="java&#45;keyword">if</span> ($parameters.readonly)         readonly=<span class="java&#45;quote">&quot;readonly&quot;</span>                                      #end&#10;#<span class="java&#45;keyword">if</span> ($parameters.onkeyup)          onkeyup=<span class="java&#45;quote">&quot;$&#33;webwork.htmlEncode($parameters.onkeyup)&quot;</span>      #end&#10;#<span class="java&#45;keyword">if</span> ($parameters.tabindex)         tabindex=<span class="java&#45;quote">&quot;$&#33;webwork.htmlEncode($parameters.tabindex)&quot;</span>    #end&#10;#<span class="java&#45;keyword">if</span> ($parameters.onchange)         onchange=<span class="java&#45;quote">&quot;$&#33;webwork.htmlEncode($parameters.onchange)&quot;</span>    #end&#10;#<span class="java&#45;keyword">if</span> ($parameters.id)               id=<span class="java&#45;quote">&quot;$&#33;webwork.htmlEncode($parameters.id)&quot;</span>                #end&#10;#<span class="java&#45;keyword">if</span> ($parameters.cssClass)         class=<span class="java&#45;quote">&quot;$&#33;webwork.htmlEncode($parameters.cssClass)&quot;</span>       #end&#10;#<span class="java&#45;keyword">if</span> ($parameters.cssStyle)         style=<span class="java&#45;quote">&quot;$&#33;webwork.htmlEncode($parameters.cssStyle)&quot;</span>       #end&#10;/&gt;</pre>
</div></div>&#160;<br/>
And finally, the controlfooter.vm is parsed to close up the td and tr tags that were previously opened in controlheader.vm
<div class="code"><div class="codeContent">
<pre>#&#42;&#10;   &#45;&#45; controlheader.vm&#10;&#42;#&#10;&#10;  &lt;/td&gt;&#10;&lt;/tr&gt;</pre>
</div></div><p class="paragraph">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.
<div class="code"><div class="codeContent">
<pre>&lt;&#37;&#64; taglib uri=<span class="java&#45;quote">&quot;webwork&quot;</span> prefix=<span class="java&#45;quote">&quot;ui&quot;</span> &#37;&gt;&#10;&lt;link rel =<span class="java&#45;quote">&quot;stylesheet&quot;</span> type=<span class="java&#45;quote">&quot;text/css&quot;</span> href=<span class="java&#45;quote">&quot;template/xhtml/styles.css&quot;</span> title=<span class="java&#45;quote">&quot;Style&quot;</span>&gt;&#10;&lt;html&gt;&#10;&lt;head&gt;&lt;title&gt;JSP PAGE&lt;/title&gt;&lt;/head&gt;&#10;&lt;body&gt;&#10;&lt;form&gt;&#10;  &lt;table&gt;&#10;	&lt;&#33;&#45;&#45; we can set the required attribute to <span class="java&#45;keyword">true</span>&#160;<span class="java&#45;keyword">if</span> we want to &#10;	     display and asterisk next to required form fields&#10;	 &#45;&#45;&gt;&#10;&#10;	&lt;ui:textfield label=<span class="java&#45;quote">&quot;&#039;Username&#039;&quot;</span> required=<span class="java&#45;quote">&quot;&#039;<span class="java&#45;keyword">true</span>&#039;&quot;</span> name=<span class="java&#45;quote">&quot;&#039;user&#039;&quot;</span> /&gt; &#10;	&lt;ui:textfield label=<span class="java&#45;quote">&quot;&#039;Email&#039;&quot;</span> name=<span class="java&#45;quote">&quot;&#039;email&#039;&quot;</span>/&gt; &#10;  &lt;/table&gt;&#10;&lt;/form&gt;&#10;&lt;/body&gt;&#10;&lt;/html&gt;</pre>
</div></div></p><div class="code"><div class="codeContent">
<pre>&lt;link rel =<span class="java&#45;quote">&quot;stylesheet&quot;</span> type=<span class="java&#45;quote">&quot;text/css&quot;</span> href=<span class="java&#45;quote">&quot;template/xhtml/styles.css&quot;</span> title=<span class="java&#45;quote">&quot;Style&quot;</span>&gt;&#10;&lt;html&gt;&#10;&lt;head&gt;&lt;title&gt;VM PAGE&lt;/title&gt;&lt;/head&gt;&#10;&lt;body&gt;&#10;&lt;form&gt;&#10;  &lt;table&gt;&#10;    #tag( TextField <span class="java&#45;quote">&quot;label=&#039;Username&#039;&quot;</span>&#160;<span class="java&#45;quote">&quot;name=&#039;user&#039;&quot;</span> )&lt;br&gt;&#10;    #tag( TextField <span class="java&#45;quote">&quot;label=&#039;Email&#039;&quot;</span>&#160;<span class="java&#45;quote">&quot;name=&#039;email&#039;&quot;</span> )&lt;br&gt;&#10;  &lt;/table&gt;&#10;&lt;/form&gt;&#10;&lt;/body&gt;&#10;&lt;/html&gt;</pre>
</div></div><p class="paragraph"><h3 class="heading3"><a name="Themes-simple%3Caname%3D%22Themessimple%22%3E%3C%2Fa%3E">  simple<a name="Themes-simple"></a></a></h3></p>The <tt class="monospaced">simple</tt> theme provides no additional functionality from HTML tags (similiar to struts).  This theme is considered the low end of the structure and can be re-used (extended) like xhtml to add additional functionality or behavior.  You can easily create your own theme and extend this one to create complex pages that fit your own needs.<br/>
To use the pre-defined theme <tt class="monospaced">simple</tt>
<div class="preformatted"><div class="preformattedContent">
<pre>&lt;&#37;&#64; taglib uri=&quot;webwork&quot; prefix=&quot;ui&quot; &#37;&gt;&#10;&lt;link rel =&quot;stylesheet&quot; type=&quot;text/css&quot; href=&quot;template/xhtml/styles.css&quot; title=&quot;Style&quot;&gt;&#10;&lt;html&gt;&#10;&lt;head&gt;&lt;title&gt;JSP PAGE&lt;/title&gt;&lt;/head&gt;&#10;&lt;body&gt;&#10;  &lt;form&gt;&#10;	&lt;ui:label name=&quot;&#039;userlabel&#039;&quot; label=&quot;&#039;user&quot; theme=&quot;&#039;simple&#039;&quot;/&gt;&#10;                &lt;ui:textfield name=&quot;&#039;user&#039;&quot; theme=&quot;&#039;simple&#039;&quot;/&gt;&#10;&#10;	&lt;ui:label name=&quot;&#039;emaillabel&#039;&quot; label=&quot;&#039;user&quot; theme=&quot;&#039;simple&#039;&quot;/&gt;&#10;                &lt;ui:textfield name=&quot;&#039;email&#039;&quot; theme=&quot;&#039;simple&#039;&quot;/&gt;&#10;  &lt;/form&gt;&#10;&lt;/body&gt;&#10;&lt;/html&gt;</pre>
</div></div><br/>

<div class="preformatted"><div class="preformattedContent">
<pre>&lt;link rel =&quot;stylesheet&quot; type=&quot;text/css&quot; href=&quot;template/xhtml/styles.css&quot; title=&quot;Style&quot;&gt;&#10;&lt;html&gt;&#10;&lt;head&gt;&lt;title&gt;VM PAGE&lt;/title&gt;&lt;/head&gt;&#10;&lt;body&gt;&#10;  &lt;form&gt;&#10;#tag( Label  &quot;name=&#039;userlabel&#039;&quot; &quot;label=&#039;user&#039;&quot; &quot;theme=&#039;simple&#039;&quot; )&#10;#tag( TextField  &quot;name=&#039;user&#039;&quot; &quot;theme=&#039;simple&#039;&quot; )&lt;br&gt;&#10;&#10;#tag( Label  &quot;name=&#039;emaillabel&#039;&quot; &quot;label=&#039;email&#039;&quot; &quot;theme=&#039;simple&#039;&quot; )&#10;#tag( TextField  &quot;name=&#039;email&#039;&quot; &quot;theme=&#039;simple&#039;&quot; )&lt;br&gt;&#10;  &lt;/form&gt;&#10;&lt;/body&gt;&#10;&lt;/html&gt;</pre>
</div></div><p class="paragraph"><h3 class="heading3"><a name="Themes-Creatingyourowntheme%3Caname%3D%22Themescustom%22%3E%3C%2Fa%3E">  Creating your own theme <a name="Themes-custom"></a></a></h3></p>Creating  themes is quite simple and can save valuable time enabling you to minimize UI code when it comes to creating complex UI pages.  It is recommended you understand webwork templates before you continue (see <a href="Templates.html" title="Templates">Templates</a>).  The steps required to use a theme.
<ol>
<li> Define a name for your theme by creating a subdirectory under /template directory.  The name of the subdirectory you create will be the same as the value you specify in your UI tag theme attribute.
<div class="code"><div class="codeContent">
<pre>/template/myTheme</pre>
</div></div>
<div class="code"><div class="codeContent">
<pre>&lt;ui:textfield label=<span class="java&#45;quote">&quot;&#039;foo&#039;&quot;</span> name=<span class="java&#45;quote">&quot;&#039;bar&#039;&quot;</span> theme=<span class="java&#45;quote">&quot;&#039;myTheme&#039;&quot;</span> /&gt;</pre>
</div></div>
</li>
<li> Create a velocity template for every UI tag that you want to use with your theme.  For example, if you have forms with only textfields and nothing else, then all you need in your subdirectory is a text.vm template.  Note: if you create a text.vm and reference another template with the parse tag, then you must make sure these templates are defined as well(ex. controlheader.vm).</li>
<li> If you want your new theme to be the default so you don&#039;t have to specify the theme attribute every time in the UI tag, then modify the webwork.ui.theme value in your webwork.properties file.  Otherwise, you can just specify the theme attribute in all your UI tags.</li>
</ol><p class="paragraph">As a good starting point, a good idea is to copy the contents of xhtml into a new subdirectory.  Therefore, you can modify the templates and still refer back to the originals as a reference point.</p>

				    
                    			    </td>
		    </tr>
	    </table>
	    <table border="0" cellpadding="0" cellspacing="0" width="100%">
			<tr>
				<td height="12" background="border/border_bottom.gif"><img src="border/spacer.gif" width="1" height="1" border="0"/></td>
			</tr>
		    <tr>
			    <td align="center"><font color="grey">Document generated by Confluence on Oct 15, 2004 20:55</font></td>
		    </tr>
	    </table>
    </body>
</html>