Bookshelf v7.5.2: Persistently Editable List Applets

Siebel Tools Reference > Physical UI Navigation and Templates > Applet Templates >

Persistently Editable List Applets

Edit List applets are shown in a persistently editable mode in views that use high interactivity. 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

Edit List mode renders list applets persistently editable. A list applet that is rendered in this mode can still be shown in the Edit mode by invoking the EditRecord method. Typically, the Edit List mode is used for editing the most commonly updated fields, and the Edit mode is used to edit the record.

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. A list applet in Edit List mode is shown in Figure 228.

To show list applets in Edit List mode

Add new controls for the applet that are required to support Editable Lists.

The editable list applets will be rendered in a view with the currently selected row showing editable fields as data entry (as opposed to read-only) controls. Users can change the values of these fields and then use a Save control to commit the changes to the database. To update another row, the user has to select that row, upon which the fields in the previously selected row return to read-only status and the fields in the newly selected row change to data entry controls. To obtain this behavior, the following two controls should be added to the list applet.

Control to Select a Row. This control should invoke the method PositionOnRow, and its HTML Row Sensitive property should be set to TRUE. This control appears once per row. (Refer to Current Record Selection in List Applets for more details.)

Control to Save a Row. This control should invoke the method WriteRecord, and its HTML Row Sensitive property should be set to TRUE. This should appear once for the entire list.

Mark the list columns that you want to edit in the list applet.

By default, all list columns in the list applet are editable in the Edit List mode if the business component allows updates to the field and if the Read Only property of the list column is not set to FALSE. However, having all columns editable is not recommended. Only the fields that would require frequent updates should be shown as editable. You still must provide an Edit Record link to edit all the fields in the record. To mark which columns in the list applet should not be editable when rendering the applet as an editable list, set the property HTML List Edit of the list column to FALSE (The default is TRUE).

Set the template to be used for rendering the applet in the Edit List mode.

In Tools, add a new Applet Web Template for the list applet, where the Type property is set to Edit List, and the Web Template is set to the template to be used for rendering the applet in this mode. Add the two controls mentioned above as Applet Web Template Items for this template.

NOTE: For an applet showing the Edit List mode, you do not need to specify a Base type template since the applet is never shown in the base mode. Also, you can share the same Web Template object between list applets in the Base and Edit List modes.

Map the list applet to the view template in the Edit List mode.

The View Web Template Item has a property called Applet Mode, which is used to specify the mode to be used for the applet when rendering the view. The default value is Base. To make the list applet editable in the view, set the value of this property to Edit List when mapping the applet in the View Web Template.

Sample List Applet Template

<table width="100%" cellspacing="0" cellpadding="0" border="0" align="center">

<swe:form>

...

<swe:list>



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

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

<swe:control id="147">

<td width="42" align="center" class="Row">

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

</td>

</swe:control>

<swe:select-row>

<td width="42" align="center" class="Row">

<swe:this property="FormattedHtml" />

</td>

</swe:select-row>



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

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

<td align="swe:this.TextAlignment" class="Row">

<swe:this property="FormattedHtml"

hintText="Field"/>

</td>

</swe:control>

</swe:for-each>



<swe:control id="142">

<td align="center" class="Row">

<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 are editable. Users can update multiple rows and then save all the records with one invocation of the SaveEditRecord 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 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 SaveEditRecord 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 the rendered 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 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" />

or

<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

Siebel Tools Reference, Version 7.5, Rev. A
Published: 18 April 2003