Data Grid Component

Overview

The Data Grid component is one of Unqork's long-standing layout components. Think of a Data Grid as a place to organize your components on your canvas. The Data Grid organizes your fields in rows and columns. But, instead of showing one fieldset at a time, your end-user can see as many fieldsets as you've allowed. So, your end-user sees a continuous stream of organized fields in the same view. It's a great way to group similar components together!

You'll use this component when you want to show multiple entries for a small number of fields. And, while your end-user enters their data, they can add or remove rows as needed. Having this flexibility improves your overall design and your end-user's experience.

You'll find the Data Grid component in the Display & Layout group at the left of the Module Builder.

What You'll Learn

In this article, you'll learn how to:

About the Configuration Window

General

Setting

Description

Display Tab

Shows the components Display settings panel as applicable.

Permissions Tab

Selecting this tab shows the component's role-based access control (RBAC) settings.

Cancel Button

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

Save Button

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

Display Settings

Setting

Description

Label

A Label indicates the purpose of the corresponding field or component. For input components, the Label tells the end-user how to interact with the field. For non-input components, the Label is not end-user facing, and only appears in the Module Builder. 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.

Property Name

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

The Property Name is how the software identifies your component. Using Property Names lets you link components, creating logic-based configurations and API (application programming interface) calls.

Property Names must use camel case (stylized as camelCase) without spaces or punctuation.

Add Another Text

Enter text here to set the label for the Add New Row button.

Remove Row Text

Enter text here to set the label for the Remove Row button.

Data Reference Key

Enter the Property ID  of the component that you're pulling data from.

Minimum Length

Sets the lowest number of rows displayed in your Data Grid. Notice that the Add row button hides when your end-user reaches this lowest limit.

Maximum Length

Sets the highest number of rows displayed in your Data Grid. Notice that the Add row button hides when your end-user reaches this highest limit.

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.

Description

Quick tip describing the expected value of an input field. Unlike a Tooltip, Helper Text stays visible under the input field and displays on a single line.

Striped

Selecting the Striped checkbox sets alternate row color to ON. So, coloring appears on alternate rows of your fieldset.  This coloring is great because it makes your rows easier to read.

By default, this checkbox is unchecked.

Hover

Selecting the Hover checkbox sets row highlights to ON. So, as you hover over an individual row the row highlights. Row highlights are great because they make your rows easier to read.

By default, this checkbox is unchecked.

Bordered

Selecting the bordered checkbox sets borders to ON. So, gray borers appear around the hears and each row of your fieldset. This coloring is great because it makes your rows easier to read.

By default, this checkbox is unchecked.

Condensed

Selecting the Condensed checkbox makes the rows appear compressed with extra spacing removed. The effect you see depends on the custom CSS styles applies to your project. This condensed view let's you make better use of your available page realestate.

By default, this checkbox is unchecked.

Multiple Values

Checking the Multiple Values checkbox allows the end-user to select multiple sections in the table.

By default, this checkbox is unchecked.

Hidden

Shows or hides the component from view. Checking the Hidden checkbox hides the component in Express View. Unchecking the checkbox unhides the component. The component will always remain visible in the Module Builder.

By default, this checkbox is unchecked.

Disabled

Checking the Disabled checkbox, stops end-users interacting with the element in Express View. When your end-user hovers over the field, their cursor changes to alert them to the status change.

By default, this checkbox is unchecked.

Protected

When checked, the API call won't returns this field as part of the API call. Set to unchecked when you want the field returned as part of the call.

By default, this checkbox is unchecked.

Table View

Checking the Table View checkbox, the value shows in the submission. Uncheck the checkbox when you don't want the values to show.

By default, this checkbox is checked.

Persistent

When checked, Unqork stores values entered into the field on submission of the module. Set to unchecked when you don't want to store the values from this field in the database.

By default, this checkbox is checked.

NOTE   If you never check the box, the value stores as "null". If the box is checked, the value stores as "true". And if you uncheck the box again after checking it, the value stores as "false".

Required

When checked, an end-user must enter a value into the field before they can save an entry. Set to unchecked, when you want your end-user's entry is optional.

By default, this checkbox is unchecked.

Field Tags

Field Tags are one-word labels used to identify a group of components.

Acting as a type of Property ID group, Field Tags let you target two or more components using a single Decision or Initializer. For example, you could add a Field Tag like “tagForDecision” to multiple components. Then in the Input table of the Decision, you could reference the “tagForDecision” Field Tag. The Decision then affects all components with the “tagForDecision” Field Tag.

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

Adding a Data Grid Component

You can add a Data Grid component to any page in your Unqork application. For this use case, let's create a simple module. In this Data Grid, you'll ask your end-user to fill out some personal information about their account assets.

What You'll Need

To set up this use case you'll need:

  • 1 Data Grid component

  • 3 Text Field components

Configure the Data Grid Component

Think of your Data Grid component as a place to organize your components on your canvas. This component divides your module into 2 evenly spaced columns.

1. In the Module Builder drag and drop a Data Grid component onto your canvas.
2. Enter Accounts in the Label.
3. Enter datagrid in the Property Name.

4. Click Save.

Configure the Text Field components

Next, lets add 3 Text Field components for your end-user to enter their account name, type and balance. Apart from their Property IDs, all other settings are the same.

1. Drag and drop 3 Text Field components onto your canvas. Place these Text Fields next to one another in your Data Grid.
2. Enter the following Property IDs and Label Texts:

Property ID

Label Text

accountname

Account Name

accounttype

Account Type

accountbalance

Account Balance

3. Click Save.
4. Save your module.

Your module should look like this in Express View:

Changing a Data Grid's Component Settings

Let's revisit and make changes to your saved component's settings.

1. Hover over the Data Grid component.

A 5-button toolbar appears above the component on hover-over.

2. Click the (Settings) button to open the Configuration window.
3. Make changes to the component's settings as needed.
4. Click Save.
5. Save your module.

Moving a Data Grid Component

Let's move your component to a new position on your module.

1. Hover over the Data Grid component.

A 5-button toolbar appears above the component on hover-over.

2. Click and drag the (Move) button, dropping the component when it's in position.
3. Save your module.

Copying a Data Grid Component

Let's make a copy of your component using the Copy and Paste tools. Copy and Paste creates an exact copy of your component, matching all settings. The only noticeable difference between the two components is the Property Name. The Property Name on the new component automatically updates. Remember, every component should have a unique Property Name. Property Names are the main method used for tracking and connecting components in Unqork.

1. Hover over the Data Grid component.

A 5-button toolbar appears above the component on hover-over.

2. Click the (Copy) button.
3. Click the (Paste) button.
4. Update the copied component's settings as needed.
5. Save your module.

Removing a Data Grid Component

Lastly, let's delete your Data Grid component from your module.

1. Hover over the Data Grid component.

A 5-button toolbar appears above the component on hover-over.

2. Click the (Remove) button.
3. Save your module.

Lab

The completed Data Grid use case is located here: https://training.unqork.io/#/form/5f8081fa85a56f024db6fc50/edit.