Grid Component

Estimated Reading Time:  13 minutes

Overview

The Grid component is a powerful tool that lets you gather, organize, and display data in your application. Using the Grid, you can retrieve data and customize how it displays. You can also use Grid operations that give end-users End-Users are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. the ability to dynamically modify the way they see your Grid data.

Like the Panel or Field Group components, the Grid component acts as a grouping or storage component for fields (other components) configured inside it. Instead of creating self-contained pages or sections, the Grid uses the component fields to create table headers. You can add any Unqork component to your Grid, but each component behaves differently depending on the view settings of your Grid component.

Common ways you can use the Grid component include: 

  • Collecting, editing, and displaying data from different sources on a single screen, such as a dashboard.

  • Displaying dynamic data that end-users can manipulate using Grid Operations.

  • Applying logic (rules, calculations, procedural operations, and so on) to multiple data records simultaneously.

You can find the Grid component under the Display & Layout group to the left of the Module Builder.

What You'll Learn

After completing this article, you’ll know when to use a Grid component, how to configure its settings and operations, and how to use it in an Unqork application.

Grid Operations

Grid operations are the actions the Grid performs. These actions include filtering, appending, hiding, transposing, sorting, and so on.

Instead of running operations in the Grid component, logic components control and trigger the Grid operations.

Each Grid operation holds key/value pairs called options. For each Grid option key, enter the relevant option value to customize how your Grid operation performs. For example, the GRID.SET_FILTER Grid operation filters columns in the Grid component. The GRID.SET_FILTER Grid operation use the column option key/value pair to select the column component the Grid operation will filter. So, if the component column Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. is status, the key/value pair will be "column": "status".

NOTE  Each Grid operation contains a unique set of Grid options. The first table below shows the Grid key options you can use for each Grid operation. The second table shows you which Grid option values you can enter for each Grid option key.

To control and trigger Grid operations within logic components, use a new Outputs Enter outputs components and actions you want the component to perform. Type called GRID_OPERATION. For the logic component's Outputs Value, enter the operation and options you want your Grid to perform.

Here is the basic template for entering and operation and its options:

Copy
{
"type": "OPERATION_TYPE",
    "options": {
        "inputs": [{"targetKey": "enter target key", "alias": "enter alias numeral"}], "targetKey": "enter Grid propertyID", "Option": "enter Option value"
  }
}

NOTE  The "inputs" Grid option isn't used in every Grid Operation. When not used, begin with the "targetKey" option.

Here are the Grid operations you can use to control your Grid component:

Operation Type

Description

Option Keys

Example Operation

GRID.SET_FILTER

Filter one or more columns in the grid.

{ “type”: “GRID.SET_FILTER”, “options”: { “targetKey”: “grid”,"global": "true", “value”: “Auto”, “column”: “type”, “mode”: “toggle”, “type”: “includesString” } }

GRID.SET_COLUMN_VISIBILITY

Show/hide a column.

  • column

  • value

    • VISIBLE

    • HIDDEN

    • TOGGLE

{ "type": "GRID.SET_COLUMN_VISIBILITY", "options": { "targetKey": "grid", "column": "status", "value": "TOGGLE" } }

GRID.SET_SORT

Set the sorting status of a column.

{ "type": "GRID.SET_SORT", "options": { "inputs": [ { "targetKey": "sortBy", "alias": "A" } ], "targetKey": "grid", "column": "=A", "direction": "asc" } }

GRID.SET_TRANSPOSED

Set the transposed state of the grid.

value

  • TRANSPOSED

  • STANDARD

  • TOGGLE

{ "type": "GRID.SET_TRANSPOSED", "options": { "targetKey": "grid", "value": "TOGGLE" } }

GRID.SET_VIEW_TYPE

Set the view type of a grid.

value

  • form

  • spreadsheet

  • TOGGLE

{ "type": "GRID.SET_VIEW_TYPE", "options": { "targetKey": "grid", "value": "TOGGLE" } }

GRID.ADD_COLUMN

Add a column to the grid.

  • columnDefinition

  • position

{ "type": "GRID.ADD_COLUMN", "options": { "inputs": [ { "targetKey": "columnKey", "alias": "B" } ], "targetKey": "grid", "columnDefinition": "=CONCATENATE('{\"type\":\"textfield\", \"key\": \"', B, '\"}')" } }

GRID.REMOVE_COLUMN

Remove a column from the grid.

column

{ "type": "GRID.REMOVE_COLUMN", "options": { "targetKey": "grid", "column": "status" } }

Grid operations contain option key/value pairs you can use to manipulate your Grid. These Grid option values include the following: 

Option Key Description Option Values Example

targetKey

Property ID of the component your Grid Operation or Option targets.

Key/value pair of the target key propertyID.

"options": { "targetKey": "gridComponentPropertyId" }

alias

A numeric variable that represents the value of the targetKey.

Key/value pair of a numeric value.

“options”: { "targetKey": "grid", "alias": "B" }

inputs

Input

  • "targetKey"

  • "alias"

“options”: { "inputs": [ { "targetKey": "enter target propertyID", "alias": "enter alias numeral" } ] }

global

Boolean value. Set to true to filter across all data properties.

  • "true"

  • "false"

“options”: { “targetKey”: “grid”, "global": "true" }

column

String value. Enter which column you want to target, remove, or filter by.

Key/value pair of the column propertyID.

“options”: {  “targetKey”: “grid”, “value”: “Auto”, “column”: “type” }

type

Filter Type value.

Any supported Tanstack filter type or Tanstack sort type.

“options”: {  “targetKey”: “grid”, “value”: “Auto”, “column”: “type”, “mode”: “toggle”, “type”: “includesString”  }

value

Show/hide, transpose, Grid view, or toggle values.

  • "VISIBLE" - Show column.

  • "HIDDEN" - Hide column.

  • "TOGGLE" - Toggle column..

  • "TRANSPOSED" - Set to transposed.

  • "STANDARD" - Set to not transposed.

  • "TOGGLE" - Toggle view or transposition.

  • "form" - Set to form view.

  • "spreadsheet" - Set to spreadsheet view.

"options": { "targetKey": "grid", "value": "TOGGLE" } }

direction

Ascending or descending value for column sorting.

  • "asc"

  • "desc"

"options": { "targetKey": "grid", "column": "=A", "direction": "asc" } }

columnDefinition

Any component definition value that creates a new column in the Grid component.

NOTE  Currently, columnDefinition only accepts Vega component definitions.

JSON component definition of a new or existing component.

"options": { "targetKey": "grid", "columnDefinition": "=CONCATENATE('{\"type\":\"textfield\", \"key\": \"', B, '\"}')" }

position

Array index value where a column is inserted. If not defined, the index value is be the last index value of the table value.

Any array index value number starting with "0".

"options": { "targetKey": "grid", "position": "0" }

mode

Grid mode value.

  • "append" - Add to an existing list.

  • "clear" - Remove any existing state.

  • "set" - Set the state for a particular property, replacing any existing state.

  • "toggle" - Set or clear the value for a property based on its current state.

“options”: { “targetKey”: “grid” , “mode”: “toggle” }

About the Configuration Window

General

Image displaying the Grid component's General Settings.
(click to expand image)

Setting

Description

Property ID

A Property ID is the unique field ID used by Unqork to track and link components in your module.

The Property ID is how the software identifies your component. Using Property IDs lets you link components, creating logic-based configurations and API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. calls.

Property IDs must use camel case A naming convention for computer programming. Use camelCase for Property IDs, for example: newUser, lastName, & rdoButton. (stylized as camelCase) without spaces or punctuation.

Notes Note-Icon

Select this tab to display the component's Notes area. You can use notes to keep your teammates informed.

The Notes editor offers a semi-WYSIWYG (What You See is What You Get) content editor. Built to look like a word processor, this editor lets you create, edit, and format your notes. Notes save when saving the component.

Display Icon Display

Select this tab to manage your component's display settings.

Data Icon Data

Select this tab to manage your component's data settings.

Validation Icon Validation

Select this tab to manage your component's validation settings.

Advanced Icon Advanced

Select this tab to manage your component's advanced settings.

Permissions Icon Permissions

Select this tab to see the RBAC RBAC (Role-Based Access Control) is a method to control system access for authorized users. The role in RBAC refers to the levels of access employees have to a network. (role-based access control) settings of the component.

Field Tag Icon Field Tags

Assign components one-word labels to help organize, identify, and group the components in your application.

Consider an example from the API Specification Snippet: Field Tags are applied to Hidden components in the panelRequest and panelResponse Panels. The Field Tags identify the data type of parameters included in the API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. request and response. The API Docs Dashboard tool populates with information about each parameter’s data type, identified by the Field Tag.

Field Tags act as a type of Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. group and let you group components for configuration purposes. Field Tags let you target two or more components using a simple logic component.

For example, add the Field Tag tagForDecision to multiple components in your module. Open the Inputs table of a Decisions component and reference the tagForDecision Field Tag as the input of the Decisions component. The output of the Decisions component then affects all components with the tagForDecision Field Tag.

Save your Field Tags by pressing Enter (Return) or adding a comma after each entry.

Shortcuts Icon Shortcuts

Select this tab to open the list of supported keyboard shortcuts you can use in the component settings modal. Keyboard shortcuts include:

  • Cmd + S (Mac) / Ctrl + S (PC): Save and close the component settings modal.

  • Cmd + G (Mac) / Ctrl + G (PC): Opens a search window to find specific fields and settings in the component settings modal.

  • Tab: Tab to the next field or setting in the component settings modal. This keyboard shortcut tabs left to right and top to bottom.

  • Shift + Tab: Tab to the previous field or setting in the component settings modal. The keyboard shortcut tabs from right to left and bottom to top.

  • Enter (Return): When tabbing to a Tooltip Icon (tooltip), press Enter (Return) to display the field or setting tooltip. Press Enter (Return) again to hide the tooltip.

Additional keyboard shortcuts:

  • Drop-down menus: When you Tab to a settings drop-down, use the keyboard's Up-Arrow Icon (up)/ Down-Arrow icon (down) arrows to make a selection. Then, press Enter (Return) to confirm the selection.

Cancel

Click this button to undo any unsaved configuration changes and return to the canvas.

Save & Close

Click this button to save all settings as configured and return to the canvas.

Display Panel

Image displaying the Grid component's Display Panel Settings.
(click to expand image)

Label and View Mode

Setting

Description

Label Text

Canvas Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field.

User-friendly labels make your module more accessible. Keep labels short and descriptive (a word or two) using title case. For longer entries, use sentence case.

View Type

Displays Grid as a Spreadsheet or Form.

NOTE  The View Type affects how component fields and their settings display in your Grid.

Default Display Options

Setting

Description

Hide Label

Hides the label in Express View.

By default, the Hide Label toggle is set to (OFF).

Disable User Input

When set to Toggle On Icon (ON), end-users can’t interact with or edit the Express View's input field or element. When end-users hover over the field, their cursor changes to alert them to the status change.

By default, the Disable User Input toggle is set to Toggle Off icon (OFF).

Hide Field

Shows or hides the component from view. Setting the Hide Field toggle to Toggle On Icon (ON) hides the component in Express View. Setting the toggle to Toggle Off icon (OFF) shows the component. The component is always visible in the Module Builder.

By default, the Hide Field toggle is set to Toggle Off icon (OFF).

Read Only View

When set to Toggle On Icon (ON), the component is display-only. If another component pushes content to the field, the end-user sees that content. Otherwise, end-users see the word None.

By default, the Read Only View toggle is set to Toggle Off icon (OFF).

Data Panel

Image displaying the Grid component's Data Panel Settings.
(click to expand image)

Initial Values

The Initial Values table displays the fields added to the Grid component as column headers. Once you add components to your Grid in the Module Builder, the field headers appear in the Initial Values Table. After adding component fields to your Grid, you can enter and/or edit table values in each cell. You can also output values from other components (such as Plug-In components) to existing Grid fields. To customize the table columns or rows, use the Table Column and Table Row Settings.

Setting

Description

Table Column Settings

Hover over the column header and select the  (ellipsis) to open the Table Column Settings drop-down menu.

Image showing the ellipsis that opens the Table Column Settings drop-down menu.

From the column settings drop-down menu, select one of the following options:

  • Copy column

  • Cut column

  • Paste column

  • Clear Data

  • Delete column

Table Row Settings

Hover over the column header and select the  (ellipsis) to open the Table Column Settings drop-down menu.

Image showing the ellipsis that opens the Table Row Settings drop-down menu.

From the row settings drop-down menu, select one of the following options:

  • Copy row

  • Cut row

  • Paste row

  • Insert row above

  • Insert row below

  • Clear Data 

  • Delete column

(Add New Row)

Add a new row to all Grid column fields.

NOTE  Rows that contain no data in any column field do not display in Express View.

Store Data in Database

The Store Data in Database setting affects how data persists through your application. When set to Toggle On Icon (ON), Unqork stores values entered into the field to the database (server-side submission). This occurs in three scenarios:

  • Navigating between Panels in a Navigation component. On navigation between pages (Panels), the component’s value saves to the database.

  • Triggering a module save event using a Button component with an Action Type of Save.

  • Navigating between screens of a workflow. On navigation between screens, the component’s value saves to the database.

NOTE  By default, workflows persist data from all fields in the client-side submission when navigating between screens. However, only values from fields with Store Data in Database enabled store in the server-side submission.

Set the toggle to Toggle Off icon (OFF) when you don’t want to store the values from this field in the database.

NOTE  When using a Plug-In to remote execute a module, ensure data moving between modules is persistent. You can optionally enable Store Data in Database for components in the source module. But any components in the API module whose values are included in an API response must have Store Data in Database enabled. When a component’s data is not persistent, the data isn't included in an API call's response. So, Plug-Ins or external services requesting data from the API module can't receive non-persistent data in the response. To learn more about Store Data in Database in the context of API modules, see the panelResponse Panel section of the API Specification Snippet article in our In-Product Help.

TIP  Store Data in Database also affects what data is tracked using Unqork’s built-in tracker. When the Enable Tracker and Track Value toggles are set to Toggle On Icon (ON) in Module Settings, only values from fields with Store Data in Database enabled are tracked.

Add Row on Initialization

Adds one blank row if the Grid contains no data entries on initialization. If the Grid contains data entries, the row won't be added.

Validation Panel

Image displaying the Grid component's Validation Panel Settings.
(click to expand image)

User Input

Setting

Description

Required

When set to Toggle On Icon (ON), the end user must enter a value in the component's visible fields. Set the toggle to Toggle Off icon (OFF) when an entry is optional.

By default, the Required toggle is set to Toggle Off icon (OFF).

Required Error Message

A custom error message that displays below a required field. The error message displays when the end-user tries to save or submit the module without completing the required field.

Advanced Panel

Image displaying the Grid component's Advanced Panel Settings.
(click to expand image)

Additional Styling

Setting

Description

Custom CSS Class

Enter a Custom CSS Cascading Style Sheets (CSS) is a style sheet language used for presenting how a HTML or XML document looks to end-users. Class to apply to your component. Use custom CSS to maintain a consistent look and feel if the field or element is part of a template or more than one module.

Updated CSS styling applies to all components that reference this custom class name.

Adding a Grid Component

In this example, use the Grid component to display a Market Summary spreadsheet for vehicle insurance. The Grid will include the insurance carrier, type, premium amount in USD, and the market status. Then add sorting and filter Grid operations that allow end-users End-Users are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. to modify the grid view.

What You Need

Before starting this configuration, you'll need the following:

Accessing Vega

Currently, the Grid component is only available in Vega runtime engine. To migrate your Centauri module to Vega:

1. Open your Workspace.
2. Select your application.
3. Open your application module.
4. At the top of the Module Builder, select the version drop-down. By default, this is set to Runtime v1.0.0 Open Dropmenu icon.
5. In the version drop-down menu, select Runtime v2.0.0 Open Dropmenu icon.

Configure the Text Field Components

When configuring the Grid component, you must start with the fields you want for your Grid. For this example, you'll add Text Fields for your Grid fields.

1. Drag and drop four  Text Field components onto your canvas.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. and Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. fields, enter the following:

Property ID

Label Text

carrier

Carrier

type

Type

premium

Premium

status

Status

3. Save & Close each component as you add it.

Configure the Grid Component

Next, add your Grid component to use your Text Fields as table columns.

1. Drag and drop a Grid Component Icon Grid component onto your canvas, placing it above your  Text Field components.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter gridInsurance.
3. In the Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. field, enter Market Summary.
4. In the View Type drop-down field, select Spreadsheet.
5. Set the Read Only View toggle to Toggle On Icon (ON).
6. Click Save & Close.
7. Drag and drop the carrier, type, premium, and status  Text Field components inside the gridInsurance Grid Component Icon Grid component.

8. Hover over the gridInsurance Grid Component Icon Grid component and click the (Settings) button from the component toolbar.
9. In the Initial Values table, enter the following values:

 

Carrier (carrier)

Type (type)

Premium (premium)

Status (status)

1

Unqork Auto

Motorcycle

$10,000

Not Taken Up

2

State Farm

Auto

$20,000

Submitted

3

Nationwide

RV

$50,000

Not Taken Up

4

American Family

Boat

$25,000

Indication

5

Geico

Auto

$25,000

Submitted

6

Unqork Auto

Auto

$30,000

Submitted

7

Nationwide

RV

$60,000

Indication

8

Geico Auto

$12,000

Not Taken Up

9

State Farm

Motorcycle

$5,000

Not Taken Up

10

American Family

Boat

$30,000

Submitted

Image showing the Grid component's Initial Values Table data entries.

10. Click Save & Close.

Configure the Columns Component

Add a Columns component to organize the Grid operations you'll add for your Grid.

1. Drag and drop a Columns Component Icon Columns component onto your canvas, placing it above your gridInsurance Grid Component Icon Grid component.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter colGridOperations.
3. Click Save & Close.

Configure the Initializer Components

Your Initializer components will contain the Grid operations for your Grid component. For this example, you'll enter the GRID.SET_SORT and GRID.SET_FILTER operations in the Initializer Outputs tables Enter outputs components and actions you want the component to perform..

1. Drag and drop three Radio Button component icon Initializer components onto your canvas, placing them below your colGridOperations Columns Component Icon Columns component.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. and Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. fields, enter the following:

Property ID

Canvas Label Text

initSort

Set Sort By

initFilterCarrierToggle

Filter Carrier to Unqork Auto

initFilterCarrier

Filter Carrier by String

3. In the Outputs table of the initSort Radio Button component icon Initializer, enter the following:

Property ID

Type

Value

grid

GRID_OPERATION

{ "type": "GRID.SET_SORT", "options": { "inputs": [ { "targetKey": "sortBy", "alias": "A" } ], "targetKey": "gridInsurance", "column": "=A", "direction": "asc" } }

Image showing the initSort Initializer component's Grid Operation in the Outputs table.

4. In the Outputs table of the initFilterCarrierToggle Radio Button component icon Initializer, enter the following:

Property ID

Type

Value

grid

GRID_OPERATION

{ "type": "GRID.SET_FILTER", "options": { "targetKey": "gridInsurance", "value": "Unqork Auto", "column": "carrier", "mode": "toggle", "type": "includesString" } }

Image showing the initFilterCarrierToggle Initializer component's Grid Operation in the Outputs table.

5. In the Outputs table of the initFilterCarrier Radio Button component icon Initializer, enter the following:

Property ID

Type

Value

grid

GRID_OPERATION

{ "type": "GRID.SET_FILTER", "options": { "inputs": [ { "targetKey": "filterString", "alias": "A" } ], "targetKey": "gridInsurance", "value": "=A", "column": "carrier", "mode": "replace", "type": "includesString" } }

Image showing the initFilterCarrier Initializer component's Grid Operation in the Outputs table.

6. Save & Close each component as you add and configure it.
7. Drag and drop your initSort Radio Button component icon Initializer component in the left column of your colGridOperations Columns Component Icon Columns component.
8. Drag and drop your initFilterCarrierToggle and initFilterCarrier Radio Button component icon Initializer components in the right column of your colGridOperations Columns Component Icon Columns component.

Configure the Grid Operation Triggers

The Initializer components you added will now modify your table with the correct input from the end-user End-Users are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.. Using a Dropdown, Button, and Text Field component, end-users can correctly sort and filter the Grid. These components can also trigger your Initializers, making the Grid view dynamic on the end-user's selection.

Adding the Dropdown Component

Add a Dropdown component to determine how your initSort Radio Button component icon Initializer sorts your Grid when the end-user End-Users are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. selects a value.

1. Drag and drop a Dropdown Component Icon Dropdown component onto your canvas, placing it in the left column of your colGridOperations Columns Component Icon Columns component below your initSort Radio Button component icon Initializer component.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter sortBy.
3. In the Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. field, enter Sort by:.
4. In the Data table, enter the following values:

Option Label

Option Values

Carrier

carrier

Premium

premium

Status

status

5. In the Trigger field, enter or select initSort.
6. Click Save & Close.

Adding the Button Component

Add a Button component to determine how your initFilterCarrierToggle Radio Button component icon Initializer sorts your Grid when the end-user End-Users are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. clicks the button.

1. Drag and drop a Button component Icon Button component onto your canvas, placing it in the right column of your colGridOperations Columns Component Icon Columns component below your initFilterCarrierToggle  Radio Button component icon Initializer component.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter btnCarrier.
3. In the Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. field, enter Filter 'Unqork Auto' only.
4. Set the Action Type The action performed by the button when selected. to Event.
5. In the On Click field, enter or select initFilterCarrierToggle.
6. Click Save & Close.

Adding the Text Field Component

Add a Text Field component to determine how your initFilterCarrier Radio Button component icon Initializer sorts your Grid when the end-user End-Users are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. enters a value.

1. Drag and drop a  Text Field component onto your canvas, placing it in the right column of your colGridOperations Columns Component Icon Columns component below your initFilterCarrier  Radio Button component icon Initializer component.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter colGridOperations.
3. Set the Hide Label toggle to Toggle On Icon (ON).
4. In the Trigger On Keypress field, enter or select initFilterCarrier.
5. Click Save & Close.
6. Save your module.

Here's how the completed module looks in the Module Builder:

Image displaying the completed Grid component configuration in the Module Editor.

Preview your module in Express View Express View is how your end-user views you application. Express View also lets you preview your applications to test your configuration and view the styling. After configuring a module, click Preview in the Module Editor to interact with the module in Express View. Here's how your module displays:

Image showing the Express View Preview of the Grid module.

Resources