List Builder FieldsClient-side Properties


The Client-side fields settings control the appearance and functionality of field data in the list control on the client-side.

Control type

Specify the control type to use to display the data in the List. If you choose 'RawData' then the data is not wrapped in any HTML tags (such as span or img) and you must add your own html markup to the template. Use 'CSSIcon' if the data in the field is the name of a CSS font icon (such as Font-Awesome) or an SVG icon.

Fields in a List can be rendered as different control types, such as switches, maps, or button lists.

The Control type choices include the following:

  • Label

    Displays the value using the label control.

  • Image

    Displays the value as an image.

  • Video

    Displays the value using a video control.

  • Audio

    Displays the value using an audio control.

  • RawData

    Displays the raw data int he field.

  • CSSIcon

    Displays the value as a CSS icon.

  • Ink

    Displays the value using the Ink control.

  • Star Rating

    Displays a value using a star rating control. Tapping on one of the stars in the control will update the value in the List.

    For example, in the image below, the selected row in the List (which has an associated Detail View) was edited by tapping on a star and the List row is shown as dirty.

  • Switch

    Displays a value using a two state switch control.

  • Integer

    Displays an integer value with buttons to the left and right of the value to increment/decrement the value. You can display buttons that change the value by 1, 10, or 100.

  • Radiobuttons

    Displays a value using a button list. The control behaves like a radio button because only one value in the button list can be selected.

  • Checkbox

    Displays a value using a button list. The control behaves like a checkbox control because multiple values in the button list can be selected. The selected values are stored as a comma delimited list. For example, if the user selects the Red and Green buttons, the value stored in the List is Red,Green

  • Map

    Display a value using a Map. The value (which must be a comma delimited string with a latitude and longitude value) is shown as a marker on the map.

  • Javascript

    Allows you to define a Javascript function that returns HTML that is displayed in the List. The Javascript must be defined as a List method (i.e. it must be defined in the List builder on the Javascript pane). The method must take these input parameters:


    The value of the field.


    The array of data for all rows in the List.


    Row number of the row being rendered (zero based).


    The name of the field being rendered.

  • For example, the following JavaScript outputs the field name in bold followed by a colon and the field value:

    var html = "";
    html = "<b>" + fieldName + ":</b> " + value;
    return html;

In-line style

Specify the in-line style for the control. It is more efficient to use this property than the server-side in-line style because this property does not add to the amount of data that has to be sent from the server.

Word wrap

By default, when a long character value is shown in a List control the data in the list are truncated, not word-wrapped. The 'Word wrap' property allows you to turn on word-wrapping.

Example without word wrapping turned on.
The property setting's location in the List Builder
Example with word wrapping turned on

Word-wrapping option

Provides options for controlling how long text in a list column should be handled. By default, long text is truncated and ellipses are displayed to indicate that the text is truncated.


When you turn on word-wrap, you get a 'wordwrap option' property with these choices:

  • 'normal' - Sequences of whitespace will collapse into a single whitespace. Text will wrap when necessary.

  • 'nowrap' - Sequences of whitespace will collapse into a single whitespace. Text will never wrap to the next line. The text continues on the same line until a tag is encountered

  • 'pre' - Whitespace is preserved by the browser. Text will only wrap on line breaks Acts like the tag in HTML

  • 'pre-line' - Sequences of whitespace will collapse into a single whitespace. Text will wrap when necessary, and on line breaks

  • 'pre-wrap' - Whitespace is preserved by the browser. Text will wrap when necessary, and on line breaks

  • 'inherit' - Specifies that the value of the white-space property should be inherited from the parent element

  • 'break-word' - Allows long words that do not have spaces to be broken.

  • *none* - Turns word-wrap off.

You can turn on the word-wrap option for individual fields.


Specify the class for the field. If no class is specified, the default class from the component's Style will be used.

Show/hide expression

The expression is evaluated for each row. If the expression is true, the control will be shown. Use the special expression syntax, which will be converted automatically to Javascript.

If you prefer to enter a Javascript expression directly, prefix the expression with 'Javascript:'. Your Javascript expression will need to refer to field values using the 'data.' prefix. You can also call a Javascript function that returns true or false. For example:


Compute summary values

You can specify that client-side summary values should be computed for any column in a list.

To turn on client-side summary values for a field in the List, check the property shown below in the List builder:

For Lists based on SQL data, you can also specify server-side summary values. Server-side summary values are only different than client-side summary values if the List is paginated. Server-side summary values compute the summary based on the List query, whereas client-side summary values are based on the data that is currently loaded into the List. In the case of the paginated List, there can be many more records in the List query than are displayed in the List.

When you compute summary data for a List column, you will typically want to display the data on the UX component. The List's afterClientSideSummaryCompute event is useful for this. The fterClientSideSummaryCompute fires after the client-side summary values have been updated. In this event handler you can reference the summary data that was computed. Here are some examples of how your Javascript code can reference summary values:


The 'csSummary' object contains all of the summary data. The field name must be in uppercase and the summary type (total, avg, count, min, or max) must be in lower case.

You can also use a method of the UX object to read a List summary value using the following method:

{dialog.object}.getListClientSideSummaryValue(listName, fieldName, summaryType)

For example:

var tot = {dialog.object}.getListClientSideSummaryValue('list1','QTY','total');

Conditional style

Client-side conditional styles can be defined using the Conditional style property. These styles are computed at run-time on the client.

The Conditional style is applied to the field.

If you want to define a conditional style for the element that contains the field, use the Conditional cell style property.

The condition for a Conditional style rule is defined is defined using JavaScript syntax. For example:

data.Country == 'Canada' || data.Country == 'France'

Because the definition is defined using JavaScript, you can use JavaScript functions in your condition:


Conditional cell style

The Conditional cell style can be used to dynamically style the element in the List layout that contains the field. In a columnar layout, the element that contains the field is the table cell. In a Kanban or Freeform layout, the element that contains the field is the parent HTML DOM element that contains the field. This can be a div, span, or other HTML element in your layout definition.

If you want to define a conditional style for only the field, use the Conditional style property.

The condition for a Conditional cell style rule is defined is defined using JavaScript syntax. For example:

data.Country == 'Canada' || data.Country == 'France'

Because the definition is defined using JavaScript, you can use JavaScript functions in your condition:


Transform data type

Unless the List data source is a Javascript function (in which case you have complete control over the data types for each field in the List), all data in the List are string values.

Download Component

The 'Transform data type' property allows you to transform the data type of the data in a List column to a Date, Numeric, or Logical data type.

To transform the data type, set the option in the 'Transform data type' property on the Fields pane in the List builder (as shown below).


The benefit of transforming dates into true date objects and numbers into true number objects is that you can then use the template formatting options to format date or numeric values.

For example, the template for a date field might be specfied as:


or a numeric field, the template might be specified as:

{Price:number('$# ###.00')}
It is not required to transform a string to a number in order to use the number format directive in the template. The sample template shown above ( {Price:number('$# ###.00')} would actually also work on a string value that contained a valid number.

Date format

Specify the date/time format so that the date string can be parsed into a JavaScript date object. This property is only available if Transform data type is set to ToDate.

Decode value

The Decode value property can be used to transform a field that contains a code (e.g. 1, 2, 3) into a user-friendly value (e.g. "Fish", "Bread", "Apples").

In order to specify that a List field should be decoded, check the Decode value property.

Decode lookup list

If the Decode value property is checked, Decode lookup list will be shown in the property list. Decode lookup list is used to define the value to show for a given code.

The decode list can be based on static or dynamic values or a Javascript function. If the decode list is based on dynamic values, you can specify a database query, or a custom Xbasic function to get the values for the decode list.

The decode list is a CRLF delimited list of values of the form codedValue|displayValue


If a value cannot be decoded, the coded value is displayed.

When the List data are refreshed, the decode list is also refreshed (assuming that the decode list was defined to be dynamic).

The decode list is stored as a property of the List Object. For example, for a field called category, the decode list for this field would be stored in:


Where <listObject> is a pointer to the List Object.

For example

var lObj = {dialog.object}.getControl('list1');
lObj.lookupvalue['category'] = [
    {value: '1', html: 'Beverages'},
    {value: '2', html: '<b>Condiments</b>'},

Notice that the html property can be any HTML markup that you want.

After you modify a field's lookupvalue property you must refresh the List using the <listObject>.refresh() method.

  • Sorting Columns with Coded Value

    When you do a client-side sort on a column that has a coded value, the resolved values (as opposed to the raw values) are sorted.

  • Contrast Decode value with Lookup Columns

    Lookup Columns is similar to the Decode value in that both allow you to display a decoded value for a field in the List. Decode value is easier to use, however, because the decode list is part of the List definition. Decode value also does not add additional fields to the List.

  • Resolving Coded Values Programmatically

    You can resolve a coded value using this method of the List:


Date/time display format

A property in the 'Fields' pane in the List Builder allows you to set the client-side display format for date, date/time and short-time fields.


The builder for the 'Date/time display format' field allows you to set the format to:

  • <None>
  • <Default> or <Default - date part only> (applies only to date/time fields)
  • a custom format

If you choose 'none', no client-side formatting rule is applied. This means that the date/time values will be displayed using the regional settings on the server from where the UX is loaded. So for example, if the server is located in Switzerland where the date format is dd.MM.yyyy, then dates in the List will be displayed like this: 31.12.2016.

If you choose (or for a date/time field), the client side display format will match the setting for the 'Date format property' (shown below). This property is set on the Properties pane in the UX builder. This property can be overwritten at run-time by setting a session variable (__protected__clientSideDateFormat) at the time a user logs into your application.


Numeric display format

The List Builder allows you to specify a client-side display format for numeric fields without directly editing the template for the field. This method is easier than editing the template.

The Numeric display format property

Clicking the button next to the 'Numeric display format' property opens the Numeric Format Genie.

The Numeric Format Genie


'RawData' Control Type

The "RawData" control type returns the data "as-is" from the data source. No HTML mark up is automatically added, as is the case when you choose the "Label" or "Image" control type. Use the "RawData" control type when you want complete control over how the HTML for the field should be created. When you use the "RawData" control type, you must put the HTML markup in the template.

For example, say you have a field called "MyImage" that contains an Image URL. If you set the control type to Image, then in the template you would simply place this placeholder: {MyImage}

But if you set the control type to "RawData", the template would then be: <img src="{MyImage}" />


Displaying Data in a List using a StarRating Control

Many applications allow you to rate something by tapping on a star in a StarRating control. The UX component has a stand-alone StarRating control (accessed by selecting [More...] in the UX Builder Controls toolbox), but in some cases you might want to display data in a List control using a StarRating control.

In this video we show how this is easily done.

Download Component


Displaying Data in a List using Switch, Radio Button, Checkbox, Integer Increment and Map Controls

The UX offers several different control types that can be used to display data in the List. In this video we demonstrate several of the control types that can be used in a List.

Download Component


Decode coded Values

It is common when designing databases to use coded values for certain fields (i.e. a category field might have values of 1, 2, 3, etc. rather than Beverages, Condiments, Confectionary, etc.). When displaying the data in the List you might like to display the decoded value for each coded value. In this video, we show how this is easily done.