How to customize grid colors

You can customize the background color of grid rows or columns in the List controller in several ways, depending on the complexity of your needs.

Fixed color in a column

The following example defines yellow as background color for the email addresses column:

EMailAddress:
  Color: yellow

A more flexible way is using the CSS node:

EMailAddress:
  CSS: background-color: yellow;

In this case the result of the two pieces of code is the same, but with the CSS node you have the possibility to fully customize the column styling (for example you can choose a color for text).

Colors based on custom conditions

The easiest way is to define a Colors subnode at the model field or view field level (view field level, as usual, has precedence). The following example defines yellow as a color for rows in which the EMailAddress field matches the given regular expression, and red for all other rows.

EMailAddress:
  Colors:
    FFFF00: ^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,4}$
    FF0000: .*

If the ViewTable (or underlying Model) has more than one field with a Colors subnode, then the first one is used, unless you also specify RowColorField at the controller level:

Controller:
  RowColorField: EMailAddress

The above settings allow you to colorize rows based on pattern matching of single field values.

RowClassProvider (JavaScript function)

For the most flexible row coloring, you can define a RowClassProvider in the MainTable/Controller node. This is a JavaScript function expression that receives a record object and returns a CSS class name. The API is compatible with Kitto^x 1.

First, define your CSS classes in Home/Resources/js/application.css:

.important-row {
  background-color: #FFB2B2;
}

.semi-important-row {
  background-color: #FFEB99;
}

Then, define a helper function in Home/Resources/js/application.js:

function getAgeClass(age) {
  if (age >= 15) {
    return 'important-row';
  } else if (age >= 12) {
    return 'semi-important-row';
  } else {
    return '';
  }
}

Finally, reference it in your view YAML:

MainTable:
  Model: Girl
  Controller:
    RowClassProvider: function (record) { return getAgeClass(record.get('Age')); }

The record object provides:

Method / Property	Description
record.get('FieldName')	Returns the value of the field (number, string, boolean, or null)
record.data	Object with all field values as properties

The function should return a CSS class name (string), or an empty string for no special styling. Multiple classes can be returned separated by spaces. Rows with a custom class automatically bypass the grid's zebra striping so the custom background is always visible.

You can also add a legend panel to explain the colors to the user. In this example, an EastView HtmlPanel is used:

Controller: List
  EastView:
    Controller: HtmlPanel
      Html: |
        <div style="padding:4px 8px; margin:2px 4px">Age under 12</div>
        <div class="semi-important-row" style="padding:4px 8px; margin:2px 4px">Age between 12 and 15</div>
        <div class="important-row" style="padding:4px 8px; margin:2px 4px">Age over 15</div>
      Border: True
      Collapsible: True
      Header: True
      Title: _(Legend)
      Width: 180

Note: RowClassProvider is evaluated client-side after each data load (initial render, sorting, paging, filtering). The application.js file is automatically included in all pages.

RowClassProvider on GroupingList

RowClassProvider also works on the GroupingList controller. The class returned by the function is applied to each data row and to the <tr> of the group header, so the group heading can visually match its rows at a glance (e.g. an entire group of overdue records can appear red from the collapsed header alone, without having to expand it).

The classification of the group header uses the first record of the group as input to the JS function. Since all records of a group share the same value for Grouping/FieldName, any function that depends only on that field returns a constant class across the group — which is the common case and why the header matches perfectly. If the function depends on fields outside the grouping column, the header takes the class of the first record (a stable but arbitrary convention).

Example — members grouped by family tax ID, rows coloured by a hash of the family key:

Type: Data
Controller: GroupingList
MainTable:
  Model: MembroFamiglia
  Controller:
    Grouping:
      FieldName: Famiglia
      SortFieldNames: Famiglia Nominativo
    RowClassProvider: function (record) { return getFamilyGroupClass(record.get('Famiglia')); }

function getFamilyGroupClass(codFisc) {
  if (!codFisc) return '';
  var h = 0;
  for (var i = 0; i < codFisc.length; i++) h += codFisc.charCodeAt(i);
  return (h % 2 === 0) ? 'family-group-even' : 'family-group-odd';
}

.family-group-even { background-color: #d4f4dd; }
.family-group-odd  { background-color: #f4d4dd; }