Bookshelf Home | Contents | Index | Search | PDF

Siebel Tools Reference > Special Behavior Supported by Templates >

Customizing Control Layout and Formatting

---

Siebel supports the use of several different control types out of the box (for example, Check Box, Button, Mail To, Text Area, and so on). However, there may be cases in which additional HTML types are needed. For this purpose, Siebel has provided a way for you to define your own HTML types by adding type definitions to the .SWF file.

Unlike cascading style sheets, which are used primarily to define general stylistic information about labels, titles, background colors, and so on, user-defined types in the CCHTMLTYPE.SWF file would normally be used to define more complex attributes that determine either the appearance or client-side functionality of a type of HTML element. Examples might include a button type that is associated with a particular GIF or a type of link that connects the user with an FTP site.

Again, these attributes could also be given to a page element by specifying the appropriate tags and attributes directly in the .SWT file. However, by defining them as types within the CCHTMLTYPE.SWF file, they can be referenced from within Siebel Tools for a specific control on a specific Applet Web Template or Web Page object. This preserves the generality of .SWT templates by avoiding the need to place HTML directly within them. It also improves the maintainability of the application by minimizing customization done to templates and storing more configuration information within the repository.

To create and use a new HTML Type

Add the name of the new type (for example, "MiniButton") to the List of Values used for the HTML Type property in Siebel Tools (REPOSITORY_HTML_CTRL_TYPE).
Add the formatting information for the new type to one of the application's two .SWF files. These files, which should use the extension .SWF, must reside in the same directory as the template files. One file contains the special types defined by Siebel; the other contains customer definitions, either to add additional types or to override Siebel types.

The format for rendering the custom type is specified by using two tags:

<swe:htmltype>
<swe:this>

The details of defining a new format are explained below, but for now, the form is as follows:

<swe:htmltype name="XXX" mode="AAA" state="BBB">

..... HTML .....

<swe:this property="YYY" />

.... More HTML ....

</swe:htmltype>

Specify the names of the .SWF files to be used by an application in the [SWE] section of the .CFG file used by the application's object manager.

[SWE]

SystemSWFName = CCHtmlType.swf

UserSWFName = MyFormat.swf // You must set this name.

In Siebel Tools, change the HTML Type property of the control, list column, or page item to the new type.
In the template file, use the FormattedHTML property for the <swe:control> or <swe:pageItem> element.

When SWE Uses a Custom HTML Type

If the HTML type of a control, list column, or page item is a custom type, the Siebel Web Engine will use the .SWF format when rendering any elements that are mapped to the control, and that specify the FormattedHtml property.

The following cases exist:

<swe:control id="1" property="FormattedHtml"/>
<swe:control id="1"> ... <swe:this property="FormattedHtml"/> ... </swe:control>
<swe:pageitem id="1" property="FormattedHtml"/>
<swe:pageitem id="1"> ... <swe:this property="FormattedHtml"/> ... </swe:pageitem>

The formatting will not be used with any other property, such as Display Name. However, in the .SWF file, the <swe:this> element can refer to these properties (except the FormattedHtml property itself).

More About Format

The .SWF files contain multiple format specs. Each format spec includes two parts:

An enclosing XML element that names the type and optionally names the mode and state in which the current format is used
The enclosed format content

The format content syntax follows these rules:

It must be valid, regular SWE syntax.
It may refer to all the properties of the current control, except "FormattedHtml" (in order to prevent recursion).
It may use a new swe:this property, "Data," which is explained below.

Examples

Example 1: To create a new HTML type for a control called "LabelRed" that shows the caption of the control in red, the formatting might look like this.

<swe:htmltype name="LabelRed">

<font color="red"> <swe:this property="DisplayName"/> </font>

</swe:htmltype>

Example 2: The Data property of <swe:this> is something like a macro that casts the current, custom type to one of the intrinsic types, and then inserts the FormattedHtml property of the intrinsic type. To use the Data property, you add an additional Type attribute to the <swe:this> tag, that names the intrinsic type. For example, to create a new type called "MiniButton," in which special formatting is added to the Web Engine intrinsic type Link, you might write a format something like this:

<swe:htmltype name="MiniButton">

<img SRC="images/btn_left.gif" border=0 height=15 width=2>

<swe:this property="Data" type="Link" />

<img src="images/btn_right.gif" border=0 height=15 width=2>

</swe:htmltype>

Here the <swe:this property="Data" type="Link" /> will output the same HTML as if the template included a separate <swe:this> tag, where the property was FormattedHtml, and the HTML type of the control were the built-in type Link.

You can only specify built-in types and not custom types for the type attribute of Data elements.

Example 3: You can also define custom formats for the different applet modes (Base, Edit, New, Query), by using the Mode attribute for the <swe:htmltype> tag. If a mode is specified, then that formatting is used only if the current show mode matches the value specified for this attribute. For example, if you want to create a new HTML type called SiebelText to show a control which displays as a label and a text field while in Edit template, and as read-only text in Base mode, you specify the format as:

<swe:htmltype name="SiebelText">

<swe:this property="Data" type="Text"/>

</swe:htmltype>

<swe:htmltype name="SiebelText" mode="Edit">

<swe:this property="DisplayName"/>:&nbsp;<swe:this property="Data" type="Text"/>

</swe:htmltype>

Example 4: You can define another optional attribute to the <swe:htmltype> tag, namely State, to show different formatting depending on the state of the control or list item. Currently Siebel Web Engine supports two states:

Disabled. For controls or list columns that invoke methods, where the method cannot be invoked on the record.
Required. For controls or list columns that are required.

For example, to show grayed-out buttons when a method cannot be invoked, add the following format definition in addition to the default definition shown earlier.

<swe:htmltype name="MiniButton" state="Disabled">

<img src="images/graybtn_left.gif" border=0 height=15 width=2>

<swe:this property="Data" type="Link" />

<img src="images/graybtn_right.gif" border=0 height=15 width=2>

</swe:htmltype>

With built-in HTML types, if a method cannot be invoked, then the control or list item is not shown (same as the current behavior). With custom HTML types, however, the formatting specified in the .SWF file is always shown. The HTML generated for the property Data (<swe:this property="Data" type="Link" />) when the method cannot be invoked is simply the caption of the control or list item without any <a href> tags.

You can hide a control or list item with a custom HTML type when a method cannot be invoked by creating an empty <swe:htmltype> tag for the Disabled state.

<swe:htmltype name="MiniButton" state="Disabled"></swe:htmltype>

NOTE:  This only hides the <swe:control> or <swe:this> tag that invokes the FormattedHtml property.

Example 5: To show the SiebelText type with an indicator (*) for required fields you can add the following format definition in addition to the definitions for this type shown earlier.

<swe:htmltype name="SiebelText" mode="Edit" state="Required">

*&nbsp;

<swe:this property="DisplayName"/>

:&nbsp;

<swe:this property="Data" type="Text"/>

</swe:htmltype>

NOTE:  When SWE looks up HTML Type definitions in the .SWF file, the order of precedence will be Mode and then State. It is recommended to always create a default format definition (that is, without specifying the mode and state attributes) for all custom HTML types.

Bookshelf Home | Contents | Index | Search | PDF