Data Grid Widget

DataGrid Widget

The DataGrid widget is a highly-configurable widget for displaying lists. DataGrid columns are sortable and sizeable by users. Each column in the DataGrid has its own properties that you can use to configure that column:

• Steps for Creating a DataGrid
• DataGrid Properties
• Properties for DataGrid Columns
• Display Types and their Editor Properties
• DataGrid Events

Steps for Creating a DataGrid

To use the DataGrid, follow these steps:

1. Drag a DataGrid widget onto the Page.
2. Click the binding property. The Binding dialog appears.
3. Under "Bind Targets" select the dataSet item in the DataGrid.
4. Under "Bind Sources", select the object to which you are binding the grid. The object must represent a list. Typically, you will use a Service Variable.
5. Add the columns. You can click autoColumns to have them built for you, or you can add columns manually by clicking the addColumn operation.
6. Use a column's field property to specify a specific field from the Grid binding for that column to display.
7. To size the columns, you can either click autoSize or use the columnWidth property to specify a precise width.

DataGrid Properties

The DataGrid widget has the following properties:

Common Properties

• name: the name that WaveMaker Studio uses to reference the widget. This is the name that appears in Model Tree, in the Page Builder, in Binding dialogs, and so on; this is also the name you use to reference the widget in code services.
• binding: defines the input dataSet for this DataGrid. The dataSet must be a list. Clicking the binding property launches a dialog for defining this input source (Tying Components to Data).
• showing: when checked (true), the widget is visible to users; when unchecked (false), the widget is hidden.

Layout Properties

• size: specifies the size of the widget. Before you can set the size, you first need to specify the units of size, which you do by setting the sizeUnits property.
• sizeUnits: specifies the units in which the size property is measured. If the autosize property is checked (true) then the sizeUnits property cannot be set. Default value is flex. Choices are:
  • px: pixels
  • em: text size; adapts automatically to current screen size
  • pt: point (1/72 inch)
  • flex: stretches widget to fill up proportional area of available space (see Setting Widget Size)

DataGrid Operation Properties

The DataGrid provides the following operations for configuring the grid:

• addColumn: allows you to manually add columns one at a time
• autoColumns: adds a column for each type returned so you don't have do it manually
• clearColumns: removes all columns from the grid
• updateNow: updates the grid with live data from the Service Variable while in design mode-no need to test run to see the data

Properties for DataGrid Columns

Each column in the DataGrid has its own properties that you can use to configure that column:

• name: the name that WaveMaker Studio uses to reference the widget. This is the name that appears in Model Tree, in the Page Builder, in Binding dialogs, and so on; this is also the name you use to reference the widget in code services.
• caption: specifies the column heading that is displayed to the user.

Layout Properties

• autoSize: if checked (true) this property sizes the widget so that it is just big enough for its contents and no bigger. If unchecked (false) the size of the widget is determined by the size property.
• columnWidth: width of the column as a percentage of the total width of the grid
• index: order in which the columns are displayed in the grid. Change the index to move columns left or right

Data Properties

• field: select the field you want displayed in the column
• display: defines the type of format (number, money, date, and so on.) See Display Types and their Editor Properties.
• format: opens the details property for configuring the format. See Display Types and their Editor Properties.

Columns Operation Properties

The DataGrid columns provide the following operations for configuring the grid:

• addColumn: adds a new column to the end of the Grid. Use the index property to move the column left or right
• removeColumn: removes the currently selected column

Display Types and their Editor Properties

Each DataGrid column has a display property. Set the display property to define the type of data you're displaying in the column. Once you set the display property, click the format property to further configure the column. The configuration options depend on the display type. In the list of format properties, click back to get back to the main properties. Possible values for the display property are described in the following sections:

• Default
• Number
• Date
• Time
• Date Time
• Money
• Link
• RegularExpression
• Evaluation

Default

Use to display text. No format properties are available for the default display.

Number

Use to display numbers. The digits format property determines the number of decimal places that are displayed in the label.

The locale format property represents language code, used for i18n. Based on locale setting, different data may be displayed. Possible values are:nls, de, en, n-au, en-ca, en-gb, es, es-es, fr, it, it-it, js, ko, ko-kr, pt, pt-br, zh, zh-cn

The round format property can be used to specify that the amount be rounded rather than truncated.

Date

Use to display dates.

The datePattern format property determines the format of the date. For example: MMM-dd-yyy

The formatLength format property determines the style of the displayed date:

• short - 12/15/2007
• medium - Dec 15, 2007
• long - December 15, 2007
• full - Saturday, December 15, 2007

Time

Use to display times.

The timePattern format property determines the format of the date. For example: HH:mm

The formatLength format property determines the style of the displayed time:

• short - 4:00 PM
• medium - 4:00:00 PM
• long - 4:00:00 PM Pacific Standard Time
• full - 4:00:00 PM Pacific Standard Time

Date Time

Use to display date and time.

The datePattern format property determines the format of the date. For example: MMM-dd-yyy

The timePattern format property determines the format of the date. For example: HH:mm

The formatLength format property determines the style of the displayed date-time:

• short - 12/15/2007 4:00 PM
• medium - Dec 15, 2007 4:00:00:00 PM
• long - December 15, 20074:00:00 PM Pacific Standard Time
• full - Saturday, December 15, 2007 4:00:00 PM Pacific Standard Time

Money

Use to display money.

The currency format property specifies the symbol to display before amount.

The digits format property determines the number of decimal places that are displayed.

The round format property can be used to specify that the amount be rounded rather than truncated.

The locale format property represents language code, used for i18n. Based on locale setting, different data may be displayed. Possible values are:nls, de, en, n-au, en-ca, en-gb, es, es-es, fr, it, it-it, js, ko, ko-kr, pt, pt-br, zh, zh-cn.

Link

Use to display a URL link. To specify the URL, use the link property in the format property list, rather than the link property in the main Property Editor.

RegularExpression

Use to format a column using a regular expression. Typically, you define a regular expression and replace anything that matches that expression with something else. You define the regular expression in the expression format property and the replacement value in the replace format property.

The expression format property specifies the regular expression to use for formatting. For example:

(^\d{3}).*(\d{2}).*(\d{4})

$1-$2-$3

The caseSensitive format property is checked (true) when you want the expression to be case-sensitive.

The global format property is checked (true) when you want to keep checking for the regular expression after the first match. It is unchecked (false) when you want to stop after the first match.

Evaluation

Use to format a column value.

The expression format property takes a dojo.formatter expression. For example, to format numbers using commas, you could use:

dojo.number.format($&)

To trim spaces from beginning and end of a string, you could use:

dojo.trim($&)

DataGrid Events

The following event properties are available for the DataGrid widget:

• onCellClick: fires when a single cell is clicked
• onHeaderCellClick: by default, when a user clicks on a header cell, the application performs a sort on the column. You can override by calling a custom service or custom JavaScript triggered on this event
• onSelected: fires when an entire row is selected
• onSetColumns: used for custom JavaScript on columns-fires when grid is rendered