7.2 Creating a Basic Table

Unlike with forms, where you bind the individual UI components that make up a form to the individual attributes on the collection, with a table you bind the ADF Faces table component to the complete collection or to a range of N data objects at a time from the collection. The individual columns in the table are then bound to the attributes. The iterator binding handles displaying the correct data for each object, while the table component handles displaying each object in a row. JDeveloper allows you to do this declaratively, so that you don't need to write any code.

7.2.1 How to Create a Basic Table

To create a table using a data control, you must bind to a method on the data control that returns a collection. JDeveloper allows you to do this declaratively by dragging and dropping a collection from the Data Control Palette.

To create a databound table:

From the Data Control Palette, select a method return that returns a collection.

For example, to create the SRList table in the SRDemo application, you drag the ServiceRequest collection that the findServiceRequest(Integer, String) method returns. This method takes an Integer parameter value that represents the user ID of the current user and a String value that represents the status of open, and returns all open requests for that user. Figure 7-2 shows the ServiceRequests collection in the Data Control Palette. For more information about how the parameters are set to determine the records to display, see Section 10.6.1, "How to Create a Form or Table Using a Method That Takes Parameters".

Figure 7-2 Collection Returned for a Method
Drag the method return onto a JSF page, and from the context menu, choose the appropriate table.

When you drag the collection, you can choose from the following types of tables:
- ADF Table: Allows you to select the specific attributes you wish your editable table columns to display, and what UI components to use to display the data. By default, each attribute on the collection object is displayed in an inputText component, thus enabling the table to be editable.
- ADF Read-Only Table: Same as the ADF Table; however, each attribute is displayed in an outputText component.
- ADF Read-Only Dynamic Table: The attributes returned and displayed are determined dynamically. This component is helpful when the attributes for the corresponding object are not known until runtime, or you do not wish to hardcode the column names in the JSF page. For example, if you have a method that returns a polymorphic collection (i.e. getAnimals() can return a collection of mammals or a collection of birds), the dynamic table can display the different attributes accordingly.
  
  Note:
  You can also drop a collection as an ADF Master Table, Inline Detail Table. For more information, see Section 8.6, "Using an Inline Table to Display Detail Data in a Master Table".
From the ensuing Edit Table Columns dialog, you can do the following:
- Change the display label for a column. By default, the label is bound to the label property of the table binding. For more information about this property, see Section B, "Reference ADF Binding Properties". This binding to the property allows you to change the value of the label text once and have it appear the same on all pages that display the label. In this dialog, you can instead enter text or an EL expression to bind the label value to something else, for example, a key in a resource file.
  
  For example, the headings for the status columns in the table on the SRList page are bound to the label property of the status attribute binding:
```
#{bindings.findServiceRequests1.labels.status}
```
  However, you could change the headings to instead be bound to a key in a properties file, for example:
```
#{srlist['sr.status']}
```
  In this example, srlist would be a variable defined in the JSF page used to load a properties file. For more information about using resource bundles, see Section 14.4, "Internationalizing Your Application".
- Change the attribute binding for a column.
  
  For example, you can change the status column to instead be bound to the requestDate attribute. Note the following:
  - If you change the binding, the label for the column also changes.
  - If you change the binding to an attribute currently bound to another column, the UI component changes to a component different from that used for the column currently bound to that attribute.
  If you simply want to rearrange the columns, you should use the order buttons. See the fourth bullet point below for more information.
- Change the UI component used to display an attribute. The UI components are either inputText or outputText and are set based on the table you selected when you dropped the collection onto the page. You can change to the other component using the dropdown menu. If you want to use a different component, such as a command link or button, you need to use this dialog to select the outputText component, and then in the Structure window, add that other UI component (such as a command link) as a parent to this component.
- Change the order of the columns using the order buttons. Top moves the column to the first column at the left of the table. Up moves the column one column to the left. Down moves the column one to the right. Bottom moves the column to the very right.
- Add a column using the New button. Doing so adds a new column at the bottom of the dialog and populates it by default with values from the next sequential attribute in the collection. You then need to edit the values. You can only select an attribute associated with the object to which the table is bound.
- Delete a column using the Delete button. Doing so deletes the column from the table.
- Add a tableSelectOne component to the table's selection facet by selecting Enable selection. For more information, see Section 7.6, "Enabling Row Selection in a Table".
- Allow sorting for all columns by selecting Enable sorting.
  
  Note:
  If you choose to enable sorting, the table can only sort through the number of objects returned by the iterator, as determined by the iterators rangeSize attribute.

7.2.2 What Happens When You Use the Data Control Palette to Create a Table

Dropping a table from the Data Control Palette has the same effect as dropping a text field or form. For more information, see Section 6.2.2, "What Happens When You Use the Data Control Palette to Create a Text Field". Briefly, JDeveloper does the following:

Creates the bindings for the table and adds the bindings to the page definition file.
Adds the necessary code for the UI components to the JSF page.

7.2.2.1 Iterator and Value Bindings for Tables

When you drop a table from a the Data Control Palette, a table value binding is created. Like an attribute binding used in forms, the table value binding references the iterator binding. However, instead of creating a separate binding for each attribute, only the table binding is created. This table binding has a child attribute name element for each attribute. Example 7-1 shows the table binding for the table created when you drop the ServiceRequest collection.

Example 7-1 Value Binding Entries for a Table in the Page Definition File

<table id="findServiceRequest1" IterBinding="findServiceRequestsIter">
  <AttrNames>
    <Item Value="svrId"/>
    <Item Value="status"/>
    <Item Value="requestDate"/>
    <Item Value="problemDescription"/>
    <Item Value="assignedDate"/>
  </AttrNames>
</table>

Only the table value binding is needed because only the table UI component needs access to the data. The table columns derive their information from the table binding.

7.2.2.2 Code on the JSF Page for an ADF Faces Table

When you use the Data Control Palette to drop a table onto a JSF page, JDeveloper creates a table that contains a column for each attribute on the object to which it is bound. To do this, JDeveloper inserts an ADF Faces table component. This component contains an ADF Faces column component for each attribute named in the table binding. Each column then contains either an input or outputText component bound to the attribute's value. Each column's heading attribute is bound to the label property for each attribute on the table binding. Example 7-2 shows a simplified code excerpt from the table on the SRList page.

Example 7-2 Simple Example of JSF Code for an ADF Faces Table

<af:table var="row"
              value="#{bindings.findServiceRequests1.collectionModel}
  <af:column headerText="#{bindings.findServiceRequests1.labels.svrId}"
      <af:outputText value="#{row.svrId}"/>
  </af:column>
  <af:column headerText="#{bindings.findServiceRequests1.labels.status}"
    <af:outputText value="#{row.status}"/>
  </af:column>
         ...   
</af:table>

An ADF Faces table itself iterates over the data accessed by the iterator binding. In order to do this, the table wraps the result set from the iterator binding in an oracle.adf.view.faces.model.CollectionModel object. As the table iterates, it makes each item in the collection available within the table component using the var attribute.

In the example above, the table iterates over the collection from the findServiceRequests1 table binding, which in turn references the findServiceRequestsIter iterator binding. The iterator binding is what determines the current data object. When you set the var attribute on the table to row, each column then accesses the current data object for the current row presented to the table tag using the row variable, as shown for the value of the outputText tag:

<af:outputText value="#{row.status}"/>

Table 7-1 shows the other attributes defined by default for ADF Faces tables created using the Data Control Palette.

Table 7-1 ADF Faces Table Attributes and Populated Values

Attribute	Description	Default Value
`rows`	Determines how may rows to display at one time.	An EL expression that evaluates to the `rangeSize` property of the associated iterator binding. For more information on this attribute, see Section 7.3, "Incorporating Range Navigation into Tables". Note that the value of the `rows` attribute is equal to or less than the corresponding iterator's `rangeSize` value.
`first`	Index of the first row in a range (based on 0).	An EL expression that evaluates to the `rangeStart` property of the associated iterator binding. For more information on this attribute, see Section 7.3, "Incorporating Range Navigation into Tables".
`emptyText`	Text to display when there are no rows to return.	An EL expression that evaluates to the viewable property on the iterator. If the table is viewable, displays No rows yet when no objects are returned. If the table is not viewable (for example if there are authorization restrictions set against the table), displays Access Denied.
Column Attributes
`sortProperty`	Determines the property on which to sort the column.	Set to the columns corresponding attribute binding value.
`sortable`	Determines whether a column can be sorted	Set to `false`. When set to `true`, the table will sort only the rows returned by the iterator.

Additionally, a table may also have a selection facet, and selection and selectionListener attributes if you chose to enable selection when you created your table. For more information, see Section 7.6, "Enabling Row Selection in a Table".