Skip to main content
Matrix42 Self-Service Help Center

Multi Fragment Grid

Multi Fragment Grid settings and grid properties configuration examples.

Goal

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

Data type:  multi-fragment array.

The main purpose of the multi-fragment grid type is to display data that is stored as an array.  In this case, an array is a data structure that contains a group of elements which cannot exist as isolated data and are a part of an independent object of a higher level. For instance, offered in the catalog Service and a multi-fragment containing Service Ratings: the same service can have multiple records with service ratings that can be displayed to the application users in the multi-fragment grid.

Data sources: data can be retrieved and displayed by means of a multi-fragment grid from

  • configured in the Martix42 platform Configuration Items applying various filtering conditions before actually displaying data in the grid;
  • the Web Services connected to the Matrix42 platform. This data source can also be optionally configured and filtered before displaying data to the application users.

For more information about Grid Control types and use cases see Grid Controls page.

Prerequisites

Multi-fragment 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. Layout implementation type is based on the data from a Configuration Item or a Web Service.
  4. Data model: click "Customize" layout action and drag&drop an array with multi-fragment data from the Data Model section on the layout designer canvas. 

Multi-fragment grid is most often used in such layouts:

  • Dialog
  • Wizard
  • Preview
  • Landing page

Minimal required property settings

For proper grid displaying it is necessary to define the source of data retrieval to the grid and columns to show.

The following data model properties are minimum required for the grid displaying based on the layout implementation type

  • Data: records and entries to be displayed in the grid;
  • Class name or Column definition: columns displayed in the grid's header row.

The rest of the properties are assigned by default and can be optionally modified if necessary. Other properties define the add, edit, delete modes of the grid records and grid's look&feel.

Default Multi Fragment Grid characteristics

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

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

multi-fragment-default-grid1.png

Multi Fragment Grid: preview example with default grid characteristics

 

Properties and settings

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

Property group Property name Description Default Property setting example

Model

Data

Defines which data will be displayed in the grid.

Select necessary data of an array type which serves as a multi-fragment of the main object it belongs to (marked with square brackets):

multi_fragment_data_1.png

  1. Auto-suggested data model sources;
  2. Array data type marker.

Data field suggests data from the model of an array type only.

Selected array value acts as a raw data source that is filtered before displaying in the application's runtime according to the set Class name or Column definition property.

For proper multi-fragment grid displaying define interdependent Data and Class name or Column definition properties as well.

clipboard_e8bffd9980d0e128e57cc296f7ab85828.png

Class name

Defines which columns will be displayed in the grid and ensures proper data retrieval to the grid's heading row. 

Possible options:

  • leave empty if the data for the grid is retrieved from a Web Service;
  • select the class name from the suggested drop-down list.

The following example is applicable to the  Layout based on a Configuration Item implementation type:

Appropriate Class name for a multi-fragment grid is pre-filled automatically when the Data with array type is drag&dropped on the Layout Designer canvas from the Data Model:

multi_fragment_data_class_name.png

The selected class defines which columns will be displayed in the header of the grid. 

The system checks the following settings and displays columns based on the first available source:

a. Column definition field value; 

b. default Data query for the selected Class name;

c. Data Definition's Display expression field settings as each suggested Class name is actually a data definition with a set of configured for displaying columns (see Administration application  → Schema → Data Definition → Edit → Display expression field).

Selected Class name should match with the Data field, otherwise, no data will be retrieved to the grid.

For instance, both settings match as they are intended to retrieve time tracking entries : 

  • Data: SPSActivityTypeIncident.SPSActivityClassTimeTracking selected property will display all time tracking records related to an incident;
  • Class name: Time Tracking (SPSActivityClassTimeTracking)  selected property will show all column names describing time tracking records from the default Data query or Data Definition settings.
grid_class_name.png

Column definition

along with the Class name property,  Column definition defines a set of columns to be displayed in the grid, their search mode, sorting, graphics, showing data of a specific range or filtering and other settings defined in a particular Data query.

  • ❌  not specified: displayed columns are defined by a selected Class name. This option is possible when Configuration Item is the main source of the Data for the grid. If the main source of the specified Data field is a Web Service, the Column definition field is mandatory for proper data retrieval to the grid. 
  • specified: enter existing Data query name (see Administration application → User Interface → Data Queries). 

Column definition can be:

a. a single source of the grid's heading row data (Class name field is empty). In this case, make sure that the manually entered Data query name exists as there is no field validation. If the Data query does not exist the page with such grid will be blank and the system will result in an error message only during the application's runtime.

It is recommended to specify the Class name property unless the data retrieval is based on a Web Service. This will reduce cases when the changes made in the Data query affect the grid and the specified in the Data query source is no longer applicable, (e.g. binding other Data definition to a Data query). Specified Class name will serve as an alternative source for the displayed in the grid's heading row columns. 

b. specified along with the Class name: such properties combination allows to specify a custom Data query that has a specific configuration of the columns to be displayed and differs from the default Data query available for the selected Class name. 

grid_column_definition.png

Object Id

ID of the main object the multi-fragment belongs to. This option is used when there is more than one source of the main data objects. 

  • leave empty (default) if the layout is configured for a specific Object that is pre-defined by the layout implementation and there are no other objects that may cause an ambiguous data source;
  • specify Object ID in the Model tab to bind the multi-fragment grid data with the proper main object.

For instance, when configuring Wizard layouts the wizard may not have a unique and specific object or main data source like Dialog or Preview layouts which are based on the data from the Configuration Item.

Another case is when the additional Configuration Item is added as a data source to configured layout and it necessary to specify where the displayed and edited multi-fragment should belong to.

grid_object_id.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 create a new Calculated property data source of an Object type:

  1. In Data model  Context → Add property  Configure calculated property of an Object type:
    multi_fragment_current_item_create.png
  2. assign  Calculated property  to the  Current Item field:

multi_fragment_current_item_add.png

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.
grid_current_item_example.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.

help_tooltip.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.

label_localized.png

Localizable grid label example

clipboard_e4f726b9c875adbf6829cfffa769b9092.png

Show label

Check-box options:

  • disabled: the title of the grid is not shown. With enabled edit mode Add and Remove buttons are displayed in the heading of the grid as text
  • selected: display title of the grid. The title is set in "Label" field. With enabled edit mode Add and Remove buttons are displayed in the heading of the grid as icons
Disabled clipboard_e0da6a6ec8b063aa682bf127f8fc2b41f.png

Edit mode

Defines how the new record can be added and edited in the grid.

Available options of the drop-down list:

  • ❌ not selected:  grid's data cannot  be edited;
  • none: the same as not selected;

For proper functioning of the properties listed below, Edit mode field requires Appearance property "Disable Edit" set to any other option except for "Yes". 

When "Disable Edit" is set to "Yes" the listed below options of the  Edit mode field are ignored.      

  • inline: allows editing record data right in the grid by double-clicking the necessary field;
  • 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.
  • wizard: start typing wizard name for auto-suggestions and set additional properties for the wizard: 
    • Wizard Outer Context: specify a source from the data model (default available data from the data model or manually added and configured calculated property).  This property is intended to pass extra data that can be displayed in the wizard if configured.  
      Specified  Wizard Outer Context is available for configuration in the wizard's layout in the Context OuterContext Data Model source:wizard_outer_context.pngExample: a specific wizard is initially intended for processing time tracking entries. Additionally specified Outer Context takes some extra data that is related to the time tracking from the edited Incident like Incident's initiator/attachments/etc. and allows displaying this data in the wizard.   
    • Add item title: a source of the name or title of the add new record page. Can be retrieved from the data model, localizable field or set as a static value;
    • Edit item title: name or title of the edit grid record page. Can be retrieved from the data model, localizable field or set as a static value.

An alternative way to add records to the multi-fragment grid dynamically (programmatically)  is to add records to a grid via a Configured calculated property field without the need of creating a new record by filling out a form, inline record editing or via an external wizard.

clipboard_e5e189e359e11d353c9c804574dd78d36.png

Name

automatically generated name or identifier of the grid. 

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

auto-generated clipboard_e3e421a96f3fce9515504caf58a9271cb.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

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 source of the data model;
    • advanced model: 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");
    • standard buttons (export, columns displaying);
    • extra buttons (delete 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:

hide_grid_header_true.png

Grid preview with enabled Hide Grid Header property

Disabled grid_hide_grid_header.png

Margin

set property creates additional blank space outside of the borders of the element containing the grid.

Set control's margin in CSS format measured in px or rem:

  • '10px', '1rem'  (top, right, bottom, left);
  • '1rem 2rem' (top-bottom, right-left); 
  • '1px 2px 3px 4px' (top, right, bottom, left).
 

Padding

the property is used to generate additional blank space around the grid's content, inside of the borders of the element containing the grid. 

Set control's padding in CSS format  measured in px or rem:

  • '10px', '1rem'  (top, right, bottom, left);
  • '1rem 2rem' (top-bottom, right-left); 
  • '1px 2px 3px 4px' (top, right, bottom, left).
clipboard_e869acb008d0fdcd115e023a9deee4526.png

Flex option

intended to automatically adjust the width of the grid. Possible options:

  • fixed: grid width is static. The columns with data that did not fit in the grid's container fixed width can be scrolled.
  • flex: grid container width is responsive and adjusts automatically according to the user device's screen resolution
Fixed clipboard_e6d0fd8ddf9c92c0f571778ce340e2454.png

Disable Add

specify the mode of adding a new record to the grid.

The field depends on the Common Edit mode property settings. If Edit mode is not set or set to "No", the Disable Add property settings listed below are not applicable. 

  • ❌  none (default):  add button depends on and is defined by the  Edit mode property settings;
  • Static value: check-box options
    • disabled (false): Add new record button/icon is shown and a new record can be added;
    • selected (true): add button is not shown in the grid header and new records cannot be added.
  • Model: suggests boolean data options from the data model (true/false values). 
clipboard_efd2489dc46391e6ae5bdde32d7bddc5a.png

Disable Delete

specify the mode of deleting a record from the grid.

The field depends on the Common Edit mode property settings. If Edit mode is not set or set to "No", the Disable Delete property settings listed below are not applicable. 

  • none (default):  Remove button displaying depends on and is defined by the  Edit mode property settings;
  • no: Remove button or icon is shown in the grid's heading row and the records can be deleted from the grid;
  • yesRemove button or icon is not shown in the grid's heading row and the records cannot be deleted from the grid;
  • manual:  verify manually set conditions according to the specified field name.
    • Delete field name: specify a field name from a data model. The entered field must be of a boolean type as it acts as a condition that enables delete button (false) for a specific grid's entry or disables delete button if the result of the checked condition is true. The specified field can be a part of the already available data model options or added as an additional data source and is a calculated property of a boolean type.

Example: it is required to disable Delete button for all entries of the grid that have time tracking duration more than 15 minutes:

  1. Initially provided Data Model does not have a necessary field that validates such condition.
  2. Create a calculated data property within the multi-fragment data structure that should be validated:
    maual_del_1.png
  3. Use Advanced Mode tab to:

a. set custom field name;

b. choose boolean data type for a calculated property;

c. optionally set related data model source fields;

d.  specify the necessary condition as the JavaScript expression:
calc_property_disable_delete1.png

4. Manually assign the created field to Disable Delete properties:

canNotBeDeleted_assign.png

clipboard_ee0b2a33cf98022252a5bc7aaa4869fd1.png

Disable Edit

Grid records editing also depends on the  Common Edit mode property settings.

Available options:

  • none (default): field editing mode depends on the  Edit mode property settings;
  • no: grid entries editing is enabled;
  • yes: grid entries editing is disabled;
  • manual: verify manually set conditions according to the specified field name.  The functioning and the property configuration flow is the same as for Disable Delete manual property setting.
clipboard_ea60e87a66f9ffd860a3a38546da7570b.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.

grid_desktop_visibility1.png

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

Enabled clipboard_eb901040d88572e905a56dde0cd58b948.png

Tablet 

Enabled

Mobile

Enabled

 

  • Was this article helpful?