14.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.

14.2.1 How to Create a Basic Table

To create a table using a data control, you bind the table component to a view object 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 collection.

For example, to create the SRList table in the SRDemo application, you select the ServiceRequestsByStatus collection that is under the LoggedInUser collection. Figure 14-2 shows the ServiceRequestsByStatus collection in the Data Control Palette.

Figure 14-2 ServiceRequestsByStatus Collection in the Data Control Palette

The ServiceRequestsByStatus collection, which extends ServiceRequests, is a child of the LoggedInUser collection because of the view link ServiceRequestsForUser. The ServiceRequestsByStatus collection also has a named bind variable StatusCode that represents the service request status type (for example, open or pending requests). In the SRList page, when the logged in user selects a command link in the menu bar to view open, pending, closed, or all service requests, the requests created by or assigned to the currently logged in user for the selected status type are returned.
Drag the collection 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 polymorphic collection (for example, a view object collection that can be a collection of mammals or a collection of birds), the dynamic table can display the different attributes accordingly.
- ADF Master Table, Inline Detail Table: For more information, see Section 15.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 labels property for the attribute on the table binding. For more information about the labels property, see Appendix B, "Reference ADF Binding Properties". The bindings to the labels property allow the labels to be inherited from the UI control hints that you have defined in your business domain layer, thus enabling you to change the value of a label text once in a central place, and have the change appear the same on all pages that display the label. In the Edit Table Columns 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 heading for the Status column in the table on the SRList page is bound to the labels property that uses the Status key to get the attribute:
```
#{bindings.LoggedInUserServiceRequests.labels.Status}
```
  However, you could change the heading to instead be bound to a key in a properties resource file, for example:
```
#{srlist['sr.status']}
```
  In the 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 22.4, "Internationalizing Your Application".
  
  Note that the SRDemo pages mainly use the inherited UI control hints for all attributes, and JSF resource strings for other kinds of labels that are not directly related to view object attributes.
- Change the attribute binding for a column.
  
  For example, you can change the status column to instead be bound to the requestDate attribute. If you simply want to rearrange the columns, you should use the order buttons, as described later in the section. If you do change the attribute binding for a column, 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.
- 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, replace the component with the desired UI component (such as a command link).
- 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. There's no limit to the number of columns you can add. When you first click New, JDeveloper adds a new column line at the bottom of the dialog and populates it with default values from the first attribute in the bound collection; subsequent new columns are populated with values from the next attribute in the sequence, and so on.
- 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 14.6, "Enabling Row Selection in a Table".
- Allow sorting for all columns by selecting Enable sorting.

14.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 13.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.

14.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; the iterator binding references an iterator for the data collection, which facilities iterating over the data objects in the collection. Instead of creating a separate binding for each attribute, only the table binding is created. In the table binding, the AttrNames element contains a a child element for each attribute that you want to be available for display or reference in each row of the table. Example 14-1 shows the value binding for the table created when you drop the ServiceRequestsByStatus collection.

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

<table id="LoggedInUserServiceRequests"
       IterBinding="ServiceRequestsByStatusIterator">
  <AttrNames>
    <Item Value="SvrId"/>
    <Item Value="Status"/>
    <Item Value="RequestDate"/>
    <Item Value="ProblemDescription"/>
    <Item Value="ProdId"/>
    <Item Value="CreatedBy"/>
    <Item Value="AssignedTo"/>
    <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.

14.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, which 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 is bound to the labels property for the attribute on the table binding. Example 14-2 shows a simplified code excerpt from the table on the SRList page.

Example 14-2 Simplified JSF Code for an ADF Faces Table

<af:table value="#{bindings.LoggedInUserServiceRequests.collectionModel}"
          var="row" ..>
  ...
  <af:column headerText="#{bindings.LoggedInUserServiceRequests.labels.Status}"
             sortProperty="Status" sortable="false">
    <af:outputText value="#{row.Status}"/>
  </af:column>
  <af:column
           headerText="#{bindings.LoggedInUserServiceRequests.labels.RequestDate}"
           sortProperty="RequestDate" sortable="false">
    <af:outputText value="#{row.RequestDate}">
      <f:convertDateTime 
           pattern="#{bindings.LoggedInUserServiceRequests.formats.RequestDate}"/>
    </af:outputText>
  </af:column>
  ...   
</af:table>

The table binding iterates over the data exposed by the iterator binding. The FacesCtrlRangeBinding class extends the base JUCtrlRangeBinding class to add specific methods to the base table binding object; one of the methods is the getCollectionModel method, which the EL accesses using the collectionModel property of the table binding. The table wraps the result set from the iterator binding in an oracle.adf.view.faces.model.CollectionModel object. As the table binding iterates, it makes each item in the collection available within the table component using the var attribute.

In the example, the table iterates over the rows in the current range of the ServiceRequestsByStatusIterator iterator binding. The iterator binding binds to a row set iterator that keeps track of the current row. 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 af:outputText tag:

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

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

Table 14-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 14.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 14.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 14.6, "Enabling Row Selection in a Table".