nerdErg

nerdErg | software | Archives | nerdErg Form Taglib

1. nerdErg Form Taglib V2.0

Bringing Readability, Convention, Consistency and CSS to form design. Updated to Version 2.0.

It gives you:

  • Labels and structure without cluttering up your GSP form

  • Standard error marking and handling without cluttering up your GSP form

  • Compatibility with browsers

  • Javascript assistance with pickers and choosers where appropriate using jQuery

  • CSS themeable rendering of forms

Active form inputs in this archived page ma not have the full functionality of the plugin due to it being an archive and not having the required javascript embedded.
usage.html
<nerderg:formfield label='Select one' field='age' bean='${myCommand}'>
  <g:select name="age" from="${18..65}" value="${myCommand.age}"/>
</nerderg:formfield>
<nerderg:inputfield label='First name' field='firstname' bean='${myCommand}'/>
<nerderg:datefield label='Date of birth' field='dob' bean='${myCommand}' format='dd/MM/yyyy'/>
<nerderg:timefield label='Time of accident' field='toa' bean='${myCommand}' format='hh:mm a'/>
<nerderg:datetimefield label='Start' field='eventStart' bean='${myCommand}' format='dd/MM/yyyy hh:mm'/>
<nerderg:checkboxgroup label='Options' field='selOptions' from='${allOptions}' bean='${myCommand}'/>
<nerderg:asJSArray var="options" items='["opt1", "opt2", "opt3"]'/>

1.1. General attributes

  • label: the Label you wish to display for the field. if not set no label is displayed. Labels can have embedded \n chars that are translated to <br> to force a new line in a label

  • delim: the Delimiter char displayed after a label. By default a ":" is displayed after the label.

  • bean: the bean the field is contained in. If this bean has an errors property then the errors are highlighted.

  • field: the beans field to display

  • name: the name of the field. If no id attribute is set the id is also set to this value

  • table: if set true then a table is used to layout the label and value. If false CSS is used for layout. Default is false, use true for IE6 compatibility

  • value: if bean has not been set then this can be used to directly set the value for the field.

Notes:

  • You can add any attributes that make sense for an input of the type being used and they’ll be automatically included. Specifying a name attribute for example will override any auto set name. This is useful when you have multiple sets of inputs with the same field name, so you might have name="${index}.firstName"

  • Specifying a size attribute on text inputs is also a good example of an additional attribute.

  • Boolean attributes like disabled, checked and readonly are correctly inserted if the value evaluates to Groovy true and left out completely if the value evaluates to false. So adding an attribute checked="${true}" will insert the attribute checked='checked'. Truth is extended to mean any non zero-length string that !(value ==~ /(?i)false/) so if you have checked='false' then checked will not be inserted.

  • As you’d hope/expect all the values are HTML encoded, and protected from null value errors.

  • The bean attribute can be just a map of values.

1.2. Using it

Install it with grails install-plugin nerderg-form-tags

To get the date picker and time entry functions you need to install some javascript stuff. The plugin includes a standard CSS and Javascript library to get you going, but you need to add some things to your page/layout.

First install the jQuery and the jquery-ui plugins (jquery is installed by default with Grails 2.x)

grails install-plugin jquery
grails install-plugin jquery-ui
you need to specify a theme for jquery-ui to use. The jQuery timeentry and mousewheel plugins are now bundled in nerdErg Form Tags Now edit your layout or page.gsp and add the following to the header section to include the jQuery and nerdergFormTags javascript and CSS.
example.gsp
 <!--
include the javascript libs, css and add the default code to associate the date and time INPUT tags with date
and time pickers from nerdergFormtags.js. Feel free to use your own...
-->
<r:require modules="nerdergFormTags"/>
<!--
set the default display dateFormat and icon for datepicker for the above JS
-->
<g:javascript>
nerdergFormTags.dateImg = "${resource(plugin: 'nerderg-form-tags', dir: 'images/icons', file: 'date.png')}";
nerdergFormTags.dateFormat = "dd/mm/yy";
</g:javascript>

and that’s it! Welcome to clean forms. You can find the example nerdergFormTags application at https://github.com/pmcneil/nerdErgFormTagsTestApp

2. Tags

2.1. <formfield>

formfield.gsp
<nerderg:formfield label='Select one' field='age' bean='${myCommand}'>
<g:select name="age" from="${18..65}" value="${myCommand.age}"/>
</nerderg:formfield>

The above tag will produce something like this (depending on CSS):

output.html
<div class='prop'>
<span class='name'><label for='age'>Select one:</label></span>
<span class='value' title='Select one'>
<select name="age" id="age" >

<option value="18" >18</option>
<option value="19" >19</option>
<option value="20" >20</option>
<option value="21" >21</option>
<option value="22" >22</option>
<option value="23" >23</option>
<option value="24" >24</option>
<option value="25" >25</option>
<option value="26" >26</option>

<option value="27" >27</option>
<option value="28" >28</option>
<option value="29" >29</option>
<option value="30" >30</option>
<option value="31" >31</option>
<option value="32" >32</option>
<option value="33" >33</option>
<option value="34" >34</option>
<option value="35" >35</option>

<option value="36" >36</option>
<option value="37" >37</option>
<option value="38" >38</option>
<option value="39" >39</option>
<option value="40" >40</option>
<option value="41" >41</option>
<option value="42" >42</option>
<option value="43" >43</option>
<option value="44" >44</option>

<option value="45" selected="selected" >45</option>
<option value="46" >46</option>
<option value="47" >47</option>
<option value="48" >48</option>
<option value="49" >49</option>
<option value="50" >50</option>
<option value="51" >51</option>
<option value="52" >52</option>
<option value="53" >53</option>

<option value="54" >54</option>
<option value="55" >55</option>
<option value="56" >56</option>
<option value="57" >57</option>
<option value="58" >58</option>
<option value="59" >59</option>
<option value="60" >60</option>
<option value="61" >61</option>
<option value="62" >62</option>

<option value="63" >63</option>
<option value="64" >64</option>
<option value="65" >65</option>
</select>
</span>
</div>

Tag specific attributes

  • hideValue (since v1.3) - by default the value of a bean supplied to the formfield tag is displayed as text in the value portion of the formfield before the body. To hide the value (not display it) add the hideValue="${true}" attribute

Notes

  • The formfield tag gives you control over the body content and the input. It provides error highlighting if a bean and field are supplied. This can be used just to display information with a label too.

  • The CSS will format it as table cells so that you end up with aligned labels and values. (if you set the table property then it will be a table row).

2.2. <inputfield>

inputfield.gsp
<nerderg:inputfield label='First name' field='firstname' bean='${myCommand}'/>

The above tag will produce something like this (depending on CSS):

output.html
<div class='prop'>

<span class='name'><label for='firstname'>First name:</label></span>
<span class='value' title='First name'><input type='text' name='firstname' value='Peter' id='firstname'/></span>
</div>

Tag specific attributes

  • type - set the input type e.g. password, text. The default type is text unless the field name is "passwd" or "password" in which case it defaults to password. You can set the type to anything you like but I only recommend using this input as textual input.

  • maxlength - override the automatic maxSize → maxlength attribute from the constraints in the bean.

Notes

  • The inputfield tag produces a text input field displaying the value of the bean.field. If the bean has a constraints property with the maxSize set it will automatically include maxlength in the input specification.

for example:

example.gsp
<nerderg:inputfield label='First Name' bean='${formCommand}' field='firstName'/>

where the formCommand bean looks like this:

formCommand.groovy
class FormCommand {
String firstName

    static constraints = {
        firstName(nullable: false, blank: false, maxSize: 10)
    }
}

will produce:

output.html
<div class='prop'>
  <span class='name'><label for='value'>First Name:</label></span>
  <span class='value' title='First Name'>
    <input type='text' name='firstName' value='Peter' id='firstName' maxlength='10'/>
  </span>
</div>

and look something like this:

2.3. <datefield>

datefield.gsp
<nerderg:datefield label='Date of birth' field='dob' bean='${myCommand}' format='dd/MM/yyyy'/>

The above tag will produce something like this (depending on CSS):

output.html
<div class='prop'>
<span class='name'><label for='date'>Result:</label></span>
<span class='value' title='Result'><input type='text' name='date' value='2010-10-28' class='date' size='10' id='date'/></span>
</div>

Tag specific attributes

  • none

Notes

  • You need to include the NerdergTagLib.js library to get a date picker.

  • the field/value can be a Date or String.

  • a string value can be anything parseable by jChronic, like "Tommorrow 2pm"

  • use format to define how the parsed date is displayed

  • if the value is not parseable as a date it will not be formatted and just displayed as is.

2.4. <timefield>

timefield.gsp
<nerderg:timefield label='Time of accident' field='toa' bean='${myCommand}' format='hh:mm a'/>

The above tag will produce something like this (depending on CSS):

output.html
<div class='prop'>
<span class='name'><label for='tob'>Time of accident:</label></span>
<span class='value' title='Time of accident'><input type='text' name='toa' value='02:59 PM' class='time' size='6' id='toa'/></span>
</div>

Tag specific attributes

  • none

Notes

  • You can include the NerdergTagLib.js library to get a time entry helper. You’ll also need the timeentry jQuery plugin.

  • the field/value can be a Date or String.

  • a string value can be anything parseable by jChronic, like "Tommorrow 2pm"

  • use format to define how the parsed date is displayed - however timeentry jquery plugin will standardise that.

  • if the value is not parseable as a date it will not be formatted and just displayed as is.

2.5. <datetimefield>

datetimefield.gsp
<nerderg:datetimefield label='Start' field='eventStart' bean='${myCommand}' format='dd/MM/yyyy hh:mm'/>

The above tag will produce something like this (depending on CSS):

 Try to be accurate
output.html
<div class='prop'>
<span class='name'><label for='date'>Result:</label></span>
<span class='value' title='Result'><input type='text' name='date.date' value='2010-10-28' class='date' size='10' id='date.date'/>&nbsp;<input type='text' name='date.time' value='10:47' class='time' size='7' title='type or use mouse wheel to change' id='date.time'/>Try to be accurate</span>
</div>

Tag specific attributes

  • none

Notes

  • You need to include the NerdergTagLib.js library to get a date picker and time chooser functionality.

  • the field/value can be a Date or String.

  • a string value can be anything parseable by jChronic, like "Tommorrow 2pm"

  • use format to define how the parsed date is displayed

  • if the value is not parseable as a date it will not be formatted and just displayed as is.

2.6. <checkboxgroup>

checkboxgroup.gsp
<nerderg:checkboxgroup label='Options' field='selOptions' from='${allOptions}' bean='${myCommand}'/>

The above tag will produce something like the following (depending on CSS):

  •  opt1
  •  opt2
  •  opt3
output.html
<div class="prop">
  <span class="name"><label for="selOptions">Options:</label></span>
  <span class="value" title="Options">
<ul class="cblist">
<li><input name="selOptions" value="opt1" checked="checked" type="checkbox">&nbsp;opt1</li>
<li><input name="selOptions" value="opt2" checked="checked" type="checkbox">&nbsp;opt2</li>
<li><input name="selOptions" value="opt3" type="checkbox">&nbsp;opt3</li>
</ul>
</span>
</div>

Tag specific attributes

  • none

Notes

  • If not using a backing bean or command object the subset of selected checkboxes can be provided using the value attribute.

2.7. <asJSArray>

asJSArray.gsp
<nerderg:asJSArray var="options" items='["opt1", "opt2", "opt3"]'/>

The above tag generates a javascript tag that makes a javascript array of the given object. So the above would generate something like this:

output.html
<script type='text/javascript'>

options = ["opt1","opt2","opt3"];
</script>

This tag basically encodes any object as JSON, so you can do this too:

asJSArray.gsp
<nerderg:asJSArray var='command' items='${command}'/>

and you’ll end up with something like this:

output.html
<script type='text/javascript'>
command = {"class":"com.nerderg.taglib.FauxCommand","date":null,"options":"[opt1, opt2]","value":"hello world"};
</script>