net.sourceforge.stripes.tag
Class InputOptionsCollectionTag

java.lang.Object
  extended by net.sourceforge.stripes.tag.StripesTagSupport
      extended by net.sourceforge.stripes.tag.HtmlTagSupport
          extended by net.sourceforge.stripes.tag.InputOptionsCollectionTag
All Implemented Interfaces:
DynamicAttributes, JspTag, Tag
Direct Known Subclasses:
InputOptionsEnumerationTag, InputOptionsMapTag

public class InputOptionsCollectionTag
extends HtmlTagSupport
implements Tag

Writes a set of <option value="foo">bar</option> tags to the page based on the contents of a Collection. Each element in the collection is represented by a single option tag on the page. Uses the label and value attributes on the tag to name the properties of the objects in the Collection that should be used to generate the body of the HTML option tag and the value attribute of the HTML option tag respectively.

E.g. a tag declaration that looks like:

<stripes:options-collection collection="${cats} value="catId" label="name"/>

would cause the container to look for a Collection called "cats" across the various JSP scopes and set it on the tag. The tag would then proceed to iterate through that collection calling getCatId() and getName() on each cat to produce HTML option tags.

The tag will attempt to localize the labels attributes of the option tags that are generated. To do this it will look up labels in the field resource bundle using:

For example for a class com.myco.Gender supplied to the options-collection tag with label="description" and value="key", when rendering for an instance Gender[key="M", description="Male"] the following localized properties will be looked for:

If no localized label can be found then the value of the label property will be used.

Optionally, the group attribute may be used to generate <optgroup> tags. The value of this attribute is used to retrieve the corresponding property on each object of the collection. A new optgroup will be created each time the value changes.

The rendered group may be localized by specifying one of the following properties:

All other attributes on the tag (other than collection, value, label and group) are passed directly through to the InputOptionTag which is used to generate the individual HTML options tags. As a result the InputOptionsCollectionTag will exhibit the same re-population/selection behaviour as the regular options tag.

Since the tag has no use for one it does not allow a body.

Author:
Tim Fennell

Nested Class Summary
static class InputOptionsCollectionTag.Entry
          A little container class that holds an entry in the collection of items being used to generate the options, along with the determined label and value (either from a property, or a localized value).
 
Field Summary
 
Fields inherited from class net.sourceforge.stripes.tag.StripesTagSupport
pageContext, parentTag
 
Fields inherited from interface javax.servlet.jsp.tagext.Tag
EVAL_BODY_INCLUDE, EVAL_PAGE, SKIP_BODY, SKIP_PAGE
 
Constructor Summary
InputOptionsCollectionTag()
           
 
Method Summary
protected  void addEntry(Object item, Object label, Object value)
          Adds an entry to the internal list of items being used to generate options.
protected  void addEntry(Object item, Object label, Object value, Object group)
          Adds an entry to the internal list of items being used to generate options.
 int doEndTag()
          Optionally sorts the assembled entries and then renders them into a series of option tags using an instance of InputOptionTag to do the rendering work.
 int doStartTag()
          Iterates through the collection and generates the list of Entry objects that can then be sorted and rendered into options.
 Object getCollection()
          Returns the value set by setCollection(Object).
 String getGroup()
          Gets the property name set with setGroup().
 String getLabel()
          Gets the property name set with setLabel().
 String getSort()
          Gets the comma separated list of properties by which the collection is sorted.
 String getValue()
          Returns the property name set with setValue().
 void setCollection(Object in)
          Sets the collection that will be used to generate options.
 void setGroup(String group)
          Sets the name of the property that will be fetched on each bean in the collection in order to generate optgroups.
 void setLabel(String label)
          Sets the name of the property that will be fetched on each bean in the collection in order to generate the body of each option (i.e.
 void setSort(String sort)
          Sets a comma separated list of properties by which the beans in the collection will be sorted prior to rendering them as options.
 void setValue(String value)
          Sets the name of the property that will be fetched on each bean in the collection in order to generate the value attribute of each option.
 
Methods inherited from class net.sourceforge.stripes.tag.HtmlTagSupport
evaluateExpression, get, getAccesskey, getAttributes, getBodyContent, getBodyContentAsString, getCssClass, getDir, getId, getLang, getOnblur, getOnchange, getOnclick, getOndblclick, getOnfocus, getOnkeydown, getOnkeypress, getOnkeyup, getOnmousedown, getOnmousemove, getOnmouseout, getOnmouseover, getOnmouseup, getOnselect, getStyle, getTabindex, getTitle, release, set, setAccesskey, setBodyContent, setClass, setCssClass, setDir, setDynamicAttribute, setId, setLang, setOnblur, setOnchange, setOnclick, setOndblclick, setOnfocus, setOnkeydown, setOnkeypress, setOnkeyup, setOnmousedown, setOnmousemove, setOnmouseout, setOnmouseover, setOnmouseup, setOnselect, setStyle, setTabindex, setTitle, toString, writeAttributes, writeCloseTag, writeOpenTag, writeSingletonTag
 
Methods inherited from class net.sourceforge.stripes.tag.StripesTagSupport
getActionBeanType, getActionBeanUrl, getPageContext, getParent, getParentTag, getTagStack, popPageContextAttributes, pushPageContextAttributes, setPageContext, setParent
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface javax.servlet.jsp.tagext.Tag
getParent, release, setPageContext, setParent
 

Constructor Detail

InputOptionsCollectionTag

public InputOptionsCollectionTag()
Method Detail

setCollection

public void setCollection(Object in)

Sets the collection that will be used to generate options. In this case the term collection is used in the loosest possible sense - it means either a bonafide instance of Collection, or an implementation of Iterable other than a Collection, or an array of Objects or primitives.

In the case of any input which is not an Collection it is converted to a Collection before storing it.

Parameters:
in - either a Collection, an Iterable or an Array

getCollection

public Object getCollection()
Returns the value set by setCollection(Object). In the case that a Collection was supplied, the same collection will be returned. In all other cases a new collection created to hold the supplied elements will be returned.


setValue

public void setValue(String value)
Sets the name of the property that will be fetched on each bean in the collection in order to generate the value attribute of each option.

Parameters:
value - the name of the attribute

getValue

public String getValue()
Returns the property name set with setValue().


setLabel

public void setLabel(String label)
Sets the name of the property that will be fetched on each bean in the collection in order to generate the body of each option (i.e. what is seen by the user).

Parameters:
label - the name of the attribute

getLabel

public String getLabel()
Gets the property name set with setLabel().


setSort

public void setSort(String sort)
Sets a comma separated list of properties by which the beans in the collection will be sorted prior to rendering them as options. 'label' and 'value' are special case properties that are used to indicate the generated label and value of the option.

Parameters:
sort - the name of the attribute(s) used to sort the collection of options

getSort

public String getSort()
Gets the comma separated list of properties by which the collection is sorted.


addEntry

protected void addEntry(Object item,
                        Object label,
                        Object value)
Adds an entry to the internal list of items being used to generate options.

Parameters:
item - the object represented by the option
label - the actual label for the option
value - the actual value for the option

addEntry

protected void addEntry(Object item,
                        Object label,
                        Object value,
                        Object group)
Adds an entry to the internal list of items being used to generate options.

Parameters:
item - the object represented by the option
label - the actual label for the option
value - the actual value for the option
group - the value to be used for optgroups

doStartTag

public int doStartTag()
               throws JspException
Iterates through the collection and generates the list of Entry objects that can then be sorted and rendered into options. It is assumed that each element in the collection has non-null values for the properties specified for generating the label and value.

Specified by:
doStartTag in interface Tag
Specified by:
doStartTag in class StripesTagSupport
Returns:
SKIP_BODY in all cases
Throws:
JspException - if either the label or value attributes specify properties that are not present on the beans in the collection

doEndTag

public int doEndTag()
             throws JspException
Optionally sorts the assembled entries and then renders them into a series of option tags using an instance of InputOptionTag to do the rendering work.

Specified by:
doEndTag in interface Tag
Specified by:
doEndTag in class StripesTagSupport
Returns:
EVAL_PAGE in all cases.
Throws:
JspException

setGroup

public void setGroup(String group)
Sets the name of the property that will be fetched on each bean in the collection in order to generate optgroups. A new optgroup will be created each time the value changes.

Parameters:
group - the name of the group attribute

getGroup

public String getGroup()
Gets the property name set with setGroup().



? Copyright 2005-2006, Stripes Development Team.