Download PDF Home History |  | API Search Feedback FAQ

> ## Writing Component Properties

> As explained in Backing Bean Management, there are two kinds of backing bean properties: those that are bound to a component's value and those that are bound to a component instance. These properties follow JavaBeans component conventions (see JavaBeans Components).

> The component tag binds the component's value to a property using its `value` attribute. The component tag binds the component instance to a property using its `binding` attribute. Using the attributes to bind components and their values to properties is discussed in Binding Component Values and Instances to External Data Sources.

> To bind a component's value to a backing bean property, the type of the property must match the type of the component's value to which it is bound. For example, if a backing bean property is bound to a `UISelectBoolean` component's value, the property should accept and return a `boolean` value or a `Boolean` wrapper `Object` instance.

> To bind a component instance, the property must match the component type. For example, if a backing bean property is bound to a `UISelectBoolean` instance, the property should accept and return `UISelectBoolean`.

> The rest of this section explains how to write properties that can be bound to component values and component instances for the component objects described in Using the HTML Component Tags.

> ### Writing Properties Bound to Component Values

> To write a backing bean property bound to a component's value, you must know the types that the component's value can be so that you can make the property match the type of the component's value.

> Table 19-1 lists all the component classes described in Using the HTML Component Tags and the acceptable types of their values.

> When page authors bind components to properties using the `value` attributes of the component tags, they need to ensure that the corresponding properties match the types of the components' values.

> Table 19-1 Acceptable Types of Component Values
> Component | Acceptable Types of Component Values
> --- | ---
> `UIInput`, `UIOutput`, `UISelectItem`, `UISelectOne` | Any of the basic primitive and numeric types or any Java programming language object type for which an appropriate `Converter` implementation is available.
> `UIData` | `array` of beans, `List` of beans, single bean, `java.sql.ResultSet,` `javax.servlet.jsp.jstl.sql.Result`, `javax.sql.RowSet`.
> `UISelectBoolean` | `boolean or Boolean`.
> `UISelectItems` | `java.lang.String, Collection, Array, Map`.
> UISelectMany | array or List. Elements of the array or List can be any of the standard types.

> #### UIInput and UIOutput Properties

> The following tag binds the `name` component to the `name` property of `CashierBean`.

>     <h:inputText id="name" size="50"
>       value="#{cashier.name}"
>       required="true">
>       <f:valueChangeListener type="listeners.NameChanged" />
>     </h:inputText>

> Here is the bean property bound to the `name` component:

>     protected String name = null;
>     public void setName(String name) {
>       this.name = name;
>     }
>     public String getName() {
>       return this.name;
>     }

> As Using the Standard Converters describes, to convert the value of a `UIInput` or `UIOutput` component, you can either apply a converter or create the bean property bound to the component with the desired type. Here is the example tag explained in Using DateTimeConverter that displays the date books will be shipped:

>     <h:outputText value="#{cashier.shipDate}">
>       <f:convertDateTime dateStyle="full" />
>     </h:outputText>

> The application developer must ensure that the property bound to the component represented by this tag has a type of `java.util.Date`. Here is the `shipDate` property in `CashierBean`:

>     protected Date shipDate;
>     public Date getShipDate() {
>       return this.shipDate;
>     }
>     public void setShipDate(Date shipDate) {
>       this.shipDate = shipDate;
>     }

> See Binding Component Values and Instances to External Data Sources for more information on applying a `Converter` implementation.

> #### UIData Properties

> `UIData` components must be bound to one of the types listed in Table 19-1. The `UIData` component from the `bookshowcart.jsp` page of the Duke's Bookstore example is discussed in the section The UIData Component. Here is part of the start tag of `dataTable` from that section:

>     <h:dataTable  id="items"
>       ...
>       value="#{cart.items}"
>       var="item" >

> The value-binding expression points to the `items` property of the `ShoppingCart` bean. The `ShoppingCart` bean maintains a map of `ShoppingCartItem` beans.

> The `getItems` method from `ShoppingCart` populates a `List` with `ShoppingCartItem` instances that are saved in the items map from when the customer adds books to the cart:

>     public synchronized List getItems() {
>       List results = new ArrayList();
>       Iterator items = this.items.values().iterator();
>       while (items.hasNext()) {
>         results.add(items.next());
>       }
>       return (results);
>     }

> All the components contained in the `UIData` component are bound to the properties of the `ShoppingCart` bean that is bound to the entire `UIData` component. For example, here is the `outputText` tag that displays the book title in the table:

>     <h:commandLink action="#{showcart.details}">
>       <h:outputText value="#{item.item.title}"/>
>     </h:commandLink>

> The book title is actually a hyperlink to the `bookdetails.jsp` page. The `outputText` tag uses the value-binding expression `#{item.item.title}` to bind its `UIOutput` component to the `title` property of the `BookDetails` bean. The first `item` in the expression is the `ShoppingCartItem` instance that the `dataTable` tag is referencing while rendering the current row. The second `item` in the expression refers to the `item` property of `ShoppingCartItem`, which returns a `BookDetails` bean. The `title` part of the expression refers to the `title` property of `BookDetails`. The value of the `UIOutput` component corresponding to this tag is bound to the `title` property of the `BookDetails` bean:

>     private String title = null;
>     public String getTitle() {
>       return this.title;
>     }
>     public void setTitle(String title) {
>       this.title=title;
>     }

> #### UISelectBoolean Properties

> Properties that hold the `UISelectBoolean` component's data must be of `boolean` or `Boolean` type. The example `selectBooleanCheckbox` tag from the section The UISelectBoolean Component binds a component to a property. Here is an example that binds a component value to a property:

>     <h:selectBooleanCheckbox title="#{bundle.receiveEmails}"
>       value="#{custFormBean.receiveEmails}" >
>     </h:selectBooleanCheckbox>
>     <h:outputText value="#{bundle.receiveEmails}">

> Here is an example property that can be bound to the component represented by the example tag:

>       protected boolean receiveEmails = false;
>         ...
>       public void setReceiveEmails(boolean receiveEmails) {
>         this.receiveEmails = receiveEmails;
>       }
>       public boolean getReceiveEmails() {
>         return receiveEmails;
>       }

> #### UISelectMany Properties

> Because a `UISelectMany` component allows a user to select one or more items from a list of items, this component must map to a bean property of type `List` or `array`. This bean property represents the set of currently selected items from the list of available items.

> Here is the example `selectManyCheckbox` tag from Using the selectManyCheckbox Tag:

>     <h:selectManyCheckbox
>       id="newsletters"
>       layout="pageDirection"
>       value="#{cashier.newsletters}">
>       <f:selectItems value="#{newsletters}"/>
>     </h:selectManyCheckbox>

> Here is a bean property that maps to the `value` of this `selectManyCheckbox` example:

>     protected String newsletters[] = new String[0];

>     public void setNewsletters(String newsletters[]) {
>       this.newsletters = newsletters;
>     }
>     public String[] getNewsletters() {
>       return this.newsletters;
>     }

> As explained in the section The UISelectMany Component, the `UISelectItem` and `UISelectItems` components are used to represent all the values in a `UISelectMany` component. See UISelectItem Properties and UISelectItems Properties for information on how to write the bean properties for the `UISelectItem` and `UISelectItems` components.

> #### UISelectOne Properties

> `UISelectOne` properties accept the same types as `UIInput` and `UIOutput` properties. This is because a `UISelectOne` component represents the single selected item from a set of items. This item can be any of the primitive types and anything else for which you can apply a converter.

> Here is the example `selectOneMenu` tag from Using the selectOneMenu Tag:

>     <h:selectOneMenu   id="shippingOption"
>       required="true"
>       value="#{cashier.shippingOption}">
>       <f:selectItem
>         itemValue="2"
>         itemLabel="#{bundle.QuickShip}"/>
>       <f:selectItem
>         itemValue="5"
>         itemLabel="#{bundle.NormalShip}"/>
>       <f:selectItem
>         itemValue="7"
>         itemLabel="#{bundle.SaverShip}"/>
>     </h:selectOneMenu>

> Here is the property corresponding to this tag:

>     protected String shippingOption = "2";

>     public void setShippingOption(String shippingOption) {
>       this.shippingOption = shippingOption;
>     }
>     public String getShippingOption() {
>       return this.shippingOption;
>     }

> Note that `shippingOption` represents the currently selected item from the list of items in the `UISelectOne` component.

> As explained in the section The UISelectOne Component, the `UISelectItem` and `UISelectItems` components are used to represent all the values in a `UISelectOne` component. See UISelectItem Properties and UISelectItems Properties for information on how to write the backing bean properties for the `UISelectItem` and `UISelectItems` components.

> #### UISelectItem Properties

> A `UISelectItem` component represents one value in a set of values in a `UISelectMany` or `UISelectOne` component. The backing bean property that a `UISelectItem` component is bound to must be of type `SelectItem`. A `SelectItem` object is composed of an `Object` representing the value, along with two `Strings` representing the label and description of the `SelectItem` object.

> The Duke's Bookstore application does not use any `UISelectItem` components whose values are bound to backing beans. The example `selectOneMenu` tag from Using the selectOneMenu Tag contains `selectItem` tags that set the values of the list of items in the page. Here is an example bean property that can set the values for this list in the bean:

>     SelectItem itemOne = null;

>     SelectItem getItemOne(){
>       return itemOne;

>     }

>     void setItemOne(SelectItem item) {
>       itemOne = item;
>     }

> #### UISelectItems Properties

> `UISelectItems` components are children of `UISelectMany` and `UISelectOne` components. Each `UISelectItems` component is composed of either a set of `SelectItem` instances or a set of `SelectItemGroup` instances. As described in Using the selectItems Tag, a `SelectItemGroup` is composed of a set of `SelectItem` instances. This section describes how to write the properties for `selectItems` tags containing `SelectItem` instances and for `selectItems` tags containing `SelectItemGroup` instances.

> ##### Properties for SelectItems Composed of SelectItem Instances

> Using the selectItems Tag describes how the newsletters list of the Duke's Bookstore application is populated using the application configuration resource file. You can also populate the `SelectItems` with `SelectItem` instances programmatically in the backing bean. This section explains how to do this.

> In your backing bean, you create a list that is bound to the `SelectItem` component. Then you define a set of `SelectItem` objects, set their values, and populate the list with the `SelectItem` objects. Here is an example code snippet that shows how to create a `SelectItems` property:

>     import javax.faces.component.SelectItem;
>     ...
>     protected ArrayList options = null;
>     protected SelectItem newsletter0 =
>       new SelectItem("200", "Duke's Quarterly", "");
>     ...
>     //in constructor, populate the list
>     options.add(newsletter0);
>     options.add(newsletter1);
>     options.add(newsletter2);
>     ...
>     public SelectItem getNewsletter0(){
>       return newsletter0;
>     }

>     void setNewsletter0(SelectItem firstNL) {
>       newsletter0 = firstNL;
>     }
>     // Other SelectItem properties

>     public Collection[] getOptions(){
>       return options;
>     }
>     public void setOptions(Collection[] options){
>       this.options = new ArrayList(options);
>     }

> The code first initializes `options` as a list. Each newsletter property is defined with values. Then, each newsletter `SelectItem` is added to the list. Finally, the code includes the obligatory `setOptions` and `getOptions` accessor methods.

> ##### Properties for SelectItems Composed of SelectItemGroup Instances

> The preceding section explains how to write the bean property for a `SelectItems` component composed of `SelectItem` instances. This section explains how to change the example property from the preceding section so that the `SelectItems` is composed of `SelectItemGroup` instances.

> Let's separate the newsletters into two groups: One group includes Duke's newsletters, and the other group includes the Innovator's Almanac and Random Ramblings newsletters.

> In your backing bean, you need a list that contains two `SelectItemGroup` instances. Each `SelectItemGroup` instance contains two `SelectItem` instances, each representing a newsletter:

>     import javax.faces.model.SelectItemGroup;
>     ...
>     private ArrayList optionsGroup = null;

>     optionsGroup = new ArrayList(2);

>     private static final SelectItem options1[] = {
>       new SelectItem("200", "Duke's Quarterly", "");
>       new SelectItem("202",
>         "Duke's Diet and Exercise Journal", "");
>     };
>     private static final SelectItem options2[] = {
>       new SelectItem("201", "Innovator's Almanac", "");
>       new SelectItem("203", "Random Ramblings", "");
>     };

>     SelectItemGroup group1 =
>       new SelectItemGroup("Duke's", null, true, options1);
>     SelectItemGroup group2 =
>       new SelectItemGroup("General Interest", null, true,
>         options2);

>     optionsGroup.add(group1);
>     optionsGroup.add(group2);
>     ...
>     public Collection getOptionsGroup() {
>       return optionsGroup;
>     }
>     public void setOptionsGroup(Collection newGroupOptions) {
>       optionsGroup = new ArrayList(newGroupOptions);
>     }

> The code first initializes `optionsGroup` as a list. The `optionsGroup` list contains two `SelectItemGroup` objects. Each object is initialized with the label of the group appearing in the list or menu; a value; a Boolean indicating whether or not the label is disabled; and an array containing two `SelectItem` instances. Then each `SelectItemGroup` is added to the list. Finally, the code includes the `setOptionsGroup` and `getOptionsGroup` accessor methods so that the tag can access the values. The `selectItems` tag references the `optionsGroup` property to get the `SelectItemGroup` objects for populating the list or menu on the page.

> ### Writing Properties Bound to Component Instances

> A property bound to a component instance returns and accepts a component instance rather than a component value. Here are the tags described in Binding a Component Instance to a Bean Property that bind components to backing bean properties:

>     <h:selectBooleanCheckbox
>       id="fanClub"
>       rendered="false"
>       binding="#{cashier.specialOffer}" />
>     <h:outputLabel for="fanClub"
>       rendered="false"
>       binding="#{cashier.specialOfferText}"  >
>       <h:outputText id="fanClubLabel"
>         value="#{bundle.DukeFanClub}" />
>     </h:outputLabel>

> As Binding a Component Instance to a Bean Property explains, the `selectBooleanCheckbox` tag renders a checkbox and binds the `fanClub` `UISelectBoolean` component to the `specialOffer` property of `CashierBean`. The `outputLabel` tag binds the `fanClubLabel` component (which represents the checkbox's label) to the `specialOfferText` property of `CashierBean`. If the user orders more than $100 (or 100 euros) worth of books and clicks the Submit button, the `submit` method of `CashierBean` sets both components' `rendered` properties to `true`, causing the checkbox and label to display when the page is rerendered.

> Because the components corresponding to the example tags are bound to the backing bean properties, these properties must match the components' types. This means that the `specialOfferText` property must be of `UIOutput` type, and the `specialOffer` property must be of `UISelectBoolean` type:

>     UIOutput specialOfferText = null;

>     public UIOutput getSpecialOfferText() {
>       return this.specialOfferText;
>     }
>     public void setSpecialOfferText(UIOutput specialOfferText) {
>       this.specialOfferText = specialOfferText;
>     }

>     UISelectBoolean specialOffer = null;

>     public UISelectBoolean getSpecialOffer() {
>       return this.specialOffer;
>     }
>     public void setSpecialOffer(UISelectBoolean specialOffer) {
>       this.specialOffer = specialOffer;
>     }

> See Backing Bean Management for more general information on component binding.

> See Referencing a Method That Performs Navigation for information on how to reference a backing bean method that performs navigation when a button is clicked.

> See Writing a Method to Handle Navigation for more information on writing backing bean methods that handle navigation.

Download PDF Home History |  | API Search Feedback FAQ

All of the material in The J2EE(TM) 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.