Dynamic Grid Component
The Dyanmic Grid component is a Centauri (1.0) The Centauri (v 1.0.0) runtime is the first-generation foundation of the Unqork Designer Platform. Centauri provides Creators a codeless experience for developing applications. runtime component and is not supported in the Vega (2.0) The Vega (v 2.0.0) runtime is the next-generation engine of the UDesigner platform. Vega uses cutting-edge technologies to improve the Creator and end-user experience. runtime.
Overview
The Dynamic Grid component combines the ease and usability of a spreadsheet with the power and flexibility of an Unqork grid component. In Express View Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View., your end-user End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. gets a streamlined, spreadsheet-like data entry and exploration experience. Built with large-scale data sets in mind, use a Dynamic Grid to focus on supporting high-performance data consumption, analysis, and exploration use cases. Dynamic Grid also includes features like pivot mode, data aggregation and grouping, and more.
You have various options for populating your Dynamic Grid component:
-
Using a logic component to output data to the Dynamic Grid component. For example, using a Plug-In component to retrieve data from a reference Data Collection. Then, using a Data Workflow component to output the data to the Dynamic Grid component.
-
Importing data from another component, like a Data Table component, using the Data Reference Key option. The grid (the Dynamic Grid component's front-end) populates with the data stored under the Data Reference Key. It's important to note that, in this case, the grid is read-only.
Whenever data entry takes place, ensuring the integrity of your data is important. That's why the Dynamic Grid component provides a strong validation framework. When configuring your Dynamic Grid component, you’ll assign each column a column type. For example, a Number, Text Field, or Checkbox. Having defined column types means your end-user can only enter values that match your data model. You can also set column-specific validation rules for even greater control.
You'll find the Dynamic Grid component under the Display & Layout group to the left of the Module Builder.
About the Configuration Window
To learn more about general component settings, view our General Component Settings article.
Display Panel
|
Setting |
Description |
|---|---|
|
Title |
The heading of the grid. The end-user sees this title at the top of the grid in Express View. It's best practice to always include a title. To hide the title in Express View, set Hide Title to (ON). |
|
Tooltip |
A short hint that displays when an end-user positions their cursor over the (Tooltip) icon. Tooltips can display across more than one line. The tooltip displays next to the title. |
|
Helper Text |
A quick tip describing the expected inputs or how to use the grid. The Helper Text displays below the Dynamic Grid component's title in Express View. |
|
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. Custom CSS lets you maintain a consistent look and feel when the field or element is part of a template or multiple modules. Updated CSS styling applies to all components that reference this custom class name. |
|
Grid Height |
Select how to set the maximum height of the grid. Options include the following:
Enabling Auto Height negatively impacts performance when displaying a large number of records (greater than 500). |
|
Set Grid Height |
Set the height of your grid. The unit depends on your Grid Height setting selection.
|
|
Hide Component |
Shows or hides the component from view. Setting the Hide Field to By default, Hide Component is set to ☐ (unchecked). |
|
Hide Title |
Setting the Hide Title toggle to (ON) stops the title from displaying in Express View. The title still displays in the Module Builder. By default, Hide Title is set to (OFF). |
|
Customize Add Row Button |
When set to (ON), you can customize the appearance of the default Add Row button shown in Express View. By default, Customize Add Row Button is set to (OFF). |
|
Button Label Text |
The Button's Label Text tells your end-user what the button does before they click it. This text shows in the button itself. By default, the Button Label Text is Add Row. |
|
Button Style |
Sets the visual appearance of the button. Options include: Primary, Secondary, Success, Danger, Warning, Info, Light, Dark, and Link. The Button Style only affects the Button component's appearance and does not effect its function. |
|
Custom CSS Class |
Enter a Custom CSS Class to apply to the Add Row button. When you update the CSS styling, it applies to all elements that reference this custom class name. |
|
Left/Right Icon |
Use these fields to add icons (glyphs) to the left or right of your Button's Label Text. For example, entering glyphicon glyphicon-pencil adds an icon of a pencil to your Button. The full list of supported GLYPHICONS® glyph codes is available here: https://getbootstrap.com/docs/3.3/components/. |
(Data Panel
|
Setting |
Description |
|---|---|
|
Data Reference Key |
The Data Reference Key setting lets you use the Dynamic Grid component to display data owned by another component. The referenced component is the sole source and owner of the data. So, your end-user can't edit this data, even if Editable is selected in the Column Setup table. To import data using a Data Reference Key, enter the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. of the component that you're pulling data from. When importing data using a Data Reference Key, the source data's structure must match how the Dynamic Grid component stores data. Column schemas, including Property IDs and data types, must also match between the data source and the Dynamic Grid's Column Setup table. You can learn more about how the Dynamic Grid component stores and structures data in the Structure of a Dynamic Grid Component's Data section. |
Column Setup
This is where you create your grid. Each new row in the Column Setup table becomes a column in your grid in Express View. Click Add Column to add a new row to the Column Setup table.
The top-to-bottom order of rows in your Column Setup table reflects the left-to-right order of columns in your grid in Express View Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View..
After adding a column, click the Edit button to see the following options:
|
Setting |
Description |
|---|---|
|
Header Label |
Enter a label for the column's header in Express View Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View.. For the Button column type, the Header Label also acts as the button label. |
|
Property ID* |
Enter a Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. to associate with the column's data. This Property ID is functionally similar to a component's Property ID. For example, you can reference a column's Property ID to target that column in logic-based configurations. When inline editing is enabled, values entered in the column in Express View store under this Property ID (key) in the submission data. Property IDs use camel case (stylized as camelCase A naming convention for computer programming. Use camelCase for Property IDs, for example: newUser, lastName, & rdoButton.) without spaces or punctuation. You can use the same column Property IDs between different Dynamic Grid components. For instance, you can have columnA and columnB in two different Dynamic Grid components without affecting functionality. *The Property ID field is required. When importing data from another source, the Property ID must match the key under which the column's data is stored in the data source. |
|
Type |
Select a column type. This selection restricts the type of data your end-user can input, or the type of interaction they can have. The column type options include the following:
A column type is required. You can only select one type option per column. Each column type has its own unique column type configuration window. See the Column Type Configuration Windows section for details on each column type's configuration window. When importing data from another source, the column type must match the type of data stored under that column in the data source. For example, using a Number column type for numeric data. |
|
Editable |
When set to Select the Editable checkbox in the column header to set all columns of the grid as editable. Or, use the Editable checkbox in each row to selectively set that column of the grid as editable. Row group cells are only editable if the original row group column is made editable. The grouped parent row, however, is not editable. |
|
Store Data |
When set to Select the Store Data checkbox in the column header to set all columns of the grid to store to the database. Or, use the Store Data checkbox in each row to selectively store data from that column of the grid. You must store all data to the database to use server-side execution. |
|
Hidden |
When set to Select the Hidden checkbox in the column header to set all columns of the grid as hidden. Or, select the Hidden checkbox in each row to selectively set that column of the grid as hidden. |
|
Type |
Choose the column type. Available column types include the following:
|
Column Type Configuration Windows
Each column type option in the Column Setup table has a unique configuration window. From there, you can control column-specific display, data, action, and validation settings.
To access the column type configuration window, click the (Column Settings) button in the Column Setup table. To exit the column type configuration window, click Back to Table.
Click on a column type in the list below to see its individual settings:
|
Text Field Column TypeThe Text Field column type lets your end-user input short text values. Values store as strings. Display SettingsGlobal Behavior Group
Freeze Columns To Left Or Right Of The Grid
Columns
Header
Actions SettingsTriggers
Validations SettingsColumn Values Required Group
Allowed Characters for Column Values Group
Number Column TypeThe Number column type lets your end-user input numbers, including integers and decimals. Entered values store as numbers. Display SettingsFreeze Columns To Left Or Right Of The Grid
Columns
Headers
Actions SettingsTriggers
Validations SettingsColumn Values Required
Allowed Characters for Column Values
Checkbox Column TypeThe Checkbox column type adds a single checkbox to each row of the grid. In Express View, checking the box changes the Boolean value from false to true. Display SettingsFreeze Columns to Left or Right of The Grid
Columns
Header
Data Settings
Actions SettingsTriggers
Validation Panel
Column Value Required
Single-Select Dropdown Column TypeThe Single-Select Dropdown column type adds a drop-down to each row of the grid. Your end-user can select one value from the drop-down. The selected value stores as a string. Display SettingsFreeze Columns to Left or Right of The Grid
Column Group
Header Group
Data Settings
Use the data panel to populate the drop-down's values. Source TypeThere are two different methods that you can use to populate your Single-Select Dropdown: Values or Data Reference Key. ValuesValues is the simplest way to populate the Single-Select Dropdown. Selecting Values shows a table where you can enter each option label along with its value to store.
Data Reference KeyWith Data Reference Key, you can use data from another component to fill your Single-Select Dropdown. You'll most often do this with a Data Table component. You'll add your option values and labels to separate columns of the Data Table then reference the Data Table's Property ID in the Data Reference Key setting.
Actions Settings
Validation SettingsColumn Value Required
Multi-Select Dropdown Column TypeThe Multi-Select Dropdown column type adds a drop-down to each row of the grid. Your end-user can select one or many values from the drop-down. The selected value(s) store as an array of string values. Display SettingsFreeze Columns to Left or Right of The Grid
Columns
Header
Data SettingsSource TypeThere are two different methods that you can use to populate your Multi-Select Dropdown: Values or Data Reference Key. ValuesValues is the simplest way to populate the Multi-Select Dropdown. Selecting Values shows a table where you can enter each option label along with its value to store.
Data Reference KeyWith Data Reference Key, you can use data from another component to fill your Multi-Select Dropdown. You'll most often do this with a Data Table component. You'll add your option values and labels to separate columns of the Data Table then reference the Data Table's Property ID in the Data Reference Key setting.
Actions Settings
Validation SettingsColumn Values Required Group
Button Column TypeThe Button column type adds a clickable button to each row of the grid. You can configure actions to occur on button-click, including deleting the row or triggering other components. No values store to the submission data for the Button column type. Display SettingsFreeze Columns to Left or Right of The Grid
Column Group
Header Group
Actions Settings
Date Column TypeThe Date column type adds a field where your end-user can enter or select a date. You can add a Calendar View to the field, which enables a date picker. Entered or selected values store as a formatted string. By default, dates store in ISO 8601 format, and include a timestamp of 00:00:00.000Z UTC (Coordinated Universal Time). Display SettingsFreeze Columns to Left or Right of The Grid
Column Group
Header Group
Data Settings
Actions Settings
Validations SettingsValid Date
Column Required
Valid Date Range for Column Values
|
Row Grouping
Group Rows
|
Setting |
Description |
|---|---|
|
Add |
Click to create a new row group. Click Add to create additional row groupings. |
|
Property ID |
Enter the Column Setup Property ID to group by. |
|
Sort Direction |
Select a sort order for your row grouping. The drop-down options are:
|
|
... |
If there is more than one Group Row, organize the sort order. Click this button to reveal the following options:
|
|
Clear |
Removes all group rows from the configuration. |
|
Organize Row Groups Into |
The options in the drop-down include:
You can only sort the first row of the grouping.
To learn more about aggregation and pivoting, jump to the User Affordances Group section. Consolidated row grouping doesn't work with row aggregation and you can't sort row groups.
You can sort every row of the grouping individually. |
|
Show Original Row Grouped Columns |
When set to |
Expand Grouping
|
Setting |
Description |
|---|---|
|
Expand Group Rows Automatically |
When set to By default, this setting is set to ☐ (unchecked). |
Actions Panel
Triggers
The Dynamic Grid component supports creating multiple triggers directly in the component's configuration window. You can choose from three possible triggering events for each trigger. You can also create several triggers that have the same triggering event.
|
Setting |
Description |
|---|---|
|
Type |
Select an action to watch for in order to fire the triggers. All 3 trigger types fire only when an end-user action happens on the grid. So, if a logic component adds a row, the triggers don't fire. Instead, if an end-user clicks the Add Row button, the triggers fire. The drop-down's options are:
|
|
Target Property ID |
Enter the Property ID of the component to trigger when the specified Type action occurs. Click the (Search) icon to display a list of possible Property IDs. |
|
... |
If there is more than one Group Row, organize the sort order. Click this button to reveal the following options:
|
|
Add |
Adds an addition trigger to the bottom of the Triggers list. |
|
Clear |
Removes all triggers from the configuration. |
User Affordances Group
These settings determine how your end-user can interact with the grid and its data in Express View. When enabled, a Side Panel displays at the right of the grid. From the Side Panel, your end-user can use any enabled settings to perform analytic functions. Some interactions are also available from the grid's column headers.
|
Setting |
Description |
|---|---|
|
Allow User to Group Rows |
When In the case of a Checkbox column type, the end-user sees checkbox values as text. For instance, end-users might see Checked (true) and Unchecked (false). This feature makes it easier when grouping and sifting through large amounts of data. By default, setting is ☐ (unchecked). |
|
Allow User to Aggregate & Pivot Across All Columns |
When Aggregation lets your end-user apply pre-defined functions to values. In order to see aggregated values, a row group must be applied or the Pivot Mode toggle must be The available aggregation actions vary by column type. For example:
Pivoting allows data to be extrapolated across another axis (Y-axis). Your end-user can pivot all data-based column types. This excludes the Button column type. To use Pivot Mode, the Pivot Mode toggle in the grid's Side Panel must be For best results, also enable the Allow User to Group Rows setting when enabling the Allow User to Aggregate & Pivot Across All Columns setting. By default, Allow User to Group Rows is set to ☐ (unchecked). |
|
Allow User to Sort by Column |
When When sorted in ascending order, an ↑ (Upwards Arrow) icon shows in the column's header. When sorted in descending order, a ↓ (Downwards Arrow) icon shows in the column's header. By default, setting is ☐ (unchecked). |
|
Allow Multi-Column Sorting |
When By default, setting is ☐ (unchecked). |
|
Allow User to Filter Columns |
When The available filtering actions vary by column type. For example:
For Multi-select Dropdown, filtering by value is interpreted as "any array that contains any of the selected values." For example, if filtering by "USA", both ["USA", "Canada"] and ["USA", "Canada", "Mexico"] match the filter criteria.
By default, this setting is |
|
Show Filter Panel |
When selected, a Filter panel shows in the Side Panel. From the Side Panel, your end-user can apply column-specific filters. The available filtering actions vary by column type. By default, the Show Filter Panel checkbox is not selected. |
|
Allow User to Rearrange Rows |
When If you enable row filtering, grouping, sorting, or aggregation and pivoting, the end-user cannot rearrange grid rows. Reordering rows in Express View affects the order in which rows store in the submission data, as well. By default, setting is ☐ (unchecked). |
|
Invoking Cell Edit State |
Select how many times the end-user must click an editable cell in order to edit the cell. There are two options:
|
Validations Settings
Required Group
|
Setting |
Description |
|---|---|
|
Require Minimum Valid Rows |
When This setting respects column-level validation. If the end-user enters one row in the grid, but the row doesn't meet all column-level validations, the component-level validation criteria isn't met. By default, Require Minimum Valid Rows is set to ☐ (unchecked). |
|
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. |
Set Number of Allowed Rows Group
|
Setting |
Description |
|---|---|
|
Set Minimum |
Sets the minimum number of allowed rows in the grid. |
|
Minimum Error Message |
An error message that displays when the grid doesn't meet the minimum number of rows set. |
|
Set Maximum |
Sets the maximum number of allowed rows in the grid. |
|
Maximum Error Message |
An error message that displays when the grid exceeds the maximum number of rows set. |
Notes on Validation
The Dynamic Grid component supports setting validation rules at several levels of the component. In addition to setting validation rules in the main configuration window and column type configuration windows, you can also use logic to set cell or row-level validation. For example, setting minimum or maximum number validation rules in specific rows of the grid. When editing a Dynamic Grid in Express View, visual cues and error messages highlight validation errors at all levels. When using server-side execution to inject data into a Dynamic Grid, though, you'll rely on the validationErrors array to identify errors. You can't display validationErrors in the front-end.
The Dynamic Grid component supports all standard server-side execution actions.
The validationErrors array for a Dynamic Grid component has a different structure compared to some other components.
Here's a basic overview of the structure:
-
Component-level validation errors follow the standard server-side execution validationErrors schema.
-
Cell-level and column-level validation errors are summarized by column. Column-specific errors have their own object in the validationErrors array, separate from component-level errors.
-
In each column-specific object of the validationErrors array is a failedValidations array. The failedValidations array summarizes errors in the column, by type. For example, minLength or required validation errors. Each group of type-specific errors has its own object in the array.
-
Each type-specific error object lists cell-level and column-level errors separately, as a celllevel errors array or columnlevel errors object.
-
The celllevel errors array contains one object per row of the column. This lets you know the exact column/row coordinates of the failed validation.
-
The columnlevel errors object lists all affected rows in the rows array. This again lets you know the exact column/row coordinates.
-
Error messages are also visible.
The following code snippet shows a sample validationErrors array, from a server-side-executed Dynamic Grid component. The array shows component-level and cell-level validation errors.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
"validationErrors": [
{
"id": "dynamicGrid",
"path": "data.dynamicGrid",
"label": "dynamicGrid",
"parent": "data",
"message": "dynamicGrid is required"
},
{
"id": "dynamicGrid",
"path": "data.dynamicGrid",
"label": "dynamicGrid",
"parent": "data",
"message": "dynamicGrid must contain no more than 5 items"
},
{
"id": "dynamicGrid.fullName",
"path": "data.dynamicGrid.fullName",
"label": "Full Name",
"parent": "data.dynamicGrid",
"failedValidations": [
{
"type": "minLength",
"columnlevel": {
"rows": [0, 1, 3],
"message": "Full Name must be no less than 5 characters"
}
},
{
"type": "required",
"columnlevel": {
"rows": [2, 5, 6],
"message": "Full Name is required"
}
}
]
},
{
"id": "dynamicGrid.employeeNumber",
"path": "data.dynamicGrid.employeeNumber",
"label": "Employee Number",
"parent": "data.dynamicGrid",
"failedValidations": [
{
"type": "min",
"cellLevel": [
{
"row": 0,
"message": "Employee Number must be greater than or equal to 1"
},
{
"row": 1,
"message": "Employee Number must be greater than or equal to 2"
}
],
"columnlevel": {
"rows": [2, 3],
"message": "Employee Number must be greater than or equal to 100"
}
},
{
"type": "max",
"columnlevel": {
"rows": [4, 5, 6],
"message": "Employee Number must be less than or equal to 999"
}
}
]
}
]
The Dynamic Grid component also includes built-in data type validations. These validations help ensure data in a given column type matches its intended data types. These validations don't prevent you from saving your module but help detect incorrect data types. The following error messages display for each Column Type when the data types are incorrect:
-
Text Field: No error messages display for the Text Field Column Type.
-
Number: Any value that isn't a number displays a Not a Number error message.
-
Single-select Dropdown: If you inject a value from a logic component that doesn't match the column’s Data Source Value or Value Property displays an Invalid Option error message.
-
Multi-select Dropdown: Any values that don't match the column’s Data Source Value or Value Property display an Invalid Option error message.
-
Date: Any value that isn't formatted as YYYY-MM-DDT00:00:00.000Z or YYYY-MM-DD displays a Not a Date error message.
The Date Column Type, like the Date Input component, has a Valid Date validation that often overrides this error for end-users anyway.
-
Checkbox: Any value that is not a true or false Boolean value displays a Not a Boolean error message.
-
Button: No error messages display for the Button Column Type.
Adding a Dynamic Grid Component
Let's look at how to set up a Dynamic Grid component that supports inline editing. This simple configuration focuses on supporting basic data entry rather than performing analytics.
Configure the Dynamic Grid Component
For this configuration, you'll add every column type to your Dynamic Grid component. But, you only need to open up the column type configuration window for two of them: the Single-Select Dropdown and Multi-Select Dropdown. For the other column types in your Column Setup table, you can keep the default settings.
| 1. | Drag and drop a  Dynamic Grid component onto your canvas. |
| 2. | In theProperty ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter dynamicGrid. |
| 3. | In the Title field, enter Tri-State Insurance. |
| 4. | In the Column Setup table, click Add New Column seven times. This adds seven rows to the Column Setup list. |
| 5. | In the Header Label, Property ID, and Column Type fields, ente the following |
| 6. | Complete the Column Setup as follows: |
| Header Label | Property ID | Editable | Store Data | Column Type |
|---|---|---|---|---|
|
Name |
name |
|
|
Text Field |
|
Annual Income |
incomeAnnual |
|
|
Number |
|
Date of Birth |
dob |
|
|
|
|
New Client |
newClient |
|
|
|
|
State |
state |
|
|
|
|
Types of Insurance |
insuranceTypes |
|
|
|
|
Delete Row |
delete |
☐ (unchecked) |
☐ (unchecked) |
|
Date Input
Single Checkbox
Single-Select Dropdown
Multi-Select Dropdown
ButtonConfigure the Single-Select Dropdown Column Type
Next, add some values to the Single-Select Dropdown.
| 1. | In the State row of your Column Setup table, click the (Settings) button. The Single-Select Dropdown column type configuration settings display. |
| 2. | In the Data panel, click Add Value three times and complete the Values settings as follows: |
| Label | Value | |
|---|---|---|
|
1 |
New York |
NY |
|
2 |
New Jersey |
NJ |
|
3 |
Connecticut |
CT |
| 3. | Click Save. The Column type settings close. |
Configure the Multi-Select Dropdown Column Type
Finally, add some values to the Multi-Select Dropdown.
| 1. | In the Types of Insurance row of your Column Setup table, click the (Settings) button. The Multi-Select Dropdown column type configuration window opens. |
| 2. | In the Data panel, click Add Value five times and complete the Values table as follows: |
| Option Label | Data Source Value |
|---|---|
|
Health |
health |
|
Renters |
renters |
|
Auto |
auto |
|
Home |
home |
|
Life |
life |
| 3. | Click Save. The Column type settings close. |
| 4. | Click Save Component. |
| 5. | Save your module. |
Now you're ready to preview your module and interact with the grid. Your completed Dynamic Grid component looks like this in Express View:
Structure of a Dynamic Grid Component's Data
Take a moment to understand how data entered in a Dynamic Grid component stores, using the configuration above.
Understanding this structure is also key when importing data into your Dynamic Grid component. Whether using a Data Reference Key or referencing a data collection, the source data's structure must match how the Dynamic Grid component stores data.
Data entered in the Dynamic Grid component stores as an array of objects under a single key. The top-level key is the Dynamic Grid component's Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module.. Each row added to the Dynamic Grid component in Express View Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View. becomes a new object in the array of row objects. In each row object, row-specific values store as explicit key/value pairs, where the key is the Property ID associated with that column. Depending on the column type, values store as different data types and data structures A data structure is the design used for organizing, using, and storing data.. The following image shows an example of how two rows of data entered in a Dynamic Grid component looks in the DevTools Console The DevTools Console helps you securely store, build, test, and deploy your software.:
Discover how to reference data from a Dynamic Grid component, view our Dynamic Grid: Targeted Logic and Referencing Syntax article.
Dynamic Grid Interaction Shortcuts
The Dynamic Grid supports several keyboard interactions that make it quick to navigate or edit the grid in Express View.
Grid Navigation
The following shortcuts for navigation are supported:
-
Using arrow keys to navigate between cells (any direction). It's important to note that the arrow keys only work when you start navigation in a cell that isn't set up with edit mode.
-
Pressing Tab (navigate right) and Shift + Tab (navigate left) to move between cells.
If actively editing cells, using these shortcuts to navigate between cells doesn't halt the editing state.
-
Pressing Enter to enter or exit the editing state on an editable cell.
You can also double-click a cell to enter the editing state. Or if you prefer to use a single-click, adjust the Invoking Cell Edit State setting.
Cell Editing
It's important to note that cell editing shortcuts only work when the grid is editable. The following cell editing shortcuts are supported:
-
Pressing Enter or clicking outside of the cell you're actively editing to commit any changes made. You'll also use the Enter key to execute buttons.
-
Pressing Esc to discard any changes to the cell you're actively editing.
It's also important to note that end-users can execute any cell with a Value is Clicked trigger applied by pressing Alt + Enter.
Checkboxes
There are a few shortcuts specific to checkboxes.
If end-users aren't editing a checkbox cell, they can select and clear boxes by either:
-
Pressing Enter.
-
Single-clicking in the checkbox.
-
Single or double-clicking outside the checkbox.
The last option depends on the Invoking Cell Edit State setting.
If end-users are editing a checkbox cell, they can select and clear boxes by either:
-
Pressing Enter.
-
Single-clicking in the checkbox.
-
Single or double-clicking outside the checkbox.
Overview
The Dynamic Grid component combines the ease and usability of a spreadsheet with the power and flexibility of an Unqork grid component. In Express View Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View., your end-user End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. gets a streamlined, spreadsheet-like data entry and exploration experience. Built with large-scale data sets in mind, use a Dynamic Grid to focus on supporting high-performance data consumption, analysis, and exploration use cases. Dynamic Grid also includes features like pivot mode, data aggregation and grouping, and more.
You have various options for populating your Dynamic Grid component:
-
Using a logic component to output data to the Dynamic Grid component. For example, using a Plug-In component to retrieve data from a reference Data Collection. Then, using a Data Workflow component to output the data to the Dynamic Grid component.
-
Importing data from another component, like a Data Table component, using the Data Reference Key option. The grid (the Dynamic Grid component's front-end) populates with the data stored under the Data Reference Key. It's important to note that, in this case, the grid is read-only.
Whenever data entry takes place, ensuring the integrity of your data is important. That's why the Dynamic Grid component provides a strong validation framework. When configuring your Dynamic Grid, you’ll assign each column a column type. For example, Number, Text Field, or Checkbox. Having defined column types means your end-user can only enter values that match your data model. You can also set column-specific validation rules for even greater control.
You'll find the Dynamic Grid component under the Display & Layout group at the left of the Module Builder.
You have various options for populating your Dynamic Grid component:
-
Using a logic component to output data to the Dynamic Grid component. For example, using a Plug-In component to retrieve data from a reference Data Collection. Then, using a Data Workflow component to output the data to the Dynamic Grid component.
-
Importing data from another component, like a Data Table component, using the Data Reference Key option. The grid (the Dynamic Grid component's front-end) populates with the data stored under the Data Reference Key. It's important to note that, in this case, the grid is read-only.
You'll find the Dynamic Grid component under the Display & Layout group at the left of the Module Builder.
About the Configuration Window
To learn more about general component settings, view our General Component Settings article.
Display Panel
|
Setting |
Description |
|---|---|
|
Title |
The heading of the grid. The end-user sees this title at the top of the grid in Express View. It's best practice to always include a title. To hide the title in Express View, set Hide Title to (ON). |
|
Tooltip |
A short hint that displays when an end-user positions their cursor over the (Tooltip) icon. Tooltips can display across more than one line. The tooltip displays next to the title. |
|
Helper Text |
A quick tip describing the expected inputs or how to use the grid. The Helper Text displays below the Dynamic Grid component's title in Express View. |
|
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. Custom CSS lets you maintain a consistent look and feel when the field or element is part of a template or multiple modules. Updated CSS styling applies to all components that reference this custom class name. |
|
Grid Height |
Select how to set the maximum height of the grid. The options are:
Enabling Auto Height negatively impacts performance when displaying a large number of records (greater than 500). |
|
Set Grid Height To |
Set the height of your grid. The unit depends on your Grid Height setting selection.
|
|
Hide Component |
Displays or hides the component from view. Setting Hide Field to (ON) hides the component in Express View. Setting it to (OFF) displays the component. The component is always visible in the Module Builder. By default, Hide Field is set to (OFF). |
|
Hide Title |
Setting the Hide Title toggle to (ON) stops the title from displaying in Express View. The title still displays in the Module Builder. By default, Hide Title is set to (OFF). |
|
Customize 'Add Row' Button |
When set to (ON), you can customize the appearance of the default Add Row button shown in Express View. By default, the Customize 'Add Row' Button toggle is set to (OFF). |
|
Button Label Text |
The Button's Label Text tells your end-user what the button does before they click it. This text shows in the button itself. By default, the Button Label Text is Add Row. |
|
Button Style |
Sets the visual appearance of the button. Options include: Primary, Secondary, Success, Danger, Warning, Info, Light, Dark, and Link. The Button Style only affects the Button component's appearance and does not effect its function. |
|
Custom CSS Class |
Enter a Custom CSS Class to apply to the Add Row button. When you update the CSS styling, it applies to all elements that reference this custom class name. |
|
Left/Right Icon |
Use these fields to add icons (glyphs) to the left or right of your Button's Label Text. For example, entering glyphicon glyphicon-pencil adds an icon of a pencil to your Button. The full list of supported GLYPHICONS® glyph codes is available here: https://getbootstrap.com/docs/3.3/components/. |
Data Panel
|
Setting |
Description |
|---|---|
|
Data Reference Key |
The Data Reference Key setting lets you use the Dynamic Grid component to display data owned by another component. The referenced component is the sole source and owner of the data. So, your end-user can't edit this data, even if Editable is selected in the Column Setup table. To import data using a Data Reference Key, enter the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. of the component that you're pulling data from. When importing data using a Data Reference Key, the source data's structure must match how the Dynamic Grid component stores data. Column schemas, including Property IDs and data types, must also match between the data source and the Dynamic Grid's Column Setup table. You can learn more about how the Dynamic Grid component stores and structures data in the Structure of a Dynamic Grid Component's Data section. |
Column Setup Table
This is where you create your grid. Each new row in the Column Setup table becomes a column in your grid in Express View. Click +Add New Column to add a new row to the Column Setup table.
The top-to-bottom order of rows in your Column Setup table reflects the left-to-right order of columns in your grid in Express View Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View..
You can easily rearrange the order of rows in your Column Setup table. Click and drag the (Grip) icon found at the left of each row in the Column Setup table.
|
Setting |
Description |
|---|---|
|
Header Label |
Enter a label for the column's header in Express View Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View.. For the Button column type, the Header Label also acts as the button label. |
|
Property ID |
Enter a Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. to associate with the column's data. This Property ID is functionally similar to a component's Property ID. For example, you can reference a column's Property ID to target that column in logic-based configurations. When inline editing is enabled, values entered in the column in Express View store under this Property ID (key) in the submission data. Property IDs use camel case (stylized as camelCase A naming convention for computer programming. Use camelCase for Property IDs, for example: newUser, lastName, & rdoButton.) without spaces or punctuation. You can use the same column Property IDs between different Dynamic Grid components. For instance, you can have columnA and columnB in two different Dynamic Grid components without affecting functionality. The Property ID field is required. When importing data from another source, the Property ID must match the key under which the column's data is stored in the data source. |
|
Column Type |
Select a column type. This selection restricts the type of data your end-user can input, or the type of interaction they can have. The column type options are:
A column type is required and you can only select one type option per column. When importing data from another source, the column type must match the type of data stored under that column in the data source. For example, using a Number column type for numeric data. Each column type has its own unique column type configuration window. See the Column Type Configuration Windows section for details on each column type's configuration window. |
|
Editable |
When selected, end-users can edit cells in this column in Express View. Use this setting to enable inline editing and data entry. Select the Editable checkbox in the column header to set all columns of the grid as editable. Or, use the Editable checkbox in each row to selectively set that column of the grid as editable. Row group cells are only editable if the original row group column is made editable. The grouped parent row, however, is not editable. |
|
Store Data |
When selected, values entered in this column in Express View store to the database. Select the Store Data checkbox in the column header to set all columns of the grid to store to the database. Or, use the Store Data checkbox in each row to selectively store data from that column of the grid. You must store all data to the database to use server-side execution. |
|
Hidden |
When selected, the column is hidden from view in Express View. Select the Hidden checkbox in the column header to set all columns of the grid as hidden. Or, select the Hidden checkbox in each row to selectively set that column of the grid as hidden. |
|
(Column Settings Button) |
Shows in the actions column in each row of the Column Setup table. When clicked, opens the selected row's column type-specific configuration window. |
|
(Delete Button) |
Shows on hover-over of the actions column in each row of the Column Setup table. When clicked,deletes the selected row and its column. |
Arrange Data Group
The Arrange Data settings let you preemptively apply row groupings to your grid. To let your end-user choose whether to apply row groupings, use the User Affordances settings.
|
Setting |
Description |
|---|---|
|
Set Column Widths |
Manually set the width for individual columns. When set to (OFF), a column's minimum-width autosizes to 20 units. An autosized column's width then grows in proportion to the contents of the column. For example, a column titled Age is 20 units (minimum-width) + 3 units (1 unit per letter character) = 23 units. Default is (OFF). |
|
(Set Column Width Settings Button) |
Opens the Set column widths configuration panel. When set to (ON), displays the Define width by units table with the following columns:
If there are no columns, the Define width by units table does not display. |
|
+ Add Column to Group By |
Click to create a new row group. Click + Group By Another Column to create additional row groupings. To delete a row group, click the X button found at the right of the Sort Order drop-down. The top-to-bottom order of row groups determines nesting. To rearrange row groups, click and drag a row group's (Grip) icon. |
|
Column Drop-down |
Select a column to group rows by. The column must exist in the Column Setup table to show in the drop-down list. The column list reflects the Header Labels assigned in the Column Setup table. |
|
Sort Order Drop-down |
Select a sort order for your row grouping. The drop-down options are:
|
|
Organize Row Groups Into |
The options include:
You can only sort the first row of the grouping.
To learn more about aggregation and pivoting, jump to the User Affordances Group section. Consolidated row grouping doesn't work with row aggregation and you can't sort row groups.
You can sort every row of the grouping individually. |
|
Repeat Row Grouped Value in Each Row |
Visible when Organize Row Groups Into is set to Single Column or Multi-Column. When selected, the row-grouped value shows in each row of the row grouping. So, when expanding a row grouping, each row in the grouping still shows the value shared between each row. When not selected, the cell is blank. The shared value only displays in the top-level grouping. |
|
Show Original Row Grouped Columns |
When selected, row-grouped columns also show in the grid without any grouping applied. So, in addition to column data showing under the row-grouping column, the original column also shows in the grid. When not selected, row-grouped columns only show under the row-grouping column(s), as determined by the Organize Row Groups Into setting. |
Column Type Configuration Windows
Each column type option in the Column Setup table has a unique configuration window. From there, you can control column-specific display, data, action, and validation settings.
To access the column type configuration window, click the (Column Settings) button in the Column Setup table. To exit the column type configuration window, click Back to Table.
Click a column type heading below to expand the drop-down and show the configuration window description.
|
Text Field Column TypeThe Text Field column type lets your end-user input short text values. Values store as strings. Display Settings
Global Behavior Group
Freeze Columns to Left or Right of The Grid
Column Group
Header Group
Actions Panel
Validation Panel
Column Values Required Group
Allowed Characters for Column Values Group
Number Column TypeThe Number column type lets your end-user input numbers, including integers and decimals. Entered values store as numbers. Display Panel
Freeze Columns to Left or Right of The Grid
Column Group
Header Group
Actions Panel
Validation Panel
Column Values Required Group
Valid Number Range for Column Values Group
Checkbox Column TypeThe Checkbox column type adds a single checkbox to each row of the grid. When selected, the Boolean value true stores. When clear, the Boolean value false stores. Display Panel
Freeze Columns to Left or Right of The Grid
Column Group
Header Group
Data Panel
Actions Panel
Validation Panel
Column Values Required Group
Single-select Dropdown Column TypeThe Single-select Dropdown column type adds a drop-down to each row of the grid. Your end-user can select one value from the drop-down. The selected value stores as a string. Display Panel
Freeze Columns to Left or Right of The Grid
Column Group
Header Group
Data Panel
There are two different methods that you can use to populate your Single-select Dropdown: Values or Data Reference Key. ValuesValues is the simplest way to populate the Single-select Dropdown. Selecting Values shows a table where you can enter each option label along with its value to store.
Data Reference KeyWith Data Reference Key, you can use data from another component to fill your Single-select Dropdown. You'll most often do this with a Data Table component. You'll add your option values and labels to separate columns of the Data Table then reference the Data Table's Property ID in the Data Reference Key setting.
Actions Panel
Validation Panel
Column Values Required Group
Multi-select Dropdown Column TypeThe Multi-select Dropdown column type adds a drop-down to each row of the grid. Your end-user can select one or many values from the drop-down. The selected value(s) store as an array of string values. Display Panel
Freeze Columns to Left or Right of The Grid
Column Group
Header Group
Data Panel
There are two different methods that you can use to populate your Multi-select Dropdown: Values or Data Reference Key. ValuesValues is the simplest way to populate the Multi-select Dropdown. Selecting Values shows a table where you can enter each option label along with its value to store.
Data Reference KeyWith Data Reference Key, you can use data from another component to fill your Multi-select Dropdown. You'll most often do this with a Data Table component. You'll add your option values and labels to separate columns of the Data Table then reference the Data Table's Property ID in the Data Reference Key setting.
Actions Panel
Validation Panel
Column Values Required Group
Button Column TypeThe Button column type adds a clickable button to each row of the grid. You can configure actions to occur on button-click, including deleting the row or triggering other components. No values store to the submission data for the Button column type. Display Panel
Freeze Columns to Left or Right of The Grid
Column Group
Header Group
Actions Panel
Date Column TypeThe Date column type adds a field where your end-user can enter or select a date. You can add a Calendar View to the field, which enables a date picker. Entered or selected values store as a formatted string. By default, dates store in ISO 8601 format, and include a timestamp of 00:00:00.000Z UTC (Coordinated Universal Time). Display Panel
Freeze Columns to Left or Right of The Grid
Column Group
Header Group
Data Panel
Actions Panel
Validation Panel
Valid Date Group
Column Values Required Group
Valid Date Range for Column Values Group
|
Actions Panel
Triggers Group
The Dynamic Grid component supports creating multiple triggers directly in the component's configuration window. You can choose from three possible triggering events for each trigger. You can also create several triggers that have the same triggering event.
|
Setting |
Description |
|---|---|
|
+ Add Trigger |
Click + Add Trigger to create a new trigger. Triggers let you create if/then rules to trigger components when a specified action occurs. |
|
When... |
Select an action to watch for in order to fire the triggers. All 3 trigger types fire only when an end-user action happens on the grid. So, if a logic component adds a row, the triggers don't fire. Instead, if an end-user clicks the Add Row button, the triggers fire. The drop-down's options are:
|
|
Then... |
Enter the Property ID of the component to trigger when the specified When... action occurs. |
User Affordances Group
These settings determine how your end-user can interact with the grid and its data in Express View. When enabled, a Side Panel displays at the right of the grid. From the Side Panel, your end-user can use any enabled settings to perform analytic functions. Some interactions are also available from the grid's column headers.
|
Setting |
Description |
|---|---|
|
Allow User to Group Rows |
When set to (ON), your end-user can group all data-based column types. This excludes the Button column type. Row grouping automatically groups data based on shared values and can be nested many times. In the case of a Checkbox column type, the end-user sees checkbox values as text. For instance, end-users might see Checked (true) and Unchecked (false). This feature makes it easier when grouping and sifting through large amounts of data. By default, this toggle is set to (OFF). |
|
Allow User to Aggregate & Pivot Across All Columns |
When set to (ON), your end-user can perform aggregation and pivoting functions. When enabled, the Pivot Mode toggle shows in the Side Panel. Aggregation lets your end-user apply pre-defined functions to values. In order to see aggregated values, a row group must be applied or the Pivot Mode toggle must be set to (ON). The available aggregation actions vary by column type. For example:
Pivoting allows data to be extrapolated across another axis (Y-axis). Your end-user can pivot all data-based column types. This excludes the Button column type. To use Pivot Mode, the Pivot Mode toggle in the grid's Side Panel must be set to (ON). Enabling Pivot Mode temporarily hides tabular data, similar to creating a new Pivot Table instance in Excel. For best results, also enable the Allow User to Group Rows setting when enabling the Allow User to Aggregate & Pivot Across All Columns setting. By default, Allow User to Group Rows is set to (OFF). |
|
Allow User to Sort by Column |
When set to (ON), end-users can sort column values. Clicking a column's header in the grid sorts the column's values in ascending order. Clicking the column's header again sorts the column's values in descending order. Clicking the column's header again removes the sort order. When sorted in ascending order, an ↑ (Upwards Arrow) icon shows in the column's header. When sorted in descending order, a ↓ (Downwards Arrow) icon shows in the column's header. By default, this toggle is set to (OFF). |
|
Allow Multi-Column Sorting |
When set to (ON), end-users can sort by multiple columns at the same time. Press and hold the Shift key when selecting additional column headers. Press and hold the Shift key when clicking a header to change the sort order. By default, this toggle is set to (OFF). |
|
Allow User to Filter Columns |
When set to (ON), end-users can filter column values. Each column header in the grid shows a (Hamburger) icon. When clicked, a column-specific Filter menu opens. The available filtering actions vary by column type. For example:
For Multi-select Dropdown, filtering by value is interpreted as "any array that contains any of the selected values." For example, if filtering by "USA", both ["USA", "Canada"] and ["USA", "Canada", "Mexico"] match the filter criteria.
By default, this toggle is set to (OFF). |
|
Show Filter Panel |
When selected, a Filter panel shows in the Side Panel. From the Side Panel, your end-user can apply column-specific filters. The available filtering actions vary by column type. By default, the Show Filter Panel checkbox is not selected. |
|
Allow User to Rearrange Rows |
When set to (ON), end-users can rearrange rows in the grid. If you enable row filtering, grouping, sorting, or aggregation and pivoting, the end-user cannot rearrange grid rows. Reordering rows in Express View affects the order in which rows store in the submission data, as well. By default, this toggle is set to (OFF). |
|
Invoking Cell Edit State |
Select how many times the end-user must click an editable cell in order to edit the cell. There are two options:
|
Validation Panel
Required Group
|
Setting |
Description |
|---|---|
|
Require Minimum Valid Rows |
When set to (ON), the end-user must enter at least one valid row in the grid before navigating ahead or saving the module. Set the toggle to (OFF) when an entry is optional. This setting respects column-level validation. If the end-user enters one row in the grid, but the row doesn't meet all column-level validations, the component-level validation criteria isn't met. By default, the Require Minimum Valid Rows toggle is set to (OFF). |
|
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. |
Set Number of Allowed Rows Group
|
Setting |
Description |
|---|---|
|
Set Minimum |
Sets the minimum number of allowed rows in the grid. |
|
Minimum Error Message |
An error message that displays when the grid doesn't meet the minimum number of rows set. |
|
Set Maximum |
Sets the maximum number of allowed rows in the grid. |
|
Maximum Error Message |
An error message that displays when the grid exceeds the maximum number of rows set. |
Notes on Validation
The Dynamic Grid component supports setting validation rules at several levels of the component. In addition to setting validation rules in the main configuration window and column type configuration windows, you can also use logic to set cell or row-level validation. For example, setting minimum or maximum number validation rules in specific rows of the grid. When editing a Dynamic Grid in Express View, visual cues and error messages highlight validation errors at all levels. When using server-side execution to inject data into a Dynamic Grid, though, you'll rely on the validationErrors array to identify errors. You can't display validationErrors in the front-end.
The Dynamic Grid component supports all standard server-side execution actions.
The validationErrors array for a Dynamic Grid component has a different structure compared to some other components.
Here's a basic overview of the structure:
-
Component-level validation errors follow the standard server-side execution validationErrors schema.
-
Cell-level and column-level validation errors are summarized by column. Column-specific errors have their own object in the validationErrors array, separate from component-level errors.
- In each column-specific object of the validationErrors array is a failedValidations array. The failedValidations array summarizes errors in the column, by type. For example, minLength or required validation errors. Each group of type-specific errors has its own object in the array.
- Each type-specific error object lists cell-level and column-level errors separately, as a celllevel errors array or columnlevel errors object.
- The celllevel errors array contains one object per row of the column. This lets you know the exact column/row coordinates of the failed validation.
- The columnlevel errors object lists all affected rows in the rows array. This again lets you know the exact column/row coordinates.
- Error messages are also visible.
The following code snippet shows a sample validationErrors array, from a server-side-executed Dynamic Grid component. The array shows component-level and cell-level validation errors.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
"validationErrors": [
{
"id": "dynamicGrid",
"path": "data.dynamicGrid",
"label": "dynamicGrid",
"parent": "data",
"message": "dynamicGrid is required"
},
{
"id": "dynamicGrid",
"path": "data.dynamicGrid",
"label": "dynamicGrid",
"parent": "data",
"message": "dynamicGrid must contain no more than 5 items"
},
{
"id": "dynamicGrid.fullName",
"path": "data.dynamicGrid.fullName",
"label": "Full Name",
"parent": "data.dynamicGrid",
"failedValidations": [
{
"type": "minLength",
"columnlevel": {
"rows": [0, 1, 3],
"message": "Full Name must be no less than 5 characters"
}
},
{
"type": "required",
"columnlevel": {
"rows": [2, 5, 6],
"message": "Full Name is required"
}
}
]
},
{
"id": "dynamicGrid.employeeNumber",
"path": "data.dynamicGrid.employeeNumber",
"label": "Employee Number",
"parent": "data.dynamicGrid",
"failedValidations": [
{
"type": "min",
"cellLevel": [
{
"row": 0,
"message": "Employee Number must be greater than or equal to 1"
},
{
"row": 1,
"message": "Employee Number must be greater than or equal to 2"
}
],
"columnlevel": {
"rows": [2, 3],
"message": "Employee Number must be greater than or equal to 100"
}
},
{
"type": "max",
"columnlevel": {
"rows": [4, 5, 6],
"message": "Employee Number must be less than or equal to 999"
}
}
]
}
]
The Dynamic Grid component also includes built-in data type validations. These validations help ensure data in a given column type matches its intended data types. These validations don't prevent you from saving your module but help detect incorrect data types. The following error messages display for each Column Type when the data types are incorrect:
-
Text Field: No error messages display for the Text Field Column Type.
-
Number: Any value that isn't a number displays a Not a Number error message.
-
Single-select Dropdown: If you inject a value from a logic component that doesn't match the column’s Data Source Value or Value Property displays an Invalid Option error message.
-
Multi-select Dropdown: Any values that don't match the column’s Data Source Value or Value Property display an Invalid Option error message.
-
Date: Any value that isn't formatted as YYYY-MM-DDT00:00:00.000Z or YYYY-MM-DD displays a Not a Date error message.
The Date Column Type, like the Date Input component, has a Valid Date validation that often overrides this error for end-users anyway.
-
Checkbox: Any value that is not a true or false Boolean value displays a Not a Boolean error message.
-
Button: No error messages display for the Button Column Type.
Adding a Dynamic Grid Component
Let's look at how to set up a Dynamic Grid component that supports inline editing. This simple configuration focuses on supporting basic data entry rather than performing analytics.
Configure the Dynamic Grid Component
For this configuration, you'll add every column type to your Dynamic Grid component. But, you only need to open up the column type configuration window for two of them: the Single-select Dropdown and Multi-select Dropdown. For the other column types in your Column Setup table, you can keep the default settings.
| 1. | Drag and drop a Dynamic Grid component onto your canvas. |
| 2. | In theProperty ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter dynamicGrid. |
| 3. | In the Title field, enter Tri-State Insurance. |
| 4. | In the Column Setup table, click + Add New Column seven times. This adds seven rows to the Column Setup table. |
| 5. | Complete the Column Setup table as follows: |
| Header Label | Property ID | Column Type | Editable | Store Data |
|---|---|---|---|---|
|
Name |
name |
Text Field |
Yes (selected) |
Yes (selected) |
|
Annual Income |
incomeAnnual |
Number |
Yes (selected) |
Yes (selected) |
|
Date of Birth |
dob |
Date |
Yes (selected) |
Yes (selected) |
|
New Client |
newClient |
Checkbox |
Yes (selected) |
Yes (selected) |
|
State |
state |
Single-select Dropdown |
Yes (selected) |
Yes (selected) |
|
Types of Insurance |
insuranceTypes |
Multi-select Dropdown |
Yes (selected) |
Yes (selected) |
|
Delete Row |
delete |
Button |
Unchecked |
Unchecked |
To change the column type, select the row-specific cell under the Column Type header. From the drop-down, select a column type.
To mark all rows as editable, select the checkbox in the Editable header of the Column Setup table. You can select the checkbox in the Store Data column header, too, to enable the setting for all rows.
Configure the Single-Select Dropdown Column Type
Next, add some values to the Single-select Dropdown.
| 1. | In the State row of your Column Setup table, click the (Column Settings) button. The Single-select Dropdown column type configuration window opens. |
| 2. | In the Data panel, complete the Values table as follows: |
| Option Label | Data Source Value | |
|---|---|---|
|
1 |
New York |
NY |
|
2 |
New Jersey |
NJ |
|
3 |
Connecticut |
CT |
| 3. | Click Back to Table to return to the main configuration window. |
Configure the Multi-Select Dropdown Column Type
Finally, add some values to the Multi-select Dropdown.
| 1. | In the Types of Insurance row of your Column Setup table, click the (Column Settings) button. The Multi-select Dropdown column type configuration window opens. |
| 2. | In the Data panel, complete the Values table as follows: |
| Option Label | Data Source Value |
|---|---|
|
Health |
health |
|
Renters |
renters |
|
Auto |
auto |
|
Home |
home |
|
Life |
life |
| 3. | Click Back to Table to return to the main configuration window. |
| 4. | Click Save. |
| 5. | Save your module. |
Now you're ready to preview your module and interact with the grid. Your completed Dynamic Grid component works like this in Express View:
Structure of a Dynamic Grid Component's Data
Take a moment to understand how data entered in a Dynamic Grid component stores, using the configuration above.
Understanding this structure is also key when importing data into your Dynamic Grid component. Whether using a Data Reference Key or referencing a data collection, the source data's structure must match how the Dynamic Grid component stores data.
Data entered in the Dynamic Grid component stores as an array of objects under a single key. The top-level key is the Dynamic Grid component's Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module.. Each row added to the Dynamic Grid component in Express View Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View. becomes a new object in the array of row objects. In each row object, row-specific values store as explicit key/value pairs, where the key is the Property ID associated with that column. Depending on the column type, values store as different data types and data structures A data structure is the design used for organizing, using, and storing data.. The following image shows an example of how two rows of data entered in a Dynamic Grid component looks in the DevTools Console The DevTools Console helps you securely store, build, test, and deploy your software.:
Discover how to reference data from a Dynamic Grid component, view our Dynamic Grid: Targeted Logic and Referencing Syntax article.
Dynamic Grid Interaction Shortcuts
The Dynamic Grid supports several keyboard interactions that make it quick to navigate or edit the grid in Express View.
Grid Navigation
The following shortcuts for navigation are supported:
-
Using arrow keys to navigate between cells (any direction). It's important to note that the arrow keys only work when you start navigation in a cell that isn't set up with edit mode.
-
Pressing Tab (navigate right) and Shift + Tab (navigate left) to move between cells.
If actively editing cells, using these shortcuts to navigate between cells doesn't halt the editing state.
-
Pressing Enter to enter or exit the editing state on an editable cell.
You can also double-click a cell to enter the editing state. Or if you prefer to use a single-click, adjust the Invoking Cell Edit State setting.
Cell Editing
It's important to note that cell editing shortcuts only work when the grid is editable. The following cell editing shortcuts are supported:
-
Pressing Enter (Return) or clicking outside of the cell you're actively editing to commit any changes made. You'll also use the Enter key to execute buttons.
-
Pressing Esc to discard any changes to the cell you're actively editing.
It's also important to note that end-users can execute any cell with a Value is Clicked trigger applied by pressing Alt + Enter.
Checkboxes
There are a few shortcuts specific to checkboxes.
If end-users aren't editing a checkbox cell, they can select and clear boxes by either:
-
Pressing Enter (Return).
-
Single-clicking in the checkbox.
-
Single or double-clicking outside the checkbox.
The last option depends on the Invoking Cell Edit State setting.
If end-users are editing a checkbox cell, they can select and clear boxes by either:
-
Pressing Enter (Return).
-
Single-clicking in the checkbox.
-
Single or double-clicking outside the checkbox.
Resources
