Uniform Grid Component

Overview

The Uniform Grid is a highly-customizable grid component that you can use to fine-tune the data entry, viewing, and editing experience for end-users. At its foundation, the Uniform Grid component acts as a container for nesting other Unqork components. In Express View, those nested components render in self-contained rows of the grid. The Uniform Grid doesn't only support nesting simple input fields. You can also nest logic components within the grid, creating row-level logic based on end-user inputs. For example, showing or hiding fields in the row based on input to another component in that row.

With its traditional table-based layout, the Uniform Grid is well-suited to inline editing with data in full view. The Uniform Grid has flexible styling options and customizable interactions. For example, customizing how end-users can invoke the edit state of the whole grid or a selected row. The Uniform Grid works well when end-users need a rich data entry experience, without a set number of rows. Such as listing guests for a booking or adding beneficiaries to an insurance policy.

NOTE  The Uniform Grid currently supports nesting Primary Fields, Secondary Fields, and the following Data & Event Processing components used to configure logic: Calculator, Data Workflow, Decisions, Initializer, and Plug-In. Nesting other components can result in unexpected behavior.

TIP  While you can easily customize your Uniform Grid’s appearance, the Uniform Grid is best when a simple table layout is appropriate. For more advanced layout options, try the Freeform Grid component.

You'll find the Uniform Grid component under 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

Jump to:

General

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.

It's best practice for Uniform Grid components to have uniformGrid as a prefix in the Property ID.

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.

Settings Tab

Select this tab to display the component's Display, Data, Actions, and Validation settings panels, as applicable.

Permissions Tab

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.

Notes Tab

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.

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 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 the Hide Title toggle 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 Uniform Grid component's label 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:

  • Define Height by Unit: Define the grid height in pixels.

  • Auto Height: The grid height scales to show all rows.

Display Pattern

Defines the display pattern for components nested in the Uniform Grid component. By default, Display Pattern is set to Inline.

Labels

Select where nested components' labels display in the Uniform Grid.

  • Show as Column Headers: Labels display as column headers at the top of the grid only.
  • Show Inline: Labels display above the corresponding component in every row of the grid.
  • Hide Label: Labels do not display.

Hide Component

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

By default, the Hide Field toggle 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, the Hide Title toggle is set to OFF.

Customize Button Styling

When set to ON, customization fields display for the following buttons:

  • Add Row

  • Update Row

  • Edit Row

  • Delete Row

To customize each button, edit the fields displayed below the corresponding button's header.

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.

Each button has the following default Label Text:

  • Add Row: Create New
  • Update Row: Done
  • Edit Row: Edit
  • Delete Row: Delete

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's look and feel; there's no effect on the Button's function.

Custom CSS Class

Enter a Custom CSS Class to apply to the 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/.

Actions Panel

Triggers Group

The Uniform 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 trigger. The drop-down's options are:

  • Row is Added: Fires the trigger when a new row is added to the grid.

  • Row is Deleted: Fires the trigger when any row in the grid is deleted.

  • Row is Edited: Fires the trigger when any row in the grid is edited.

  • Row is Saved: Fires the trigger when the end-user clicks Done after invoking the edit state.

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 rows in Express View.

Setting

Description

Editing

Select how and where the end-user invokes edit state for a row. From the edit state, end-users can edit and delete rows. There are four options:

  • Full Grid Editable: All rows of the grid retain the edit state at all times.

  • Full Grid Editable via Global Edit Button: End-users control the edit state for all rows in the grid using a component-level Edit button. Clicking Edit makes all rows editable. Clicking Done makes all rows view-only.

  • Selected Entry Editable: End-users control the edit state at the individual row level, by selecting the row. Selecting a row makes the selected row editable. Clicking Done makes the selected row view-only.

  • Entry Editable via Edit Button: End-users control the edit state at the individual row level, using a row-level Edit button. Clicking Edit makes the selected row editable. Clicking Done makes the selected row view-only.

Validation Panel

Set Number of Allowed Rows Group

Setting

Description

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.

Maximum

Sets the maximum number of allowed rows in the grid.

NOTE  When the maximum number of rows is met, the Uniform Grid's Create New button is disabled and end-users cannot add any new rows.

Maximum Error Message

An error message that displays when the grid exceeds the maximum number of rows set.

Validation

Setting

Description

Invalid Error

An error message that displays when the grid has any validation errors.

Structure of a Uniform Grid Component's Data

Take a moment to understand how data entered in a Uniform Grid component stores, using the configuration from the Adding a Uniform Grid Component section.

Data entered in the Uniform Grid component stores as an array of objects under a single key. The top-level key is the Uniform Grid component's Property ID. Each row added to the Uniform Grid component 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 keys are the Property IDs of the components nested in the Uniform Grid. The values are those entered by the end-user in that row. Depending on the component type, values store as different data types and data structures. The following image shows an example of how two rows of data entered in a Uniform Grid component looks in the DevTools Console:

Adding a Uniform Grid Component

In this configuration, you'll use a Uniform Grid to let end-users list guests coming to an event. The Uniform Grid is great for simple data entry scenarios like this, especially when you don't know how many rows your end-user needs. Nesting input fields in the Uniform Grid makes it easy to collect information. To see how you can use logic components inside the Uniform Grid, the configuration includes a Decisions component that displays hidden fields based on the end-user's input.

NOTE  This simple configuration focuses on how to use the Uniform Grid component for basic information collection. You can add additional components and leverage features like validation and triggers for more complex functionality.

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

What You Need

For this configuration, you need:

  • 1 Uniform Grid component
  • 3 Text Field components
  • 1 Number component
  • 1 Single Checkbox component
  • 1 Decisions component

Configure the Uniform Grid Component

For this configuration, the Uniform Grid mainly uses the default settings. Customizing labels and helper text, however, helps guide the end-user.

1. Drag and drop a Uniform Grid component onto the canvas.
2. In the Property ID field, enter uniformGridRsvp.
3. In the Title field, enter Guest RSVP.
4. In the Helper Text field, enter Please list all guests who will attend the event.
5. Under Labels, select the Show inline radio button.
6. Set the Customize Button Styling toggle to ON.
7. Under 'Add Row' Button, in the Button Label Text field, enter Add Guest.

8. Click Save.

Configure the Text Field Components

The following Text Field components and Number component collect basic information about each guest.

1. Drag and drop 2 Text Field components onto the canvas, placing them inside the Uniform Grid component.
2. Complete the Property IDs and Label Text as follows:
Property ID Label Text

firstName

First Name

lastName

Last Name
3. Save each component as you add it.

Configure the Number Component

1. Drag and drop a Number component onto the canvas, placing it inside the Uniform Grid component, below the Text Fields.
2. In the Property ID field, enter age.
3. In the Label Text field, enter Age.
4. Click Save.

Configure the Text Field Component

The third Text Field component is a read-only field, used to display a message. You'll use the Decisions component to set when this Text Field displays.

1. Drag and drop a Text Field component onto the canvas, placing it inside the Uniform Grid component, below the Number component.
2. In the Property ID field, enter ageNotice.
3. In the Label Text field, enter Notice.
4. Set the Read Only View toggle to ON.
5. Set the Hide Field toggle to ON.
6. Click Save.

Configure the Single Checkbox Component

1. Drag and drop a Single Checkbox component onto the canvas, placing it inside the Uniform Grid component, below the third Text Field component.
2. In the Property ID field, enter minorGuest.
3. In the Label Text field, enter I understand that minors must be accompanied by an adult at all times.
4. Set the Hide Field toggle to ON.
5. Click Save.

Configure the Decisions Component

The Decisions component displays the read-only Text Field as well as the Single Checkbox component when certain criteria are met. In this case, when the end-user lists a guest who is below age 18. The Text Field displays a message noting the name of the guest who is underage. Then, the end-user must confirm that they understand all minors must be accompanied by an adult during the event.

1. Drag and drop a Decisions component onto the canvas, placing it inside the Uniform Grid component, below the Single Checkbox component.
2. In the Property ID and Canvas Label Text fields, enter ruleAdultCheck.
3. Set the Trigger Type to Watch.
4. Set the Execution Type to Merge. Because the same Property ID is in the Outputs table twice, using an Execution Type of Merge ensures both outputs targeting that field occur.
5. Complete the Inputs table as follows:
Property ID Alias Type Required

age

A

range

Yes

firstName

B

exact

Yes

lastName

C

exact

Yes
6. Complete the Outputs table as follows:
Property ID Type

ageNotice

visible

minorGuest

requiredAndVisible

ageNotice

value
7. Complete the Micro Decisions table as follows:
age_min age_max firstName lastName ageNotice_visible minorGuest_requiredAndVisible ageNotice_value

0

17

 

 

yes

yes

=CONCATENATE(B, " ", C, " is a minor. Please answer the following question.")

18

 

 

 

no

no

 

TIP  By using a concatenation formula that references the firstName and lastName Property IDs, the ageNotice message can include the guest's name.

8. Click Save.
9. Save your module.

You're now ready to test out your configuration. Click Preview Module to open your module in Express View. The completed configuration works like this in Express View:

Editing a Uniform Grid Component's Settings

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

1. In the Module Builder hover over the Uniform Grid component.

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

2. Using the toolbar, click the (Settings) button.
3. Using the configuration window, make changes to the component’s settings as needed.
4. Click Save.
5. Save your module.

Moving a Uniform Grid Component

You can move your component to a new position on your canvas.

1. Hover over the Uniform Grid component.

A 5-button toolbar displays 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 Uniform Grid Component

You can 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 ID. The Property ID on the new component automatically updates. Remember, every component must have a unique Property ID. Property IDs are the main method used to track and connect components in Unqork.

1. Hover over the Uniform Grid component.

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

2. Click the (Copy) button.
3. Click the (Paste) button.
4. Update the copied component’s settings, if needed.
5. Click Save.
6. Save your module.

Removing a Uniform Grid Component

You can remove your Uniform Grid component from the module.

NOTE  Deleting a Uniform Grid component deletes all the components inside the grid.

1. Hover over the Uniform Grid component.

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

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

Resources