doc/src/ComponentReference/PropertySelection.html - tapestry3 - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <!-- $Id$ -->
 <html>
 <head>
 <title>PropertySelection</title>
 <link rel="stylesheet" type="text/css" href="Tapestry.css" title="style">
 </head>

 <body>
 <table border="0" cellpadding="0" cellspacing="0" width="100%">
  <tr>
   <td align="left"><A href="PageLink.html"><IMG alt=PageLink src="common-images/prev.png"></a></td>
   <td align="middle"><A href="index.html"><IMG alt=Index src="common-images/home.png"></a></td>
   <td align="right"><A href="Radio.html"><IMG alt=Radio src="common-images/next.png"></a></td>
  <tr>
  <tr>
   <td colspan="3"><hr></td>
  </tr>
  <tr>
   <td colspan="3">
    <table border="0" cellpadding="4" cellspacing="4" width="100%">

 <tr valign="top">
  <td>
   <table>
 	 <tr>
 	  <td><font size="+2"><b>PropertySelection</b></font></td>
 	 </tr>
 	 <tr>
 	  <td>
 		 <A href="../api/org/apache/tapestry/form/PropertySelection.html">
 		 org.apache.tapestry.form.PropertySelection</a>
 		</td>
 	 </tr>
   </table>
  </td>
  <td>
   <table align="right" valign="middle" bgcolor="#c0c0c0" cellspacing="8">
 	 <tr>
 	  <td>Color
 		 <select>
 		  <option selected>Red</option>
 		  <option>Blue</option>
 		  <option>Green</option>
 		 </select>
 		</td>
 	 </tr>
   </table>
  </td>
 </tr>

 <tr valign="center">
  <td colspan="2">&nbsp;</td>
 </tr>

 <tr>
  <td colspan="2">
   <P>
   <b>Description</b>
 	<br>
   Creates form elements that allow a property of
   an object to be set from a drop-down list.</P>
   <P>
   Uses a
   <A href="../api/org/apache/tapestry/form/IPropertySelectionModel.html">model</a>
   to map between Java values that will be assigned, and textual labels
   that will appear in the HTML response.
   </P>
 	<p>
   There is a range property selection models you can use, including
   <A href="../api/org/apache/tapestry/form/StringPropertySelectionModel.html">
   <tt>StringPropertySelectionModel</tt></a>
   and
   <A href="../api/org/apache/tapestry/form/EnumPropertySelectionModel.html">
   <tt>EnumPropertySelectionModel</tt></a>. You can also create your own model,
   as illustrated in the Examples below.
 	<p>
 	Note that complex value Objects need to properly implement the
   <tt>Object.equals()</tt>
   method if the correct initial item is to be displayed.
   <P>
   Informal parameters are applied to the &lt;select&gt; tag.&nbsp;
   To have greater control over the &lt;option&gt; tags, you must use the
 	<A href="Select.html">Select</a>&nbsp;and <A href="Option.html">Option</a>&nbsp;components.</P>

  </td>
 </tr>

 <tr>
  <td colspan="2">
   <b>See Also</b><br>
 	<A href="Select.html">Select</a>, <A href="Option.html">Option</a>,
 	<A href="Radio.html">Radio</a>, <A href="RadioGroup.html">RadioGroup</a>,
 	<A href="Form.html">Form</a>,
   <A href="Script.html">Script</a>
  </td>
 </tr>

 <tr>
  <td colspan="2">
   <b>Parameters</b>
 	<br>
   <table border="1" cellpadding="4" cellspacing="4"  class="parameters">
   <tr>
     <th>Name</th>
     <th>Type</th>
 	  <th>Direction</th>
     <th>Required</th>
     <th>Default</th>
     <th >Description</th>
   </tr>
   <tr>
     <td>value</td>
     <td>Object</td>
     <td>in-out</td>
    	<td>yes</td>
 		<td>&nbsp;</td>
 		<td>The property to set. During rendering, this property is read, and sets
 		the default value of the selection (if it is null, no element is selected).
 		When the form is submitted, this property is updated based on the new
 		selection.
 		</td>
 	</tr>
   <tr>
  		<td>model</td>
 		<td>
 		 <A href="../api/org/apache/tapestry/form/IPropertySelectionModel.html"><tt>
 		 IPropertySelectionModel</tt></a>
 		</td>
 		<td>in</td>
 		<td>yes</td>
 		<td>&nbsp;</td>
 		<td>The model provides a list of possible labels, and matches those labels
 		against possible values that can be assigned back to the property.
 		</td>
 	</tr>
   <tr>
  		<td>disabled</td>
 		<td>boolean</td>
 		<td>in</td>
 		<td>no</td>
 		<td>false</td>
 		<td>Controls whether the &lt;select&gt; is active or not. A disabled
 		PropertySelection does not update its value parameter. Corresponds to the
 		"disabled" HTML attribute.
 		</td>
 	</tr>
   <tr>
  		<td>submitOnChange</td>
 		<td>boolean</td>
 		<td>in</td>
 		<td>no</td>
 		<td>false</td>
 		<td>If true, then additional JavaScript is added to submit the containing
 		form when select is changed. Equivalent to specifying a JavaScript event
 		handler of <code>this.form.submit()</code>.
 		</td>
 	</tr>
 	</table>
   <P>
   Body: <STRONG>removed</STRONG><BR>
   Informal parameters: <STRONG>allowed</STRONG><br>
   Reserved parameters: "name"
   </P>
  </td>
 </tr>

 <tr>
  <td colspan="2">
   <b>Examples</b>
   <p>
   The PropertySelection component provides Gender selection drop down list using a
   <a href="../api/org/apache/tapestry/form/StringPropertySelectionModel.html"><tt>StringPropertySelectionModel<tt></tt></tt></a>
             <tt><tt>
             <p>
             <table class="examples" valign="middle" cellspacing="8">
               <tr>
                 <td>Gender:
                   <select>
                     <option selected>Unspecified</option>
                     <option>Female</option>
                     <option>Male</option>
                   </select>
                 </td>
               </tr>
             </table>
             </tt></tt>
             <pre>
 &lt;form jwcid="@<A href="Form.html">Form</a>" listener="ognl:listeners.formSubmit"&gt;
  Gender: &lt;span jwcid="<span class="jwcid">@<a href="PropertySelection.html">PropertySelection</a></span>" model="ognl:@com.mycorp.DetailsPage@GENDER_MODEL" value="ognl:gender"/&gt;
 &lt;/form&gt;

 &lt;property-specification name=&quot;gender&quot; type=&quot;java.lang.String&quot;/&gt;<br>
 package com.mycorp;

 public abstract class DetailsPage extends BasePage {
     public static final <A href="../api/org/apache/tapestry/form/IPropertySelectionModel.html">IPropertySelectionModel</a> GENDER_MODEL =
         new <A href="../api/org/apache/tapestry/form/StringPropertySelectionModel.html">StringPropertySelectionModel</a>(new String[] { "Unspecified", "Female", "Male" });

     public abstract String getGender();

     public void formSubmit(IRequestCycle cycle) {
         // Process form submission
         String genderSelection = getGender();
         ..
     }
 }
 </pre>
             <hr>
             <a name="Example2"></a>
             <p> Provides list of clothing items for the user to select. When the
               user selects a cloting item from the list the description the label
               and price is automatically updated. The list of clothing items would
               typically be loaded from a database.
             <p> This example uses the component's <b>submitOnChange</b> property
               to automatically submit the form when a HTML &lt;select&gt; onchange
               event occurs. The page's clothing item property is then updated
               and the new cloting item information is displayed by the description,
               label and price <a href="Insert.html">Insert</a> components.
             <p>
             <table class="examples" valign="middle" cellspacing="8">
               <tr>
                 <td>Item:
                   <select>
                     <option selected>Dress</option>
                     <option>Jacket</option>
                     <option>Pants</option>
                     <option>Shirt</option>
                     <option>Skirt</option>
                   </select>
                   <p> Description: Cotton full length Summer dress
                   <p> Label: CountryClub
                   <p> Price: $89.95</p>
                 </td>
               </tr>
             </table>
             <pre>
 &lt;form jwcid="@<a href="Form.html">Form</a>" listener="ognl:listeners.formSubmit"&gt;
  Item: &lt;span jwcid="<span class="jwcid">selectItem</span>"/&gt;
  &lt;p&gt;
  Description: &lt;span jwcid="@<a href="Insert.html">Insert</a>" value="ognl:clothingItem.description"/&gt;
  &lt;p&gt;
  Label: &lt;span jwcid="@<a href="Insert.html">Insert</a>" value="ognl:clothingItem.label"/&gt;
  &lt;p&gt;
  Price: $&lt;span jwcid="@<a href="Insert.html">Insert</a>" value="ognl:clothingItem.price"/&gt;
 &lt;/form&gt;


 &lt;component id="<span class="jwcid">selectItem</span>" type="<A href="PropertySelection.html">PropertySelection</a>"&gt;
     &lt;binding name="model" expression="itemSelectionModel"/&gt;
     &lt;binding name="value" expression="clothingItem"/&gt;
     &lt;binding name="<b>submitOnChange</b>" expression="true"/&gt;
 &lt;/component&gt;

 &lt;property-specification name=&quot;clothingItem&quot; type=&quot;Item&quot; persistent=&quot;yes&quot;/&gt;<br>&lt;property-specification name=&quot;itemSelectionModel&quot; type=&quot;ItemSelectionModel&quot; persistent=&quot;yes&quot;/&gt;<br>

 public abstract class PurchagePage extends BasePage {

     public abstract Item getClothingItem();
     public abstract void setClothingItem(Item value);

     public abstract ItemSelectionModel getItemSelectionModel();

     public void setItemSelectionModel(ItemSelectionModel value);

     public void formSubmit(IRequestCycle cycle) {
         // Process form submission
     }
 }

 public class Item implements Serializable {
     private int id;
     private String name;
     private String description;
     private String label;
     private String price;

     public Item(int id, String name, String desc, String label, String price) {
         this.id = id;
         this.name = name;
         this.description = desc;
         this.label = label;
         this.price = price;
     }

     public int getId() { return id;  }

     public String getName() { return name;  }

     public String getDescription() { return description;  }

     public String getLabel() { return label;  }

     public String getPrice() { return price;  }
 }

 public class ItemSelectionModel implements IPropertySelectionModel, Serializable {
     private List itemList;

     public ItemSelectionModel(List itemList) {
         this.itemList = itemList;
     }

     public int getOptionCount() { return itemList.size(); }

     public Object getOption(int index) {
         return itemList.get(index);
     }

     public String getLabel(int index) {
         return ((Item) itemList.get(index)).getName();
     }

     public String getValue(int index) { return Integer.toString(index); }

     public Object translateValue(String value) {
         return getOption(Integer.parseInt(value));
     }
 }
 </pre>
           </td>
         </tr></table>
 </td></tr>
 <tr>
  <td colspan="3"><hr></td>
 </tr>
 <tr>
  <td align="left"><A href="PageLink.html"><IMG alt=PageLink src="common-images/prev.png"></a></td>
  <td align="middle"><A href="index.html"><IMG alt=Index src="common-images/home.png"></a></td>
  <td align="right"><A href="Radio.html"><IMG alt=Radio src="common-images/next.png"></a></td>
 </tr>
 </table>

 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<!-- $Id$ -->
	<html>
	<head>
	<title>PropertySelection</title>
	<link rel="stylesheet" type="text/css" href="Tapestry.css" title="style">
	</head>

	<body>
	<table border="0" cellpadding="0" cellspacing="0" width="100%">
	<tr>
	<td align="left"><A href="PageLink.html"><IMG alt=PageLink src="common-images/prev.png"></a></td>
	<td align="middle"><A href="index.html"><IMG alt=Index src="common-images/home.png"></a></td>
	<td align="right"><A href="Radio.html"><IMG alt=Radio src="common-images/next.png"></a></td>
	<tr>
	<tr>
	<td colspan="3"><hr></td>
	</tr>
	<tr>
	<td colspan="3">
	<table border="0" cellpadding="4" cellspacing="4" width="100%">

	<tr valign="top">
	<td>
	<table>
	<tr>
	<td><font size="+2"><b>PropertySelection</b></font></td>
	</tr>
	<tr>
	<td>
	<A href="../api/org/apache/tapestry/form/PropertySelection.html">
	org.apache.tapestry.form.PropertySelection</a>
	</td>
	</tr>
	</table>
	</td>
	<td>
	<table align="right" valign="middle" bgcolor="#c0c0c0" cellspacing="8">
	<tr>
	<td>Color
	<select>
	<option selected>Red</option>
	<option>Blue</option>
	<option>Green</option>
	</select>
	</td>
	</tr>
	</table>
	</td>
	</tr>

	<tr valign="center">
	<td colspan="2"> </td>
	</tr>

	<tr>
	<td colspan="2">
	<P>
	<b>Description</b>
	<br>
	Creates form elements that allow a property of
	an object to be set from a drop-down list.</P>
	<P>
	Uses a
	<A href="../api/org/apache/tapestry/form/IPropertySelectionModel.html">model</a>
	to map between Java values that will be assigned, and textual labels
	that will appear in the HTML response.
	</P>
	<p>
	There is a range property selection models you can use, including
	<A href="../api/org/apache/tapestry/form/StringPropertySelectionModel.html">
	<tt>StringPropertySelectionModel</tt></a>
	and
	<A href="../api/org/apache/tapestry/form/EnumPropertySelectionModel.html">
	<tt>EnumPropertySelectionModel</tt></a>. You can also create your own model,
	as illustrated in the Examples below.
	<p>
	Note that complex value Objects need to properly implement the
	<tt>Object.equals()</tt>
	method if the correct initial item is to be displayed.
	<P>
	Informal parameters are applied to the <select> tag.
	To have greater control over the <option> tags, you must use the
	<A href="Select.html">Select</a> and <A href="Option.html">Option</a> components.</P>

	</td>
	</tr>

	<tr>
	<td colspan="2">
	<b>See Also</b><br>
	<A href="Select.html">Select</a>, <A href="Option.html">Option</a>,
	<A href="Radio.html">Radio</a>, <A href="RadioGroup.html">RadioGroup</a>,
	<A href="Form.html">Form</a>,
	<A href="Script.html">Script</a>
	</td>
	</tr>

	<tr>
	<td colspan="2">
	<b>Parameters</b>
	<br>
	<table border="1" cellpadding="4" cellspacing="4" class="parameters">
	<tr>
	<th>Name</th>
	<th>Type</th>
	<th>Direction</th>
	<th>Required</th>
	<th>Default</th>
	<th >Description</th>
	</tr>
	<tr>
	<td>value</td>
	<td>Object</td>
	<td>in-out</td>
	<td>yes</td>
	<td> </td>
	<td>The property to set. During rendering, this property is read, and sets
	the default value of the selection (if it is null, no element is selected).
	When the form is submitted, this property is updated based on the new
	selection.
	</td>
	</tr>
	<tr>
	<td>model</td>
	<td>
	<A href="../api/org/apache/tapestry/form/IPropertySelectionModel.html"><tt>
	IPropertySelectionModel</tt></a>
	</td>
	<td>in</td>
	<td>yes</td>
	<td> </td>
	<td>The model provides a list of possible labels, and matches those labels
	against possible values that can be assigned back to the property.
	</td>
	</tr>
	<tr>
	<td>disabled</td>
	<td>boolean</td>
	<td>in</td>
	<td>no</td>
	<td>false</td>
	<td>Controls whether the <select> is active or not. A disabled
	PropertySelection does not update its value parameter. Corresponds to the
	"disabled" HTML attribute.
	</td>
	</tr>
	<tr>
	<td>submitOnChange</td>
	<td>boolean</td>
	<td>in</td>
	<td>no</td>
	<td>false</td>
	<td>If true, then additional JavaScript is added to submit the containing
	form when select is changed. Equivalent to specifying a JavaScript event
	handler of <code>this.form.submit()</code>.
	</td>
	</tr>
	</table>
	<P>
	Body: <STRONG>removed</STRONG><BR>
	Informal parameters: <STRONG>allowed</STRONG><br>
	Reserved parameters: "name"
	</P>
	</td>
	</tr>

	<tr>
	<td colspan="2">
	<b>Examples</b>
	<p>
	The PropertySelection component provides Gender selection drop down list using a
	<a href="../api/org/apache/tapestry/form/StringPropertySelectionModel.html"><tt>StringPropertySelectionModel<tt></tt></tt></a>
	<tt><tt>
	<p>
	<table class="examples" valign="middle" cellspacing="8">
	<tr>
	<td>Gender:
	<select>
	<option selected>Unspecified</option>
	<option>Female</option>
	<option>Male</option>
	</select>
	</td>
	</tr>
	</table>
	</tt></tt>
	<pre>
	<form jwcid="@<A href="Form.html">Form</a>" listener="ognl:listeners.formSubmit">
	Gender: <span jwcid="<span class="jwcid">@<a href="PropertySelection.html">PropertySelection</a></span>" model="ognl:@com.mycorp.DetailsPage@GENDER_MODEL" value="ognl:gender"/>
	</form>

	<property-specification name="gender" type="java.lang.String"/><br>
	package com.mycorp;

	public abstract class DetailsPage extends BasePage {
	public static final <A href="../api/org/apache/tapestry/form/IPropertySelectionModel.html">IPropertySelectionModel</a> GENDER_MODEL =
	new <A href="../api/org/apache/tapestry/form/StringPropertySelectionModel.html">StringPropertySelectionModel</a>(new String[] { "Unspecified", "Female", "Male" });

	public abstract String getGender();

	public void formSubmit(IRequestCycle cycle) {
	// Process form submission
	String genderSelection = getGender();
	..
	}
	}
	</pre>
	<hr>
	<a name="Example2"></a>
	<p> Provides list of clothing items for the user to select. When the
	user selects a cloting item from the list the description the label
	and price is automatically updated. The list of clothing items would
	typically be loaded from a database.
	<p> This example uses the component's <b>submitOnChange</b> property
	to automatically submit the form when a HTML <select> onchange
	event occurs. The page's clothing item property is then updated
	and the new cloting item information is displayed by the description,
	label and price <a href="Insert.html">Insert</a> components.
	<p>
	<table class="examples" valign="middle" cellspacing="8">
	<tr>
	<td>Item:
	<select>
	<option selected>Dress</option>
	<option>Jacket</option>
	<option>Pants</option>
	<option>Shirt</option>
	<option>Skirt</option>
	</select>
	<p> Description: Cotton full length Summer dress
	<p> Label: CountryClub
	<p> Price: $89.95</p>
	</td>
	</tr>
	</table>
	<pre>
	<form jwcid="@<a href="Form.html">Form</a>" listener="ognl:listeners.formSubmit">
	Item: <span jwcid="<span class="jwcid">selectItem</span>"/>
	<p>
	Description: <span jwcid="@<a href="Insert.html">Insert</a>" value="ognl:clothingItem.description"/>
	<p>
	Label: <span jwcid="@<a href="Insert.html">Insert</a>" value="ognl:clothingItem.label"/>
	<p>
	Price: $<span jwcid="@<a href="Insert.html">Insert</a>" value="ognl:clothingItem.price"/>
	</form>


	<component id="<span class="jwcid">selectItem</span>" type="<A href="PropertySelection.html">PropertySelection</a>">
	<binding name="model" expression="itemSelectionModel"/>
	<binding name="value" expression="clothingItem"/>
	<binding name="<b>submitOnChange</b>" expression="true"/>
	</component>

	<property-specification name="clothingItem" type="Item" persistent="yes"/><br><property-specification name="itemSelectionModel" type="ItemSelectionModel" persistent="yes"/><br>

	public abstract class PurchagePage extends BasePage {

	public abstract Item getClothingItem();
	public abstract void setClothingItem(Item value);

	public abstract ItemSelectionModel getItemSelectionModel();

	public void setItemSelectionModel(ItemSelectionModel value);

	public void formSubmit(IRequestCycle cycle) {
	// Process form submission
	}
	}

	public class Item implements Serializable {
	private int id;
	private String name;
	private String description;
	private String label;
	private String price;

	public Item(int id, String name, String desc, String label, String price) {
	this.id = id;
	this.name = name;
	this.description = desc;
	this.label = label;
	this.price = price;
	}

	public int getId() { return id; }

	public String getName() { return name; }

	public String getDescription() { return description; }

	public String getLabel() { return label; }

	public String getPrice() { return price; }
	}

	public class ItemSelectionModel implements IPropertySelectionModel, Serializable {
	private List itemList;

	public ItemSelectionModel(List itemList) {
	this.itemList = itemList;
	}

	public int getOptionCount() { return itemList.size(); }

	public Object getOption(int index) {
	return itemList.get(index);
	}

	public String getLabel(int index) {
	return ((Item) itemList.get(index)).getName();
	}

	public String getValue(int index) { return Integer.toString(index); }

	public Object translateValue(String value) {
	return getOption(Integer.parseInt(value));
	}
	}
	</pre>
	</td>
	</tr></table>
	</td></tr>
	<tr>
	<td colspan="3"><hr></td>
	</tr>
	<tr>
	<td align="left"><A href="PageLink.html"><IMG alt=PageLink src="common-images/prev.png"></a></td>
	<td align="middle"><A href="index.html"><IMG alt=Index src="common-images/home.png"></a></td>
	<td align="right"><A href="Radio.html"><IMG alt=Radio src="common-images/next.png"></a></td>
	</tr>
	</table>

	</body>
	</html>