Matrix Component

Overview

The Matrix component is a format component with input capabilities. As a Display & Layout component, it's easiest to show you what the Matrix component looks like. Let's take a look at the two possible appearances of the Matrix component.

Your first option is to use the Matrix component as a table of radio buttons. Here's how the table option for displaying the Matrix component looks in Express View:

Your second option is to use the Matrix component inline with the rest of your module. Here's how the second option looks in Express View:

For logic-based configurations, you can also assign numeric values to your response options. For example, Strongly Agree = 5, Agree = 4, and so on.

You'll find the Matrix 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

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 calls.

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

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 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 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 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

Label Text

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

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

Rows/Collections

Use this table to set the row labels.

  • Label: The label text that appears on the left side of each row.
  • Value: Each option needs an associated value for storage with the data submitted. Enter your Values using this column.

By default, the value is a camel case version of the Label. You can also assign a numeric value to each option for use in logic-based configurations.

Columns/Properties

Use this table to set the column headers.

  • Label: The label text for each column header. This is the text that the end-user sees at the top of each column.
  • Value: Each option needs an associated value for storage with the data submitted. Enter your Values using this column.

By default, the value is a camel-case version of the Label. You can also assign a numeric value to each option for use in logic-based configurations.

Display Type

You can choose to display the Matrix component either as a Table or Inline.

  • Table: Table display is the standard matrix layout. It's a grid with columns and rows.
  • Inline: Inline display shows each collection one after the other, in a list-like layout. Each collection shows all options, displayed as a series of radio buttons.

Table

When using Table display, you can add a text field column to your Matrix component. This lets the end-user enter their own values. The text field column triggers when the end-user selects the triggering value. For example, if an end-user selects an option titled Other/Not listed. This selection could trigger a text field where the end-user can enter a specific value.

Selecting the Table choice chip opens the following settings:

  • Header for Optional Text Field Column: Shows as the label or header for the rightmost text field column.
  • Display Text Fields When Triggered By: Select which value triggers the text field column. Until the end-user selects this value, the text field column remains disabled.

Inline

When you select the Inline choice chip, the following setting appears:

Tooltip:

A short hint that displays when an end-user positions their cursor over the Questionmark Icon (Tooltip) icon. Tooltips can display across more than one line.

Hide Label

Setting the Hide Label to  (ON) hides Label Text from displaying in Express View. Your Label Text still displays in the Module Builder.

By default, this setting is set to (OFF).

Disable User Input

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

By default, Disable User Input is set to (OFF).

Read Only View

When set to  (ON), the component is display-only. If another component sends content to the field, the end-user can view that content. Otherwise, end-users see the word None.

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

Hide Field

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).

Custom CSS Class

Enter a Custom CSS 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.

Data Panel

Setting

Description

Store Data in Database

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

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

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

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

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

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

When using a Plug-In to remote execute a module, ensure data moving between modules is persistent. You can optionally enable Store Data in Database for components in the source module. But any components in the API module whose values are included in an API response must have Store Data in Database enabled. When a component’s data is not persistent, the data isn't included in an API call's response. So, Plug-Ins or external services requesting data from the API module can't receive non-persistent data in the response.

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

By default, the Store Data in Database toggle is set to ON.

Validation Panel

Setting

Description

Required

When set to  (ON), the end-user must enter a value in the component's visible fields. When set to (OFF), the input is optional.

By default, Required 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.

Adding a Matrix Component

In this scenario, you'll create a car insurance questionnaire. You'll use the default Table display option. These instructions assume that you have an open module saved with a title.

1. In the Module Builder drag and drop a Matrix component onto your canvas.
2. Enter surveyInsurance in the Property ID.
3. Enter Car Insurance Questionnaire in the Label Text.
4. In the Rows/Collection table, enter the following:

Label

Value

My car insurance is priced fairly.

myCarInsuranceIsPricedFairly

My car insurance does not provide enough coverage.

myCarInsuranceDoesNotProvideEnoughCoverage

My car is not worth insuring.

myCarIsNotWorthInsuring

Car insurance should not be required by law.

carInsuranceShouldNotBeRequiredByLaw

The Label column sets the row labels for your table.

5. In the Columns/Properties table, enter the following:

Label

Value

Strongly Agree

stronglyAgree

Agree

agree

Undecided

undecided

Disagree

disagree

Strongly Disagree

stronglyDisagree

The Label column sets the column headers for your table.

6. Click Save.
7. Save your module.

Once complete, your module should look like this in Express View:

Changing a Matrix Component's Settings

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

1. In the Module Builder hover over the Matrix component.

A 5-button toolbar appears 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 Matrix Component

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

1. Hover over the Matrix 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 Matrix 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 needs a unique Property ID. Property IDs track and connect components in Unqork.

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

Lastly, let's delete your Matrix component from the module.

1. Hover over the Matrix component.

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

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