Configuring the table component through a CSS file

How to load a CSS file in a table component

The table configuration can be split across several CSS files that you can load by:

Specifying a project file that lists the style sheets and the data file to be loaded in the component (see Loading a project file). The project file will be as follows:
```
<?xml version="1.0"?>
<tgo xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation = "ilog/cpl/schema/project.xsd" 
style="configurationFile1.css,configurationFile2.css">
  <datasource javaClass="ilog.tgo.datasource.IltDefaultDataSource" 
fileName="table.xml"/>
</tgo>
```
If the settings in two of the CSS files disagree, the effect depends on the order of the filenames in the list: the last file mentioned takes precedence over the first file.
Using the method IlpTable.setStyleSheets as follows:
```
tableComponent = new IlpTable();
try {
  tableComponent.setStyleSheets(new String[] {
                      myConfigurationFile1,myConfigurationFile2 });
} catch (Exception e) {
}    
```
If the settings in the CSS files disagree, the effect depends on the order of the filenames in the list: the last file listed takes precedence over the first one.

How to configure a table component in a CSS file

The following example shows you how you can customize the table component itself. It is based on the CSS file located in <installdir> /samples/table/styling/srchtml/table.css.html

where <installdir> is the directory where you have installed JViews TGO.

The configuration in CSS is organized as a set of rules that define properties.

// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Table Component configuration
// Type: Table
//
// This is the main selector when customizing
// a table component. It identifies the 
// sub-components that will be addressed in the
// CSS customization. In the Table Component, it
// is possible to customize the view, controller
// and adapter using CSS.
//
// List of available properties:
// - view: boolean
// - interactor: boolean
// - adapter: boolean
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Table {
  view: true;
  interactor: true;
}

The Table rule

This rule specifies the elements of the table component that will be customized. It contains Boolean flags that indicate whether some specific customizable properties are present. For example, the customization of the property adapter is not taken into account unless adapter: true is declared in the Table rule.

This feature provides powerful cascading possibilities. You can define adapter customizations in a default CSS file and turn them on or off in another CSS file.

The following CSS properties affect the table component:

CSS properties of the table component

CSS property	Type of value	Default	Usage
`view`	`boolean`	`false`	Enables the customization of the table view.
`interactor`	`boolean`	`false`	Enables the customization of the table interactors.
`adapter`	`boolean`	`false`	Enables the customization of the table adapter.

The View rule

This rule specifies the properties that are applied to the table view.

The following CSS properties affect the appearance of the table view:

CSS Properties of the table view

CSS property	Type of value	Default	Usage
`autoResizeMode`	IlpTableResizeMode	`AUTO_RESIZE_OFF`	Resize mode of the table. Possible values are: `AUTO_RESIZE_OFF` `AUTO_RESIZE_ALL_COLUMNS` `AUTO_RESIZE_LAST_COLUMN` .
`background`	`Color`	`null`	Color to be used in the background of the table view. By default, the color is gray.
`gridColor`	`Color`	`null`	Color to be used for the table grid.
`showGrid`	`Boolean`	`true`	Determines whether the grid is displayed or not.
`showHorizontalLines`	`Boolean`	`true`	Determines whether the grid horizontal lines are displayed or not.
`showVerticalLines`	`Boolean`	`true`	Determines whether the grid vertical lines are displayed or not.
`rowMargin`	`Integer`	`1`	Height in pixels of the margin between each row.
`columnMargin`	`Integer`	`1`	Width in pixels of the margin between each column.
`reorderingAllowed`	`Boolean`	`true`	Determines whether the user is allowed to reorder the columns of the table.
`fixedColumnCount`	`Integer`	`0`	Defines the number of fixed columns.
`headerRenderer`	IlpTableHeaderRenderer	IlpTableHeaderRenderer	The renderer used to perform the graphic representation of the headers of the table columns.
`defaultRenderer`	IlpTableCellRenderer	IlpTableCellRenderer	The renderer used to perform the graphic representation of the table cells.
`selectionMode`	IlpTableSelectionMode	`MULTIPLE_OBJECTS_SELECTION`	Selection mode of the table. Possible values are: `EMPTY_SELECTION` `SINGLE_OBJECT_SELECTION` `MULTIPLE_OBJECTS_SELECTION` `SINGLE_ATTRIBUTE_SELECTION` `MULTIPLE_ATTRIBUTES_SELECTION` `SINGLE_CELL_SELECTION` `MULTIPLE_CELLS_SELECTION`

How to configure a table view in a CSS file

Prior to configuring the table view, you need to configure the table component so that the view configuration is enabled:

Table {
  view: true;
}

Then, you can customize the view properties in the View rule as illustrated by the following code extract. Refer to The CSS specification in the Styling documentation for details about the CSS syntax.

View {
  reorderingAllowed : true;
  autoResizeMode : AUTO_RESIZE_OFF;
  selectionMode : MULTIPLE_OBJECTS_SELECTION;
  fixedColumnCount: 1;
}

Refer to IlpViewRenderer for more information.

The Interactor rule

This rule specifies the properties that are applied to the table controller. The following CSS properties affect how the table component handles mouse and keyboard events:

CSS Properties of the table interactor

Property name	Type	Default value	Usage
`viewInteractor`	IlpViewInteractor	IlpDefaultTableViewInteractor	Defines the interactor that handles events in the view.
`headerInteractor`	IlpDefaultTableHeaderInteractor	IlpDefaultTableHeaderInteractor	Defines the interactor that handles events in the table header.

Note

Events are only handled by the header interactor if the current view interactor is an IlpDefaultViewInteractor.

How to configure a table interactor in a CSS file

Prior to configuring the table interactor, you need to configure the table component so that the interactor configuration is enabled:

Table {
  interactor: true;
}

After that, you can customize the each interactor property in the Interactor rule as illustrated by the following code extract. Refer to The CSS specification in the Styling documentation for details about the CSS syntax.

Interactor {
  viewInteractor: @+viewInt;
  headerInteractor: @+headerInt;
}
Subobject#viewInt {
  class: 'ilog.cpl.table.interactor.IlpDefaultTableViewInteractor';
}
Subobject#headerInt {
  class: 'ilog.cpl.table.interactor.IlpDefaultTableHeaderInteractor';
}

The behavior of the view interactor is determined by the actions that are associated with user gestures and keystrokes. This behavior can also be customized through CSS. You can also configure a pop-up menu to be displayed in the table view or table header. For more information about interactor customization, refer to Interacting with the table view and Interacting with the table cells.

For more information, refer to IlpInteractorRenderer.

The Adapter rule

This rule controls the configuration of the table adapter. The table adapter is responsible for converting the business objects in the data source to representation objects (table rows) in the table component. It provides the following features:

Filtering: applies a filter so that business objects currently in the data source are not mapped to representation objects in the table component.
Accepted class: defines a specific class of business objects to be displayed in the table.
Excluded classes: defines a list of business classes whose business objects will not be displayed in the table.

These table adapter features can be customized through CSS using the following properties:

CSS properties of the table adapter

Property name	Property type
`filter`	`ilog.cpl.util.IlpFilter`
`acceptedClass`	`String`
`excludedClasses`	list of IlpClass
`representationObjectFactory`	`ilog.cpl.table.IlpTableRowFactory`

How to configure a table adapter in a CSS file

Prior to configuring the adapter, you need to configure the table component so that the adapter configuration is enabled:

Table {
  adapter: true;
}

After that, you can customize each adapter property in the Adapter rule as illustrated by the following code extract. Refer to The CSS specification in the Styling documentation for details about the CSS syntax.

Adapter {
  filter: @+tableFilter;
  acceptedClass: ’ilog.tgo.model.IltNetworkElement;
  representationObjectFactory: @+repObjFactory;
}

Subobject#tableFilter {
  class: MyTableFilter;
}
Subobject#repObjFactory {
  class: MyRepresentationObjectFactory;
}

How to programmatically configure a table adapter using CSS

You can programmatically modify the CSS configuration of the default table adapter ( IlpTableListAdapter) by using mutable style sheets through the IlpMutableStyleSheet API.

Important

The mutable style sheet is set to the adapter as a regular style sheet and is cascaded in the order in which it has been declared.

To use mutable style sheets:

Get the mutable style sheet.

You access the mutable style sheet through the getMutableStyleSheet() method in the table adapter API:
```
IlpMutableStyleSheet mutable = adapter.getMutableStyleSheet();
```
This method automatically registers the mutable style sheet in the adapter. You can manually instantiate an object of the class IlpMutableStyleSheet and register it yourself through the setStyleSheet() API:
```
IlpMutableStyleSheet mutable = new IlpMutableStyleSheet(adapter);
try {
  adapter.setStyleSheets(new String[] { mutable.toString() });
} catch (Exception x) {
  x.printStackTrace();
}
```
Set the CSS declarations.

Once you have the mutable style sheet, you can set the declarations you want:
```
mutable.setDeclaration("#myObjectId", "expansion", "NO_EXPANSION");
```
This creates the following CSS declaration into the mutable style sheet:
```
#myObjectId {
  expansion: NO_EXPANSION;
}
```
Register the mutable style sheet.

The mutable style sheet should be set as a regular style sheet for the adapter using the setStyleSheet() method:
```
try {
  adapter.setStyleSheets(new String[] { mutable.toString() });
} catch (Exception x) {
  x.printStackTrace();
}
```
Set and update the CSS declarations.

The mutable style sheet can be modified even after being registered to the adapter:
```
// Update the expansion type for 'myObjectId'
mutable.setDeclaration("#myObjectId", "expansion", "IN_PLACE");
// Add a new declaration
mutable.setDeclaration("#myOtherId", "expansion", "IN_PLACE");
```
Note

Like any style sheet, the mutable style sheet is lost when the setStyleSheet() API is invoked and a new set of style sheets is applied to the adapter.

How to customize the mutable style sheet

Reapplying a CSS configuration may be a heavy task, as the adapter may be forced to review filters, origins, recreate representation objects, and so on. It is important to use the mutable style sheet with care and to customize it properly to reapply the CSS wisely. To do so, there are two methods available in the IlpMutableStyleSheet API: setUpdateMask() and setAdjusting() .

setUpdateMask()

This method controls what should be recustomized once a declaration of the mutable style sheet has been updated. The CSS configuration of the adapter is divided into two parts: adapter customization and representation object customization.

The adapter customization handles the origins, filters, and so on:
```
Adapter {
  origins[0]: id0;
  origins[1]: id1;
  showOrigin: true;
  filter: @+myFilter;
} 
```
The representation object customization handles the expansion type of a representation object:
```
#myObjectId {
  expansion: IN_PLACE;
}
```
The accepted values for setUpdateMask() are:
- IlpStylable.UPDATE_COMPONENT_MASK : Only the adapter part is recustomized.
- IlpStylable.UPDATE_OBJECTS_MASK : Only the representation object part is recustomized.
- IlpStylable.UPDATE_ALL_MASK : Bot the adapter and representation object parts are recustomized.
- IlpStylable.UPDATE_NONE_MASK : Nothing is recustomized.
For example, if you update the expansion type of a representation object through the mutable style sheet, it is recommended that you set the update mask to UPDATE_OBJECTS_MASK as there is no need to reapply the CSS configuration for the adapter part:
```
mutable.setUpdateMask(IlpStylable.UPDATE_OBJECTS_MASK);
mutable.setDeclaration("object", "expansion", "IN_PLACE");
```
setAdjusting()

This method is used when a series of declarations must be applied to the mutable style sheet. When the method is set to true , the mutable style sheet puts all the calls to setDeclaration() into a queue. When the method is set back to false , all the queued declarations are processed in a batch:
```
mutable.setAdjusting(true);
mutable.setDeclaration("#myObjectId", "expansion", "IN_PLACE");
mutable.setDeclaration("#myOtherId", "expansion", "IN_PLACE");
mutable.setAdjusting(false);
```