Bookshelf v7.7: About List Applet Templates

Configuring Siebel eBusiness Applications > Overview of Web Templates and Siebel Tags > About Siebel Templates >

About List Applet Templates

Standard list applets allow simultaneous display of data from multiple records. The standard list displays data fields in a multi-column layout with each record of data represented in a row. In addition to textual data, lists also support images in JPEG and GIF formats and edit controls such as check boxes, drop-down lists, MVGs, and text fields.

A single row at a time within the standard list applet is selected for editing by clicking in the far left column selection area. When selected, the fields within the row can activate either input or edit controls. Clicking the New button creates a new row with a series of blank fields for the user to populate.

Persistently Editable List Applets

Edit List mode renders list applets as persistently editable. The purpose of an editable list applet is to allow users to modify the records in a list applet without switching to an edit page.

The editable list applet has the following features:

Editable cells displayed as text input, list box, or mini-buttons
Modified records that can be saved individually

A given list applet exhibits different behavior and appears differently depending on whether it is part of a view being displayed using standard or high interactivity:

In standard interactivity, there is a row selector control that allows the user to select a specific row for editing. When selected, the fields within the row can activate either input or edit controls. Clicking the New button creates a new row with a series of blank fields for the user to populate.
Row selection using high interactivity is done by clicking on any area within a row in the list. Therefore, the row selection is redundant, and the control is automatically deleted when the list is rendered. Also, because high interactivity uses an implicit save model, a Save control is not required. When a user steps off the current record, the changes are automatically saved.

Sample List Applet Template

<swe:form>

...

<swe:list>

<!-- List Header Section Start>

<swe:control id="147">

<swe:this property="DisplayName"/>

</td>

</swe:control>

<swe:select-row>

</td>

</swe:select-row>

<swe:for-each startValue="501" count="20" iteratorName="currentId">

<swe:control id="swe:currentId">

<swe:this property="ListHeader"/>

</td>

</swe:control>

</swe:for-each>

<swe:control id="142">

<swe:this property="DisplayName"/>

</td>

</swe:control>

<!-- List Header Section End>

<swe:for-each-row count="7">

<swe:control id="147">

<swe:this property="FormattedHtml" hintMapType="Control"/>

</td>

</swe:control>

<swe:select-row>

<swe:this property="FormattedHtml" />

</td>

</swe:select-row>

<swe:for-each startValue="501" count="40" iteratorName="currentId">

<swe:control id="swe:currentId">

<swe:this property="FormattedHtml"

hintText="Field"/>

</td>

</swe:control>

</swe:for-each>

<swe:control id="142">

<swe:this property="FormattedHtml" hintMapType="Control"/>

</td>

</swe:control>

</tr>

</swe:for-each-row>

</swe:list>

...

</swe:form>

</table>

Tags that typically appear in a list applet template include swe:form, swe:list, swe:control, swe:select-row, and swe:for-each-row.

<swe:form>
As with form applets, this tag encloses an editable section. It is therefore used for editable list applets.
<swe:list>
This tag encloses the section of the template that contains the list header and body. For applications that use high interactivity, the section between the start and end of the swe:list tags is replaced by the specialized List Control that supports capabilities such as resizing columns, and so on. This tag is ignored for standard interactivity applications.
<swe:control>
This tag defines a placeholder for List Columns. The property attribute takes the same values as in the case of form applets - DisplayName for the Display Name attribute of the list column object, FormattedHTML for the data value. In addition, certain attributes of a list column object can be used to control the attributes of an HTML element contained within the enclosing swe:control tag. For example, the align attribute of a contained TD tag can be set to be equal to the Text Alignment property of the enclosing list column as follows:

<td align="swe:this.TextAlignment">
<swe:select-row>
This tag is used to render check boxes for selecting a row for the purposes of multi-selection. This is described in greater detail in the section on multi-select lists.
<swe:for-each-row>
This tag encloses the section of the template that is to be repeated for each list row.

Current Record Selection in List Applets

The Web client has a feature that allows users to select a record as the currently active record in a list applet in the Base and the Edit List modes.

NOTE: This applies only to standard interactivity applications. For high interactivity applications, row selection is achieved by clicking anywhere within the current row.

To select a record as the currently active record

Add a control to all list applets that invokes the method PositionOnRow.
The HTML Row Sensitive property of this method should be set to TRUE.
Place this control on the list applet where you want the link to select the row. You are able to select the record by clicking on this link.

SWE provides two options to show the currently selected record. These options can be used together or individually:

You are able to specify the formatting to be used for the currently selected row.
This feature is based on changing the CSS style sheet class associated with a row (for example in a <TR> tag) to specify different formatting information. You can associate a list applet with a named style to be used for formatting its rows. You can define this attribute in the cfg file used by the application under the SWE section. (This is currently limited to all list applets used by an application so they have the same row formatting style.)

ListRowStyle = "Siebel List"

You can specify any name for the row style. The actual style sheet classes used by this named style is specified in a new file type called the Siebel Web Style file (similar to the Siebel Web Format file used for custom HTML types). The Siebel Web Style files (SWS files) will have the extension .sws, and should be installed in the same folder as the template files.

As in the case of the SWF files, the SWS files used by an application are specified in the .cfg file of the application. There are two parameters that define the SWS file. One defines the file defined by the Siebel application teams and the other the file that can be defined by customers to either override the styles specified by the application teams or to add new styles. The parameters should be defined in the SWE section of the cfg file.

SystemSWSName = CCStyles.sws

;UserSWSName = // for customer use only

In the SWS file you can define the style sheet classes to be used with a named style using two new SWE tags and conditional tags like <swe:if> or <swe:switch>. These tags are described as follows:

swe:style
Usage: <swe:style type="XXX" name="YYY">

Attributes:
- type. Currently supports only one value which is RowStyle. Other values will be supported in the future.
- name. Name of the style (like Siebel List)
  swe:class
  
  Usage: <swe:class name="XXX"/>
  
  Attributes:
  
  name. Name of the CSS style sheet class. The style sheet that defines this class should be loaded through the template.
  
  The following is a sample entry in a SWS file that will achieve the same formatting as the conditional tags that were put in the template file using the earlier approach:
<swe:style type="RowStyle" name="Siebel List">

<swe:switch>

<swe:case condition="Web Engine State Properties, IsErrorRow">

<swe:class name="listRowError"/>

</swe:case>

<swe:case condition="Web Engine State Properties, IsCurrentRow">

<swe:class name="listRowOn"/>

</swe:case>

<swe:case condition="Web Engine State Properties, IsOddRow">

<swe:class name="listRowOdd"/>

</swe:case>

<swe:case condition="Web Engine State Properties, IsEvenRow">

<swe:class name="listRowEven"/>

</swe:case>

<swe:default>

<swe:class name="listRowOff"/>

</swe:default>

</swe:switch>

</swe:style>

In the template file used by the list applet, the conditional tags used earlier should be replaced with a new property of the applet called "RowStyle" that can be set to the class attribute of any HTML tag. The format used for specifying the RowStyle property of the list applet is similar to that used for specifying the TextAlignment property of a list column.

<swe:for-each-row count="7">

<tr class="swe:this.RowStyle">

<swe:for-each startValue="501" count="20" iteratorName="currentId">

<swe:control id="swe:currentId">

<td align="swe:this.TextAlignment" class="Row"><swe:this property="FormattedHtml" hintText="Field" hintMapType="ListItem"/></td>

</swe:control>

</swe:for-each>

</tr>

</swe:for-each-row>

You can use the PositionOnRow control itself to distinguish between the selected and the unselected rows. Once a row is selected, the PositionOnRow control on that row will be in a disabled state. So you can use different images for the disabled and enabled state of the control to differentiate between selected and unselected rows.

Multi-Row Editable List Applets

This is an extension to the Editable List Applet capability. By default when an applet is rendered in the Edit List mode in a view, only the currently selected row is editable. To edit other rows, you need to save the current changes and then select the next row to edit.

It is also possible to render list applets in Edit List mode where all the rows can be edited. Users can update multiple rows and then save all the records with one invocation of the WriteRecord control.

To make a list applet support multi-row edits in Edit List mode, set the HTML Multi Row Edit property of the List object in Siebel Tools to TRUE. The default for this attribute is FALSE. All the other steps are the same as for the regular Edit List mode.

NOTE: You do not need to place the WriteRecord control on each row. Only one such control is required for the applet.

There are certain limitations around the usage of this feature:

If an error occurs while committing any of the records, the Siebel Web Engine will try to commit as many of the records that it can and will report errors on all the failed records. However, the error messages may not have sufficient information on which rows failed.
Changes in the current working set must be committed before you can navigate to another working set (in other words you need to save your changes before calling GotoNextSet, GotoPreviousSet, and so on).

Because of these limitations, this feature should be used only in cases where these limitations will not cause a significant impact on the application's usability.

Hence this feature should be used only when the following conditions are met:

Validation errors in the editable fields of the applet can be caught with client side validation (using the Browser Script).
Only one user will be updating the records of this applet at any given time.
The number of records in the list applet are small enough that they can be rendered on a single page without the Next or Previous controls.

A good example of the use of this feature is to update the Quantity field in the Shopping Cart applet.

NOTE: This feature is specific to standard interactivity applications. Applications that use high interactivity commit implicitly as you navigate between rows of a list applet. You can edit any row of a list applet, and as you proceed these changes will be committed to the database.

Multi-Record Select List Applets

Multi-select list applets provide a way to select multiple items for a transaction. The check boxes in the left column are used to select the items. The Select All button allows the user to select all available records in the list. The Select action button selects all of the records that have been chosen for inclusion in the selection.

This feature is specific to standard interactivity applications. In applications that use high interactivity, multi-row selection is available in all list applets rendered using the <swe:list> tag, except for pick applets. In these applets, multiple rows can be selected using the Control/Shift keys, as in any standard Windows application

The Siebel Web Engine supports the selection of multiple records in list applets for invoking methods that act on these selected records. With the HTML Client the selection of rows is done using check boxes that are placed on each row.

This is different from positioning the current record using the PositionOnRow control. You can have both the PositionOnRow control and Multiple Row Selection on the same list applet.

When you initially navigate to a list applet, the record on which the bus comp is positioned is automatically selected. Users can unselect this using the check box if desired. Unlike PositionOnRow, when you select rows using the check box there is no server round trip. The selected records are marked as selected on the bus comp only when a method is invoked on the applet. You can select records across multiple pages (that is, you can navigate using the Next and Previous controls and select records from different working sets).

By default, multirecord selection is not enabled for list applets. To enable this feature on list applets where this needs to be supported, set the new attribute of the List object in Siebel Tools called HTML Multi Row Select to TRUE.

To render the check boxes to select multiple rows in list applet templates, the tag <swe:select-row> is used. The syntax of this tag is:

<swe:select-row property="FormattedHtml" />

<swe:select-row>

<swe:this property="FormattedHtml" />

</swe:select-row>

When the property attribute is set to FormattedHtml in either the <swe:select-row> or <swe:this> tag, the check box will be rendered if the applet is enabled for multirecord selection in Tools. When <swe:select-row> tag is used without the property attribute, it acts as a conditional tag to show its body if the applet is enabled for multirecord selection.

By using this tag, you can create a generic list applet template that can be used with list applets that support multi-record selection and those that do not. In the list header, use the <swe:select-row> tag conditionally to put in a <td> for the header for the row selection check box column, and in the list body use the <swe:select-row> tag along with the <swe:this> tag conditionally to put in a <td> that contains the check box.

NOTE: You must place your list applet controls/list columns within a <swe:form> tag when you enable the multi-select feature, as any invoke method on the applet requires the form which contains the row selection check boxes to be submitted.

Controls that do not support invoking methods when multiple records are selected are not disabled when the user selects multiple records since there is no server call when selecting multiple records. Instead, when the control is activated a message will be shown to the user that the action cannot be performed when multiple records are selected.

Configuring Siebel eBusiness Applications