Skip to main content
Matrix42 Self-Service Help Center

Dynamic Grid

Overview

This how-to explains the basics of the Dynamic Grid settings and provides examples of the properties configuration.

The main purpose of the dynamic grid type is to display data that is dynamically uploaded, processed, parsed, and represented in the application like a spreadsheet. 

Use cases and data sources: 

  • data import: data can be retrieved and displayed by means of a dynamic grid from an external source, such as manually uploaded files, files from the LAN network, or available at a web resource. Data intended for displaying in the grid can come in different formats (.csv, .xls, .xlsx, .xml, .txt, MS SQL,etc.), therefore it is considered as dynamic as the source and the content varies for each specific case.
    An example of the dynamic grid configuration for the data import can be found in the out-of-the-box version of the Martix42 Administration application → Integration menu →  Import Import Definitions →  Create New Import Definition → Table Source Definition Step → Preview data from the import source is rendered to the dynamic grid
    The data retrieved to the dynamic grid can be additionally edited, extended, filtered, or deleted before being imported to the application's database and without modifying the data source file.
  • dynamic data displaying: data configured on one page of the application instantly affects the other. An example of such a case is a Pickup Data Definition settings in Administration application: Data Definition Attributes are added in the appropriate tab are immediately added as new columns of the dynamic grid of the Data tab:
     dynamic_grid_pickup_settings3.png
    Data displaying in the dynamic grid: Pickup Data Definition settings

 

Additionally, the application's Layout Designer allows configuring a number of settings that predefine the default look&feel and elements of the dynamic grid, while the represented content varies and depends on the input data source.

For more information about Grid Control type see also Grid Controls page.

Prerequisites

Dynamic grid is added and configured after the following steps:

  1. Administration application: open a Solution Builder;
  2. User Interface  Layouts: create new or edit existing layout;
  3. Toolbox: click "Customize" layout action and drag&drop the Dynamic Grid control descriptor on the layout designer canvas. 
  4. Proceed to the data configuration and define the minimum required properties

Dynamic grid can be used in such layouts:

  • Dialog
  • Preview
  • Wizard

Minimum required property settings

For proper grid displaying it is necessary to define the sources of the data that should be displayed in the grid.

The following data model properties are minimum required for the grid displaying:

  • Data: defines the data source for the grid's content;
  • Column: the source of the header row data.

dynamic_grid_min_settings.png

The rest of the properties are assigned by default and can be optionally modified if necessary. Other properties define the grid's header elements, multiple rows selection mode, edit, add and delete previewed in the grid data properties.

Default Dynamic Grid characteristics

By default, each dynamic grid with the configured minimum required properties results in the following page elements:

  • Column with a check-box for records multiple selection;
  • Columns data sorting order (ascending/descending);
  • Export data;
  • Column preview mode (show/hide specific columns);
  • Records scrolling (no pagination);
  • Read-only mode of grid data management.

dynamic_grid_default1.png

Dynamic Grid: preview example with default grid characteristics

 

Properties and settings

The table provides a detailed list of configurable dynamic grid properties, their settings, and particularities overview.

Property group Property name Description Default Property setting example

Model

Data

Defines the source of the data intended for display in the grid.

Data type: an array of data items.

dynamic_grid_data.png

Columns

Defines the source of the data heading columns. Is similar to the Data Query column definition, but is configured manually as described in Column property configuration section of this document. 

Data type: an array of data items. 

dynamic_grid_columns_control.png

Selected Items

optional property of a data model that acts as a variable. Allows passing the manually selected items of the grid to a specified data model field.

Additionally requires Enable Row Selection property set to true to enable multiple items selection column displaying in the grid.

dynamic_grid_selected_items.png

Current item

optional property of a data model that acts as a variable. Allows passing the data of a just clicked item of the grid to a specified data model field.

Select the necessary source from a list of suggested data model fields of an Object data type only or

  1. create a new Calculated property data source of an Object type :
  2. assign  Calculated property  to the  Current Item field:

Example: a row of a grid is edited using a wizard. Current item usage is as follows:

  • click on a record of the grid;
  • the system passes data from the row to an edit page. In this case, data is passed to the Current item;
  • modify data and introduce necessary changes. Changes are made to the field specified in the Current item;
  • save and apply changes. Data from the Current item is passed to the actual data structure of the grid.
dynamic_grid_current_item.png

Common 

Help

help icon and tooltip for information displaying as:

  • ❌  not set: help icon is not displayed;
  • static value: manually entered text displayed in a pop-up window. The text of the prompted message  is edited in a standard text editor and can include plain text, headings, links, and lists;
  • localizable:  plain text specified per each available in the system locale. Shows appropriate localized help message according to the currently selected by the user language profile settings;
  • model: displayed data is retrieved from a specified data model field.

dynamic_grid_help.png

Help icon with a tooltip displaying example

grid_help.png

Label

title of the grid. Can be set via one of the following options:

  • not selected:  grid title is empty and not displayed;
  • static value: manually entered title of the grid;
  • localizable:  grid title specified per each available in the system locale. Shows appropriate localized  title according to the currently selected by the user language profile settings;
  • model: displayed data is retrieved from a specified data model field.

dynamic_grid_label1.png

Localizable grid label example

clipboard_e4f726b9c875adbf6829cfffa769b9092.png

Inline mode

Check-box options:

  • disabled (default): grid item's editing in the inline mode is disabled;
  • selected: to edit a record double-click the field of the grid's data item:

dynamic_grid_inline_mode.png

Disabled dynamic_grid_inline_mode_control.png

Edit mode

Available options of the drop-down list:

  • none: grid's data cannot  be edited;
  • form: adds an area on a layout designer for configuring grid record editing form. In the application's runtime, this form is opened as a new page intended for a specific record editing only:
    Dynamic_grid_edit_form_layout_designer.png

None

dynamic_grid_edit_mode.png

Name

automatically generated technical name which serves as an identifier of the grid. 

The only required field for the grid saving, although without properly configured Data and Columns properties the entire grid is poorly displayed.

auto-generated dynamic_grid_name.png

Appearance

Full Height

Check-box options:

  • disabled: the grid takes only a part of the page's working area and shows 10 first records. Use scrolling for other records preview
  • selected: the grid preview expands and covers the entire available space of the page's working area.
Disabled grid_full_height.png
 

Minimal Height, px

defines the fixed height of the grid displayed on the page. 

Set and measured in pixels, for instance: "100".

The specified height is spread upon the entire grid representation, including grid's header with default buttons area (export, columns preview), grid heading row and displayed records data.

grid_minimal_height.png
 

Hide Export button

Check-box options:

  • disabled: export button is available in the grid's header. Additionally requires disabled Hide Grid Header property;
  • selected: export button is not shown in the grid's header.

dynamic_grid_export_button.png

Hide export button option is disabled

Disabled dynamic_grid_hide_export_button.png
 

Enable Row Selection

  • Static value: check-box options
    • selected (True):  the first column of the grid is a column with check-boxes for grid records multiple selection and further processing:dynamic_grid_enable_row_selection.png
      Enabled row selection displaying example: check-box option is set to true.
    • disabled (false): the first column with check-boxes is not displayed in the grid.
  • Model: suggests boolean data options from the data model (true/false values).
True dynamic_grid_enable_row_selection_control.png
 

Visibility

Grid display on the page modes:

  1. Static value: check-box options
    • selected (True): grid displaying on the page layout template is enabled; 
    • disabled (False): the grid is not shown on the page layout template.
  2. model:
    • assigned model: select the source of the data model resulting in boolean value;
    • advanced model: specify additional data processing and filtering conditions in JavaScript language.
True clipboard_ef748af5414dd44fb723697c41161887d.png
 

Hide Grid Header

Check-box options:

  • disabled: grid header is displayed on the page layout. The header includes:
    • the title of the grid ("Label", if enabled);
    • standard buttons (export, columns displaying);
    • extra buttons (remove the record, add new record).
  • selected: header is not displayed,  only grid heading row with sortable columns titles and the available in the grid records are shown:

dynamic_grid_grid_header1.png

Grid preview with enabled Hide Grid Header property

Disabled grid_hide_grid_header.png
 

Show add button

Check-box options:

  • disabled:  new items cannot be added to the grid. Add new data item button is not shown. 
  • selected: click the add button to create a new record in the grid. 

Selected option additionally requires:

  1. Set Edit Mode property to Form or enable Inline Mode for editing;
  2. Enable Row Selection property set to true to enable multiple items selection column displaying in the grid;
  3. disabled Hide Grid Header property.

dynamic_grid_add_button_inline _mode.png

Dynamic grid with enabled inline mode editing and selected show add button property

Disabled dynamic_grid_show_add_button.png
 

Show remove button

Check-box options:

  • disabled: data items cannot be removed from the dynamic grid;
  • selected: manually selected items of the dynamic grid can be deleted from the grid.  

Selected option additionally requires:

  1. Set Edit Mode property to Form or enable Inline Mode for editing;
  2. Enable Row Selection property set to true to enable multiple items selection column displaying in the grid;
  3. disabled Hide Grid Header property.

dynamic_grid_remove_button1.png

Disabled dynamic_grid_show_remove_button.png

Device visibility

Desktop

This property allows improving user experience by managing device visibility options. For instance, the grid can be hidden from the preview when it is too large and contains a lot of columns that cannot fit the small screen of a mobile device.

The application checks the user device's screen resolution and shows or hides grid preview based on the selected check-box options settings:

  • disabled: the grid is not displayed;
  • selected (default): the grid is shown on the page.

dynamic_grid_device_visibility1.png

Device visibility settings example: multi-fragment grid enabled for desktop devices only.

Enabled clipboard_eb901040d88572e905a56dde0cd58b948.png

Tablet 

Enabled

Mobile

Enabled

 

Column properties configuration

Data Query serves as s columns display source for such types of grids, like Objects grid, Object Relations grid. Data Query defines which data to show and how to show it according to the Data Query columns configuration. 

Dynamic Grid columns are not set by the selected Data Query, but are defined manually. The columns and values for the columns are set according to the described below rules and syntax.

You may use as Dynamic Grid Columns configuration reference an example from the default DWP installation:

 

  • For the internal properties configuration example, open Administration application → User InterfaceLayoutsDialogsData Definition Dialog → click Change Layout action to open the Layout Designer. In the Layout Designer, open Data view of the dialog → click on the Dynamic grid control on the canvas → click on the Columns property.
  • To see how the configuration looks in the user interface, go to Object State Data Definition in Administration application → open SchemaData Definition.

 

Colums value is an object of a Data Model that has been created according to the described rules and can be bound to the Columns value.

Minimum required properties

To retrieve a column to the dynamic grid add the following minimum required properties:

  • Name: a technical name of the data source attribute
  • Title: a name of the column that will be retrieved to the title of the dynamic grid and shown in the application UI.
return [ 
    {
        Name: 'catalogName',
        Title: 'Catalog Name',
    }
];

Type property

Type property defines the type of the data that is retrieved to the column.

By default, if the data Type is not explicitly set, the system applies string data type.

To redefine the data type, explicitly set one of the supported data types:

  • string (default)
  • icon
  • color
  • integer (see number)
  • number 
  • decimal
  • float
  • date
  • currency
  • boolean
  • enumeration
  • pickup

Add Type key to the minimum required properties, for instance: 

return [ 
    {
        Name: 'Visible',
        Title: 'visible',
        Type:  'boolean',
    }
];

The grid column will display a checkbox in the rows.

Below you will find some specific data types and examples.

Enumeration

Enumeration configuration differs based on the data source. 

Retrieving values from the database

Use this type if the column should suggest a value from the database, e.g. for choosing a country or a ticket status from a drop-down list.

To be able to choose a value and select it from the drop-down list set the Inline Mode to selected in the Dynamic Grid configuration.

Set minimum required properties (Name and Title), explicitly define type, and add the following properties:

  • ReferenceTo (mandatory) requires a class name or an internal name of a Data Definition of a pickup type that will be used as a source of the provided options you can choose from.
  • ReferenceFilter is an ASQL expression that filters the values of the Data Definition specified in the ReferenceTo property. 
  • ValuePropertyName: redefines the data source for the column. The value for the column will be searched and retrieved from the data source not by the Name property value, but using the ValuePropertyName. This property allows saving an additional property for the same column. For instance, ValuePropertyName holds the raw data from the data source, while Name, in this case, retrieves the display string of the attribute from the specified Data Definition (see ReferenceTo property). 

Example: 

return [ 
    {
      Name: 'stateGroup',
      Title: 'State Group Title',
      Type: 'enumeration',
      ReferenceTo: 'SPSCommonPickupStateGroup',
      ReferenceFilter: 'Hidden = 0',
      ValuePropertyName: 'State'
    }
];

dynamic_grid_enumeration1.png

Showing static data

Enumeration can also use as a source the data from the dialog or static data which is not stored in the database. 

To be able to choose a value and select it from the drop-down list set the Inline Mode to selected in the Dynamic Grid configuration.

Set minimum required properties (Name and Title), explicitly define type, and add the following properties:

  • Enumeration: specify an array of objects

For static data in the example below, the grid will show the title from the Enumeration property.

return [ 
    {
       Name: 'countryTitle',
       Title: 'Country Title',
       Type:  'enumeration',
       Enumeration: [{
            title: 'Germany',
            value: 3
       }],
    }
];

An array of objects from the calculated field value specified in the Enumeration property may look as follows:

return [ 
     {
        Name: 'сountryTitle',
        Title: 'Country Title',
        Type:  'enumeration',
        Enumeration: calcFieldName.$value,
     }
];

Calculated field property must return title and value as a part of an object, similarly to the example with static enumeration.

Object picker

Use object picker to retrieve data from the data source of a GUID type.

To be able to choose a value and select it from the object picker set the Inline Mode to selected in the Dynamic Grid configuration.

Set minimum required properties (Name and Title), explicitly define type, and add the following properties:

  • ReferenceTo (mandatory) requires a class name or an internal name of a Data Definition that will be used as a source of the provided options you can choose from. Here you can specify any Data Definition type except for the pickup Data Definition type.
  • ValuePropertyName: redefines the data source for the column. The value for the column will be searched and retrieved from the data source not by the Name property value, but using the ValuePropertyName. This property allows saving an additional property for the same column. For instance, ValuePropertyName holds the raw data from the data source, while Name, in this case, retrieves the display string of the attribute from the specified Data Definition (see ReferenceTo property). 
return [ 
     {
        Name: 'computerTitle',
        Title: 'Computer',
        Type: ‘pickup’,
        ReferenceTo: ‘PDRComputerClassBase',
        ValuePropertyName: 'Computer'
    }
];

With such configuration, the cell of the dynamic grid column will suggest you an option from the data source when you start typing its name and you can select one of the suggested values:

dynamic_grid_object_picker_example.png

Additional properties

To modify the column display, add and define the following properties to the column definition:

  • Width: column width defined in px;
  • Alignment
    • Left: 0
    • Center: 1
    • Right: 2
  • Sorting
    • None: 0 (default, the column data is not sorted, but you can click on the column title to apply ascending/descending sorting)
    • Ascending: 1
    • Descending: 2
    • Disabled: 4 (column data cannot be sorted)
  • SortingPriority: allows sorting by several columns at the same time. Specify the priority as a number, e.g. 10, 20, etc. For proper functioning, set the Sorting value for the column with SortingPriority. Both properties set the default sorting of the grid, i.e. when you open a page with the dynamic grid the data in the grid will be sorted according to the specified criteria by default. Further, you can change the sorting manually and reorder values according to your needs by clicking the title of the grid's column (if the Sorting is not Disabled for the column). 
  • DisplayType: another way to manage column visibility. Possible options are similar to the dialog settings:
    • Visible: 0. The column is visible on the grid by default 
    • InvisibleByDefault: 1.  The column is hidden in the grid, but column visibility can be changed in Grid Settings on the right side of the grid.
    • None: 2. The column is not present in the grid. The data for the column is not retrieved.
    • Hidden: 3. The column is not present in Grid, but the System returns column data to Client, and this data can be used for internal operations, e.g. filtering of the available Actions
  • Format: the Format property setups custom format for the data. For more examples see Data Query Page: Format property
  • Color: specify the code of the color, e.g. #FF0000. This property corresponds to the "Column Background Color" of the Data Query configuration. It has a higher priority than the ColorScript configuration.
  • ColorType: is similar to the "Use Color For" property of the Data Query configuration. Possible values:
    • None: 0,
    • CellText: 1,
    • CellBackground: 2,
    • RowText: 3,
    • RowBackground: 4
  • ColorScript: Javascript expression that configures the color of the Cell Text / Cell Background / Row Text / Row Background set in ColorType. The expression can return either the code of the color, e.g. #FF0000, or the whole definition of the CSS style, like 'font-weight:bold'. As well as for the Image Script, it is possible to use variables $item and $value to specify the logic. 
    See the Graphics Configuration section of the Data Query page for more information.
  • ImageScript: a Javascript expression that returns the reference to the image. An image can be represented by the name of the available SVG icon, or just a relative or full URL to the image. You can operate with two variables in Script to specify the logic, $item - represents the whole data in grid row, and $value - value of the column where the Image script is defined. See the Graphics Configuration section of the Data Query page for more information.
  • DisplayImage: is similar to the “Display Image" property of the Data Query configuration. Possible values:
    • None: 0
    • Image: 1
    • ImageWithText: 2

Example:

return [ 
     {
        Name: 'Date',
        Title: 'StartFrom',
        Type:  ‘date',
        Alignment: 1,
        Sorting: 2,
        DisplayType: 3,
        Width: 100
     }
];

The listed properties are common for all data types

  • Was this article helpful?