Widget styles

Many display characteristics of an individual widget depend on whether you include styles. The rules are as follows: :

You can reference a style class stored in a cascading style sheet (CSS):
- Every Rich UI application accesses the styles from the CSS file that resides in a Rich UI system project; at this writing, the project name is com.ibm.egl.rui. To access that CSS file, expand the WebContent folder and css subfolder. We advise you to leave the file untouched because updating it is likely to cause a maintenance problem over time.
- You can override and supplement the provided styles by maintaining your own CSS file. You make that file available to the Rich UI handler part in either of two ways:
  - You can set the part property cssFile, which accepts a path relative to the WebContent directory.
    Here is an example setting:
```
Handler ButtonTest Type RUIHandler 
   { children = [ui], cssFile = "buttontest/coolblue.css" }
```
    Here is an example CSS file:
```
.EglRuiGridTable 
{ border: 3px solid black; }  

.EglRuiGridHeader 
{ color:yellow; 	
  background-color:red;	 }  

.EglRuiGridCell 
{ color:black; 	
  background-color:aqua; } 
```
    Please note that if both the cssFile property and (as described next) the includeFile property are specified, the CSS content referenced by the cssFile property takes precedence.
  - You can set the part property includeFile, which also accepts a path relative to the WebContent directory.
    Here is an example setting:
```
Handler ButtonTest Type RUIHandler 
   { children = [ui], includeFile = "buttontest/coolblue.css" }
```
    For details on this option, see Rich UI handler part.
Each widget type provided in Rich UI names a style class for inclusion in the CSS. The class name has the following pattern, where WidgetTypeName is the widget-type name such as TextArea:
```
EglRuiWidgetTypeName
```
The purpose of this convention is to let a web designer establish the styles for each type of widget so that you can achieve consistency across applications.
Some widgets reference additional class names:
- The grid widget includes children that reference the style classes EglRuiGridTable, for setting the border style of the grid as a whole; EglRuiGridHeader, for setting characteristics of header cells; and EglRuiGridCell, for setting characteristics of body cells.
- If a textField widget is read only, the widget references the style class EglRuiTextFieldReadOnly
- If a passwordTextField widget is read only, the widget references the style class EglRuiPasswordTextFieldReadOnly
You can see the additional class names in the source for a given widget. Also, if you use the Firefox browser, you can use Firebug to inspect the styling of a displayed widget.
You can override a style class by setting the widget property class, as shown here:
```
loginBox	Box { numColumns=2, class="NormalBoxStyle" };
```
Here is an example of the related content in the CSS file:
```
.NormalBoxStyle 
   {  color:black; 	
      background-color:aqua; } 
```
All styles in the specified class are in effect in the widget. These styles are inherited in every enclosed widget except when a widget overrides a style, as noted later.
You can specify a style (or a set of styles) in the style property. Here is an example, which includes (in the property value) the syntax used in CSS files:
```
loginBox	Box 
   { numColumns=2,
     style="background-color:lightgreen;border-style:solid;" };      
```
All the CSS styles are available if you use the style property. However, for most purposes you can assign values to individual style-related properties. The following declaration is equivalent to the previous one and does not involve CSS syntax:
```
loginBox	Box 
   { columns=2,
     backgroundColor="lightgreen",
     borderStyle="solid" };      
```
Here are the EGL style-related properties:
- background
- backgroundColor
- borderStyle or one of the following subsets: borderLeftStyle, borderRightStyle, borderTopStyle, borderBottomStyle
- borderWidth or one of the following subsets: borderLeftWidth, borderRightWidth, borderTopWidth, borderBottomWidth
- color
- cursor
- font
- fontSize
- fontWeight
- height
- margin or one of the following subsets: marginLeft, marginRight, marginTop, marginBottom
- opacity
- padding or one of the following subsets: paddingLeft, paddingRight, paddingTop, paddingBottom
- pixelHeight
- pixelWidth
- position
- visibility
- width
Except for background, backgroundColor, borderStyle, cursor, font, and visibility (each of which takes a value of type STRING), each property takes a value of type INT and uses pixel as the unit of measure.
The styles in effect for a given widget are the sum of the styles specified in class and style specifications. In most cases, a style applied to a widget overrides the same styles inherited from enclosing widgets, and the last style specified in a list of widget properties overrides an equivalent style, if any, that was specified earlier in the list.
If, in defining a widget, you use both the style property or an equivalent property (to specify a given style) and the class property (to reference a class that includes the same style), the value in the style property takes precedence, in most cases.

If you do not specify styles, the default settings of the browser determine characteristics such as the line widths, the spacing between widgets, and the text font.

Best practice for styles

Rich UI projects are likely to be most successful if your company divides the responsibility for two tasks—laying out the user interface, as handled by an EGL developer, and creating the interface look and feel, as handled by a web designer. To make this division of labor possible, we recommend that you use external style sheets. You can rely on a default class name such as EglRuiTextField. Alternatively, you can assign your own class name by assigning a value to the class property for a given widget.

The effect of removing all children from the document body

Consider the following statement:

   document.body.removeChildren();

The effect is twofold:

Removes all children widgets from the web page
Removes access to the external style sheet, if any

If you wish to remove children from the document body without removing access to the external style sheet, remove specific children, as in the following statement:

   document.body.removeChild(myBox);

Sources of additional information

For details on cascading style sheets, consider the following websites:

http://www.w3schools.com/css

At this writing, the left side of that website includes several links, and the choices under the heading CSS Basic are of particular interest for Rich UI. The site search at the right is also useful.

For a complete description of cascading style sheets, see CSS: The Definitive Guide by Meyer (O'Reilly Media, Inc., November 2006).