List Builder FieldsClient-side Properties
Description
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.
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:
- value
The value of the field.
- data
The array of data for all rows in the List.
- rowNumber
Row number of the row being rendered (zero based).
- fieldName
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.
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.
Class
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:
javascript:myFunc(data)
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:
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:
csSummary['QTY'].total csSummary['PRICE'].avg csSummary['PRICE'].max
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:
data.LastName.startsWith("S")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:
data.LastName.startsWith("S")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.
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:
{DateOfBirth:date('MM-dd-yyyy')}or a numeric field, the template might be specified as:
{Price:number('$# ###.00')}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
1|Beverages 2|Condiments 3|Confections
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:
<listObject>.lookupvalue['category']
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:
<listObject>.resolveCodedValue(fieldName,fieldValue)
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.
Clicking the 
button next to the 'Numeric display format' property opens the Numeric Format Genie.
Videos
'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.
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.
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.