Screen Fields

Last updated 17/01/2024

What Are Screen Fields?

Screen fields are fields that are not attached to a database. When you add screen fields to your mail merge, they can become placeholders in your template.

The screen fields will be available on your mail merge and when data is entered, this data will be populated in your mail merge.

Let's take a look at the Christmas Party Invitation mail merge that was added in the Add a Mail Merge chapter.

As it currently stands the venue, date, and time are hard-coded in the mail merge. The following example will demonstrate how you can use screen fields to populate these values in the mail merge template.

Figure 1 - Christmas Party Invitation template

Add Screen Fields to a Mail Merge

1. Click the Screen Fields tab.

Figure 2 - Screen Fields tab

2. Click the Add Screen Fields button.

Figure 3 - Add Screen Fields button

3. Type a caption in the Caption field.

4. Click the lookup icon in the Display Type field and select a type.

Figure 4 - Add a screen field

5. Click the Save button in the form app bar.

Figure 5 - Save button

info

Continue to add as many screen fields as you require. For this example, two more screen fields were added, a Date field with a display type of _Date, and a Time field with a display type of _Time.

6. Click the General tab.

Figure 6 - General tab

7. Click in the Merge Text field.

Figure 7 - Merge Text field

8. Position your cursor where you want the placeholder.

9. Click the Tags icon.

info

All screen fields are available by clicking the Tags icon. When added to your template the placeholders will be available as

{{five.variable.<fieldID>}}

.

10. Select the placeholder (screen field).

Figure 8 - Tags

11. Continue to select all the placeholders you need.

Figure 9 - Christmas Party Invitation template

12. Click the Save button in the editor app bar.

Figure 10 - Save button

13. Click the Save button in the form app bar.

Figure 11 - Save button

How This Will Work in Your Application

1. Select the menu item holding your mail merge.

Figure 12 - Mail merge menu item

2. Type or select a value in each of the screen fields.

Figure 13 - Screen fields

3. Click the Run button.

Figure 14 - Run button

info

Your parameters will be displayed on the screen.

Figure 15 - Parameters

info

Your mail merge will hold the values entered into the screen fields.

Figure 16 - Christmas Party Invitation email

Filter Data Using Screen Fields

Screen fields can be used to filter data. The screen field gets passed in as a parameter to the query as a variable and then a _Lookup display type on the screen field can be used to filter who the mail merge is to be sent to.

The HR application will be used to demonstrate this. The HR application has several departments, as shown in the image below.

Figure 17 - Departments

Employees belong to a department, as shown in the image below.

Figure 18 - Employees

To demonstrate how this works, we will create a Department Meeting mail merge and select a department, the mail merge will only be sent to the employees belonging to the selected department.

This will require the following steps:

• Add a query selecting a Name, Email, and the other fields required for your results.
• Pass a parameter to filter the query, this needs to be named the same as the screen field ID and will be available on the
  variable
  property on the
  Five
  object.
• Create your mail merge with a screen field that has the display type of _Lookup.
• Create a menu item for the mail merge.

This documentation will explain how to filter the employees for a selected department. Only the employees belonging to the selected department will receive the mail merge.

Navigate to Queries

info

Step one is to create your query with a parameter to pass in the screen field ID.

1. Select Data in the menu.

2. Select Queries in the sub-menu.

Figure 19 - Queries menu item

Add Your Query

1. Click the Add Item button.

2. Type an ID in the Data Source ID field.

3. Click in the Query field to open Five's Query Builder.

Figure 20 - Add your query

4. Click the SQL tab

tip

You can use the Query Builder to create your query!

Figure 21 - SQL tab

5. Add your SQL.

info

The below syntax is the example being used.

• The DepartmentKey field from the Employee table is selected to know what department the employee belongs to.
• The FullName field from the Employee table is selected to have the recipient names.
• The Email field from the Employee table is selected to have the recipient email addresses.
• The DepartmentName field from the Department table is selected to display the department name in the email template.
• The
  WHERE
  clause is used to filter the employees belonging to the department. The
  ?
  parameter will hold the the screen field ID on the
  variable
  property on the
  Five
  object to filter the employees that belong to the selected department.

Department Meeting

SELECT
    Employee.DepartmentKey,
    Employee.FullName,
    Employee.Email,
    Department.DepartmentName
FROM
    Employee
INNER JOIN Department ON Employee.DepartmentKey = Department.DepartmentKey
WHERE Employee.DepartmentKey = ?

6. Click the Save button in the SQL Editor app bar.

Figure 22 - Save button

7. Click the Parameters tab.

Figure 23 - Parameters tab

8. Click the Add Parameters button.

Figure 24 - Add Parameters button

9. Type an ID in the Parameter ID field.

10. Type the parameter in the Parameter field, example

{{five.variable.DepartmentKey}}

.

info

{{five.variable.<screenFieldID>}}

must be used to pass in the screen field ID into the parameter.

Figure 25 - Add a parameter

11. Click the Save button in the form app bar.

Figure 26 - Save button

12. Click the Save button in the form app bar above the list.

Figure 27 - Save button

Navigate to Mail Merges

info

Step two is to create your mail merge with a screen field to pass in your parameter.

1. Select Tasks in the menu.

2. Select Mail Merges in the sub-menu.

Figure 28 - Mail Merges menu item

Add Your Mail Merge

1. Click the Add Item button

2. Type a title in the Title field.

3. Click the lookup icon in the Data Source field and select your query.

4. Click the lookup icon in the Name Field ID and select your name field.

5. Click the lookup icon in the Email Field ID and select your email field.

info

For this example, the SMTP From Name and SMTP From Email fields are not used as the mail merge will use the values in these fields on the Instances form.

6. Type a subject line in the Subject Text field.

Figure 29 - Add your mail merge

7. Click the Screen Fields tab.

Figure 30 - Screen Fields tab

8. Click the Add Screen Fields button.

Figure 31 - Add Screen Fields button

9. Type a caption in the Caption field.

caution

The value in the Field ID must match the value on the

variable

property in your parameter.

Example
The Parameter field on the Queries form holds the value:

{{five.variable.DepartmentKey}}

.

This means the Field ID for the screen field must hold DepartmentKey.

10. If required, change the value in the Field ID field to match the value on the

variable

property in your parameter.

11. Click the lookup icon in the Display Type field and select _Lookup.

12. Click the lookup icon in the Reference Form field and select a form to reference.

info

A _Lookup display type must reference a form that you have saved in Five. For this example, the Departments form is used. When in the HR application all the department names will be available to select in the mail merge screen field enabling you to filter by a department.

Figure 32 - Add a screen field

13. Click the Save button in the form app bar.

Figure 33 - Save button

14. Click the General tab.

Figure 34 - General tab

15. Click in the Merge Text field.

Figure 35 - Merge Text field

16. Use the icons in the toolbar to select your fields and design your template.

info

All your screen fields will be listed here with your data source fields.

Once you insert a screen field into your template, the placeholder will be available as

{{five.variable.<fieldID>}}

Figure 36 - Tags icon

17. Click the Save button in the editor app bar.

Figure 37 - Save button

18. Click the Save button in the form app bar.

Figure 38 - Save button

How This Will Work in Your Application

1. Select the menu item holding your mail merge.

Figure 39 - Mail merge menu item

2. Click the lookup icon in the screen field and select an option.

Figure 40 - Screen field

3. Click the Run button

Figure 41 - Run button

info

The mail merge will only be sent to the users that belong to the option selected. For this scenario, only the employees from the Administration department.