Use Case: Dashboard With Global Search

Overview

Your dashboard is only useful if it's easy to navigate. You may find that navigation becomes more difficult as more submissions appear on your dashboard. Adding search functionality can help.

What is Global Search?

Global search lets you search many submission fields at once using a single search bar. When you enter a search term, only submissions that contain your search term show in the dashboard.

Let’s say you have a dashboard that lists the following data for each submission:

  • First Name

  • Middle Name

  • Last Name

  • Email

  • Date of Birth

Most often, you'll find submissions based on their Last Name or Email fields. To do this faster, you can set up a global search that references those two fields at once.

This use case also includes steps for building a simple dashboard. The dashboard pulls submissions from the following source module: https://trainingx.unqork.io/#/display/5eb01aa6811bf80215fd706b. If you're following along from the Simple Dashboard article, you can skip pre-configuration.

Here's how your completed dashboard will look in Express View:

Here's how your completed dashboard will look in the Module Builder:

What You’ll Learn

In this article, you’ll learn how to set up a global search to reference specific fields in your dashboard.

What You’ll Need

To set up this use case, you’ll need:

  • 1 Panel component

  • 1 Initializer component

  • 2 Hidden components

  • 1 Plug-In component

  • 1 ViewGrid component

  • 1 Decisions component

  • 1 Submission Search template

The Submission Search template includes the following:

  • 1 Text Field component

  • 3 Hidden components

  • 1 Data Workflow component

  • 1 Calculator component

  • 1 Initializer component

  • 1 Plug-In component

Pre-Configuration

To build the above dashboard, continue as follows:

This Panel acts as a container for the components that follow.

1. In the Module Builder, drag and drop a Panel component onto your canvas.
2. Enter panelDashboard in the Property Name.
3. Click Save.

This Initializer component triggers the Plug-In component that you'll set up next.

1. Drag and drop an Initializer component onto your canvas. Place your Initializer inside the Panel.
2. Enter initStart in the Property ID and Label Text.
3. Select New Submission from the Trigger Type.
4. In the Outputs table, enter the following:
a. Property ID: enter pluginGetSubmissions.
b. Type: enter trigger.
c. Value: enter GO.

5. Click Save.

This is the first of 2 Hidden component in this configuration. This component houses the module ID of your source or submission module. You can pull the module ID from the source module’s hyperlink as follows: https://training.unqork.io/#/form/5eb01aa6811bf80215fd706b/edit.

1. Drag and drop a Hidden component onto your canvas. Place your Hidden component below the Initializer.
2. Enter moduleId in the Property ID and Label Text.
3. Enter 5eb01aa6811bf80215fd706b in the Default Value field. This is the source module's module ID.
4. Click Save.

This Plug-In connects your module to the outside world. To make this connection, you use an application programming interface (API). You'll use this Plug-In to get submissions to display in your dashboard.

1. Drag and drop a Plug-In component onto your canvas. Place your Plug-In below the moduleId Hidden component.
2. Enter pluginGetSubmissions in the Property ID and Label Text fields.
3. Select Manual from the Trigger Type.
4. Complete the Inputs table as follows:

Property ID

Mapping

moduleId

moduleId

'firstName,middleName,lastName,email, dateOfBirth'

fields

NOTE  The first row references the module ID stored in the moduleId Hidden component. The second row shows which fields you're pulling into the dashboard. Here, we'll pull the firstName, middleName, lastName, email, and dateOfBirth fields. The values entered in the Mapping column (moduleId and fields) are native values recognized by the Unqork Designer Platform. Add these as shown.

5. Select List Submissions for Dashboard from the Internal Service drop-down. The Request Type and Data Source URL auto-populate.

6. Click Save.

This is the second Hidden component in this configuration. It houses the submission ID.

1. Drag and drop a Hidden component onto your canvas. Place your Hidden component below your Plug-In.
2. Enter submissionId in the Property ID and Label Text.
3. Click Save.

Next, let's bring in a ViewGrid component to display your dashboard.

1. Drag and drop a ViewGrid component onto the canvas. Place your ViewGrid below the submissionId Hidden component.
2. Enter View Grid in the Label.
3. Enter gridView in the Property Name.
4. Enter View in the Action field.
5. Enter View in the Event field.
6. In the Inputs table, enter the following:
a. ID: enter pluginGetSubmissions.
b. Required: select Yes.
7. In the Outputs table, enter the following:
a. ID: enter submissionId.
b. Mapping: enter id.
8. In the Display table, enter the following:

ID

Formula

Heading

firstName

 

First Name

middleName

 

Middle Name

lastName

 

Last Name

email

 

Email

dateOfBirth

=MOMENT(MOMENT(dateOfBirth), 'format', 'MM/DD/YY')

Date of Birth

NOTE  The Moment.js in the Formula column formats the dateOfBirth values as MM/DD/YY.

9. Click Save.

This Decisions component provides the trigger for your dashboard's View button.

1. Drag and drop a Decisions component onto the canvas. Place it below your ViewGrid component.
2. Enter ruleButtons in the Property ID and Label Text.
3. In the Inputs table, enter the following:

Property ID

Type

Required

Silent

buttonClick

exact

No (not checked)

No (not checked)

moduleId

exact

No (not checked)

Yes (checked)

submissionId

exact

No (not checked)

Yes (checked)

NOTE  Every row in the Inputs table gets an associated column in the Micro Decisions table. If an input doesn't have a value in its Micro Decisions column, Unqork sets it to silent. In the next steps, you won't add values to the moduleId and submissionId columns. You'll only be using these inputs in the panelDashboard_pageOpen micro decision. So, you can mark these values as silent, or let Unqork do it for you.

4. In the Outputs table, enter the following:
a. Property ID: enter panelDashboard.
b. Type: enter pageOpen.
5. In the Micro Decisions table, enter the following:
a. buttonClick: enter View.
b. panelDashboard_pageOpen: enter =concatenate('/#/display/',moduleId,'/', submissionId , '/',moduleId). Replace moduleId and submissionId with your specific IDs.

6. Click Save.

Configure the Submission Search Template

Next, let's add the Submission Search template to your dashboard module. This template sets up your global search functionality, with a few adjustments. You can locate the Submission Search template by searching under Templates in the Module Builder.

1. In the Module Builder, drag and drop a Submission Search template onto your canvas. Place your template above your panelDashboard Panel.
2. Delete the moduleId Hidden component from the panelSubmissionSearch Panel.
3. Delete the pluginGetSubmissions Plug-In from the panelSubmissionSearch Panel.

NOTE  The Submission Search template includes a moduleId Hidden component and a pluginGetSubmissions Plug-In component. Because you already set these components up during pre-configuration, you can delete them from the template.

4. Save your module.

Update the Data Workflow Component

Next, we’ll update the Data Workflow component in the template to reference your chosen search parameter fields.

1. Hover over the dwSearchGlobalData Workflow component.

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

2. Using the toolbar, click the (Settings) button.
3. Click on the Create Field operator to open its Info window.

NOTE  Fields 1 and 2 already show the following formulas: CONCATENATE('{"data.PROPERTYNAMEONE":"/', _arg, '/i"}') and CONCATENATE('{"data.PROPERTYNAMETWO":"/', _arg, '/i"}'). PROPERTYNAMEONE and PROPERTYNAMETWO are the placeholders for the search parameter fields you’ll be referencing.

4. In Field 1, replace PROPERTYNAMEONE with email.

NOTE  The Property Name you enter here must match what’s listed in the ID column of the Inputs table in your pluginGetSubmissions Plug-In. This ties the search to the Email field of your dashboard.

5. In Field 2, replace PROPERTYNAMETWO with lastName.

NOTE  The Property Name you enter here must match what’s listed in the ID column of the Inputs table in your pluginGetSubmissions Plug-In. This ties the search to the Last Name field of your dashboard.

6. Click the Save button.
7. Save your module.

NOTE   Sometimes, you may want more than two search parameters in your global search. To reference more than two fields, enter the formula again in Fields 3–5 of the Create Field operator. Increase the sequence for each and replace PROPERTYNAME as needed. The resulting Info window will look like this:

Setting

Selection

Category

Formula

Label

Leave this blank.

Do Not Sanitize Formula

YES (checked)

Field 1

0 = CONCATENATE('{"data.PROPERTYNAMEONE":"/', _arg, '/i"}')

Field 2

1 = CONCATENATE('{"data.PROPERTYNAMETWO":"/', _arg, '/i"}')

Field 3

2 = CONCATENATE('{"data.PROPERTYNAMETHREE":"/', _arg, '/i"}')

Field 4

3 = CONCATENATE('{"data.PROPERTYNAMEFOUR":"/', _arg, '/i"}')

Field 5

4 = CONCATENATE('{"data.PROPERTYNAMEFIVE":"/', _arg, '/i"}')

To reference more than five fields, add another Create Field operator to the workflow. Then, continue the formula sequence. The resulting Info window will look like this:

Setting

Selection

Category

Formula

Label

Leave this blank.

Do Not Sanitize Formula

YES (Checked)

1

5 = CONCATENATE('{"data.PROPERTYNAMESIX":"/', _arg, '/i"}')

2

6 = CONCATENATE('{"data.PROPERTYNAMESEVEN":"/', _arg, '/i"}')

3

7 = CONCATENATE('{"data.PROPERTYNAMEEIGHT":"/', _arg, '/i"}')

4

8 = CONCATENATE('{"data.PROPERTYNAMENINE":"/', _arg, '/i"}')

5

9 = CONCATENATE('{"data.PROPERTYNAMETEN":"/', _arg, '/i"}')

Update the Text Field Component

Next, you'll update the Text Field component masterSearchGlobal. As configured in the template, it includes placeholder text that doesn't match this configuration. The placeholder text tells end-users what search parameters they can use. You'll update it to direct users to search by email or last name.

1. Hover over the masterSearchGlobal Text Field component.

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

2. Using the toolbar, click the (Settings) button.
3. Enter Search by email or last name in the Placeholder field.

4. Click Save.

Update the Plug-In Component

In order to add the search functionality to the dashboard, you'll update your pluginGetSubmissions Plug-In component.

1. Hover over the pluginGetSubmissions Plug-In component.

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

2. Using the toolbar, click the (Settings) button.
3. Enter /fbu/uapi/system/getSubmissions?{{data.searchGlobalFilterOr}} in the Data Source URL.

4. Click Save.
5. Save your module.

Summary

With this complete, your dashboard now has a search bar referencing the Last Name and Email fields. You can preview your dashboard in Express View and test the functionality.

Lab