Freeform Grid Component

Overview

The Freeform Grid component is a flexible, highly customizable grid component that allows you to create complex data and display interactions. At its foundation, the Freeform Grid component acts as a container for nesting other Unqork components. In Express View Express View is how your end-user views you application. Express View also lets you preview your applications to test your configuration and view the styling. 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., those nested components render in self-contained rows of the grid.

In addition to nesting simple input fields, you can also use the Freeform Grid component to nest logic components within the grid, creating row-level logic based on 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. inputs both inside and outside the grid. This also includes nesting components within already-nested components, such as displaying a fully-configured Uniform Grid within each row of the Freeform Grid.

The Freeform Grid component also brings flexible layout and styling options to the grid components line up. Its multiple layout options let you create a custom viewing and editing experience that's ideal for complex data display. The Freeform Grid uses a summary-detail view to display data in Express View. This summary-detail approach lets you easily convey information hierarchy.

The summary view is the at-a-glance layout. Summary view presents a subset or summarized view of your data. The summary view options include:

  • Stacked rows

  • Table

The detail view displays upon selecting a row from the summary view. From the detail view, you can explore details and perform actions like adding, editing, or deleting data. The detail view options include:

  • Accordion view

  • Modal view

  • Sidebar view

You can mix-and-match most summary and detail views. This gives you the flexibility to create custom layouts and complex display logic. For example, your end-user can review information at-a-glance by scrolling through stacked rows, then select a row to bring up a modal that shows more details.

The following GIF shows three different summary-detail view combinations, applied to the same Freeform Grid and data. The only configuration change between each clip is the detail view selected. In order: Rows and Sidebar, Rows and Accordion, and Rows and Modal.

You'll find the Freeform 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 Freeform Grid components to have freeformGrid 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 Panel components. 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. 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 Module Builder canvas.

Save Button

Click this button to save all setting  configuration changes and return to the Module Builder 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 Freeform 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.

Summary View Table

The Summary View table is where you set the information that displays in your grid's summary view. Define headings as well as what values to show under that heading.

Click + New to add a new heading.

The top-to-bottom order of rows in your Summary View table creates the left-to-right order of headings in Express View.

Setting

Description

Heading

Enter a heading to show in the summary view.

Property ID or Formula

Define the value to display under the heading. You can reference a single Property ID in the grid or use a formula that references multiple Property IDs. For example:

  • Using CONCATENATE to join the values of two Text Fields in the grid.
  • Using SUM to total the values of multiple Number components in the grid.

The Property ID or Formula field supports the same formulas as other Unqork components, like the Calculator component. This includes standard Excel formulas and Moment.js for Date Input fields. You can also string together formulas to create more complex formulas.

Customize Summary and Detail View Group

The following settings set the summary and detail view options for your Freeform Grid.

Setting

Description

Choose Summary View

Select which summary view your Freeform Grid uses:

  • Rows: Each row of the grid displays as a stacked row. The headings and values defined in the Summary View table show in each row. To display a row's full detail view, select the stacked row.

  • Table: Each row of the grid displays as a row in a table. The headings defined in the Summary View table display once at the top of the table. The accompanying values display as a row in the table. To display a row's full detail view, select the table row.

Customize Detail View

Select which detail view your Freeform Grid uses:

  • Accordion: The detail view expands below the row.

  • Modal: The detail view opens as a modal in the same frame.

  • Sidebar: The detail view displays as a sidebar in the same frame.

Modal Title

Displays when Customize Detail View is set to Modal.

Enter a title for the detail view modal.

Sidebar Title

Displays when Customize Detail View is set to Sidebar.

Enter a title for the detail view sidebar.

Additional Display Settings

Setting

Description

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

  • Cancel Row

  • Update 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
  • Cancel Row: Cancel
  • Update Row: Save
  • 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 Freeform 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 Saved: Fires the trigger when any row in the grid is saved.

Then...

Enter the Property ID of the component to trigger when the specified When... action occurs.

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.

When the maximum number of rows is met, the Freeform 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.

Invalid Row Error

An error message that displays when a specific row of the grid has any validation errors.

Structure of a Freeform Grid Component's Data

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

Data entered in the Freeform Grid component stores as an array of objects under a single key. The top-level key is the Freeform Grid component's Property ID. Each row added to the Freeform 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 Freeform 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 Freeform Grid component looks in the DevTools Console:

Freeform Grid Data Storage: Grid Cache and Submission Data Object

When working with the Freeform Grid component, it's important to understand there are two locations data from the Freeform Grid can be written to and read from:

  • Grid cache: Any data entered in the Freeform Grid is written to the cache. Cached data is temporarily saved in the browser, but the data only writes to the submission data object after a grid Save event occurs.
  • Submission data object (submission.data): The submission data object houses data for all components in the module. The Freeform Grid's data is accessible via the submission.data.[gridPropertyId] path. Data from the Freeform Grid component writes to the submission data object after a grid Save event.

To get a snapshot of data in the grid cache, you can use the following Angular command in the DevTools Console: angular.element(document.body).injector().get("CacheService").cache. To get a snapshot of data in the submission data object instead, use the following Angular command: angular.element('.unqorkio-form').scope().submission.

The following diagram shows a simplified flow of data in a module containing a Freeform Grid, after both a grid Save event and a module Save event:

In the above image, assume myGrid is the Property ID of the Freeform Grid component. submission.data.{gridPropertyID} is the data access path for the Freeform Grid's array of row objects.

The data from the input component outside of the Freeform Grid automatically syncs to the submission data object. The data from the input components inside the Freeform Grid, however, only automatically syncs to the grid cache. A grid Save event is required for the grid cache to sync to the submission data object. None of these changes, however, can save as a submission in the database until a module Save event.

The grid cache impacts how logic components nested inside a Freeform Grid behave. To learn about using logic components with the Freeform Grid component, including how to use grid referencing syntax, see the Uniform Grid and Freeform Grid: Logic and Referencing Syntax article in our In-Product Help.

Due to limitations of the grid cache, nesting an Advanced Datagrid component(s) is not supported in a Freeform Grid.

Adding a Freeform Grid Component

In this configuration, you'll use a Freeform Grid to let end-users list guests joining a reservation. This simple usage of the Freeform Grid component highlights its support for nesting components, including nesting components within already-nested components.

This configuration focuses on how to use the Freeform Grid component for basic information collection. To learn about more complex configuration scenarios, including notes on using logic components with the Freeform Grid, see the Uniform Grid and Freeform Grid: Logic and Referencing Syntax article in our In-Product Help.

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

What You Need

For this configuration, you need:

  • 1 Freeform Grid component
  • 1 Columns component
  • 2 Text Field components
  • 1 Email component
  • 1 Uniform Grid component
  • 1 Phone Number component
  • 1 Dropdown component
  • 1 Radio Buttons component
  • 1 Text Area component
  • 1 Decisions component

Configure the Freeform Grid Component

For this configuration, the Freeform Grid uses the Rows summary view with a Modal detail view. The modal is where the end-user fills out all the fields nested in the Freeform Grid. The summary view then displays the values from some of the nested components, as defined in the Summary View table.

1. Drag and drop a Freeform Grid component onto the canvas.
2. In the Property ID field, enter freeformGridGuests.
3. In the Title field, enter Guests.
4. In the Helper Text field, enter Please list all guests who will be on this reservation.
5. Complete the Summary View table as follows:
Heading Property ID or Formula

Guest Requests

requests

Email

email

Full Name

=CONCATENATE(firstName, " ", lastName)

By using a concatenation formula that references the firstName and lastName Property IDs, the summary view can include the guest's full name while the submission data stores individual values.

6. Select Rows from Choose Summary View.
7. Select Modal from Customize Detail View.
8. Set the Customize Button Styling toggle to ON.
9. Under 'Add Row' Button, in the Button Label Text field, enter Add Guest.

10. Click Save.

Configure the Columns Component

A Columns component helps structure and organize the modal.

1. Drag and drop a Columns component onto your canvas, placing it inside the Freeform Grid component.
2. In the Property ID field, enter col1.
3. Under Column Layout, select the icon displaying 3 evenly-spaced columns.
4. Click Save.

Configure the Text Field Components

The following 2 Text Field components and the Email component collect some basic information about the guest.

1. Drag and drop 2 Text Field components onto the canvas, placing one in column 1 of the Columns component, and the other in column 2 of the Columns component.
2. Complete the Property IDs and Label Text as follows:
Property ID Label Text

firstName

First Name

lastName

Last Name
3. Set the Required toggle to ON for both fields.
4. Save each component as you add it.

Configure the Email Component

1. Drag and drop an Email component onto the canvas, placing it in column 3 of the Columns component.
2. In the Property ID field, enter email.
3. In the Label Text field, enter Email.
4. Set the Required toggle to ON.
5. Click Save.

Configure the Uniform Grid Component

This Uniform Grid collects phone numbers, with the help of a nested Phone Number component and Dropdown component. Using a Uniform Grid makes it easy for the end-user to add multiple phone numbers, if needed.

1. Drag and drop a Uniform Grid component onto the canvas, placing it inside the Freeform Grid, below the Columns component.
2. In the Property ID field, enter uniformGridPhoneNumber.
3. In the Title field, enter Phone Number(s).
4. In the Helper Text field, enter Enter your phone number(s) below:.
5. Set the Customize Button Styling toggle to ON.
6. Under 'Add Row' Button, in the Button Label Text field, enter Add Number.
7. Under Set Number of Allowed Rows, in the Minimum field, enter 1.
8. Under Validation, in the Invalid Error field, enter Please add at least one phone number.
9. Click Save.

Configure the Phone Number Component

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

Configure the Dropdown Component

1. Drag and drop a Dropdown component onto the canvas, placing it inside the Uniform Grid component.
2. In the Property ID field, enter numberType.
3. In the Label Text field, enter Number Type.
4. Complete the Values table as follows:
Option Label Data Source Values

Mobile

mobile

Home

home

Work

work
5. Click Save.

Configure the Radio Buttons Component

The next 3 components, the Radio Buttons, Text Area, and Decisions components, work together. Based on the answer to the Radio Buttons, the Decisions component will either make the hidden Text Area component visible or keep it hidden.

1. Drag and drop a Radio Buttons component onto the canvas, placing it inside the Freeform Grid, below the Uniform Grid component.
2. In the Property ID field, enter requests.
3. In the Label Text field, enter Does this guest have any accommodation requests or other restrictions (e.g. allergies)?.
4. Complete the Values table as follows:
Option Label Value to Store in Submission Data

Yes

Yes

No

No
5. Set the Required toggle to ON.
6. Click Save.

Configure the Text Area Component

1. Drag and drop a Text Area component onto the canvas, placing it below the Radio Buttons component.
2. In the Property ID field, enter guestNotes.
3. In the Label Text field, enter Please list your accommodation requests or other notes:.
4. Set the Hide Field toggle to ON.
5. Click Save.

Configure the Decisions Component

The if/then logic for this Decisions component is:

  • If the end-user selects Yes in the requests Radio Buttons, then make the guestNotes Text Area visible.
  • If the end-user selects No, then keep the Text Area hidden.
1. Drag and drop a Decisions component onto the canvas, placing it below the Text Area component.
2. In the Property ID and Canvas Label Text fields, enter ruleRequests.
3. Set the Trigger Type to Watch.
4. Complete the Inputs table as follows:
Property ID Alias Type Required

requests

 

exact

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

guestNotes

visible
6. Complete the Micro Decisions table as follows:
requests guestNotes_visible

Yes

yes

No

no

7. Click Save.
8. 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 Freeform Grid Component's Settings

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

1. In the Module Builder hover over the Freeform 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 Freeform Grid Component

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

1. Hover over the Freeform 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 Freeform 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 Freeform 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 Freeform Grid Component

You can remove your Freeform Grid component from the module.

Deleting a Freeform Grid component deletes all the components inside the grid.

1. Hover over the Freeform Grid component.

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

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

Resources