Placeholders for end-users
Discover how to create a placeholder system for dynamic text replacement in emails, notifications, and more.
Welcome to the Placeholder Guide!
In this guide, we'll explore how to create and implement a placeholder system that lets users define placeholders and seamlessly replace them with actual values. Whether you're managing email templates, internal notifications, generating dynamic text, or customizing user interactions, understanding and implementing placeholder systems can enhance efficiency and flexibility in your applications. Let's dive in and unlock the full potential of placeholders!
How does it work?
The placeholder system operates through a simple yet powerful mechanism. At the core of the placeholder system is the replace
function, which scans through text for predefined placeholder tags and substitutes them with corresponding values. These tags are sourced from a list of placeholder items stored in the database. Replacement values can be set in one of two ways: either by end users during runtime or by developers in the modeler using expressions.
Determining Placeholder Values
Placeholder values can be defined in two ways:
User-Defined Values: End users can set placeholder values during runtime. This approach allows for dynamic and flexible content based on user input.
Calculated Values: Developers can define placeholders with values calculated using expressions. This optional extension enables placeholders to have dynamically generated values at the moment of replacement, providing a more automated and contextual update.
Preparing the datamodel
Placeholder List
This list contains the placeholders and their corresponding replacement values.
PlaceholderLabel
ReplacementFunction (Calculated field) (optional)
ReplacementValue
Email Template List
In this example we also use a list of email templates:
Subject
Message
Created Emails List
This list stores the generated emails after placeholders have been replaced with actual values:
Subject
Sender
Receiver
Message
Expansion: Calculated Values
When using the calculated ReplacementFunction
for dynamic values, you will also need to create a concept for each optional calculated value. In this example we will use the following:
Placeholders (concept set)
Date
Time
Full Date and Time
Current Projects Count
Also, add a concept property called TagLabel
to the placeholder concept set. This will enable you to set a TagLabel
for each concept. This allows the user to set the full PlaceholderLabel
without retyping it, reducing errors from incorrectly copying the PlaceholderLabel
property.
Do not use punctuation marks or non-text characters in {PlaceholderLabel}
names. These characters have corresponding rich text tags that can break the replace function, as the values will not match correctly. This problem occurs when using plain text values and rich text as the source text.
For example, Recipient's
in plain text appears as Recipient's
in rich text. This difference can be observed by enabling the source option in the rich text input field's toolbar.
Flows and Screens
How your screens will look and feel highly depends on the specific implementation. For this guide we will make some screens and flows to explain how it works but are not real world implementations.
Email home page
The flow
The Interaction screen: Email & Placeholder Home
This page will serve as the main dashboard where you'll see the available email templates, the emails with replaced values, and the optional placeholders. It will also have buttons for key actions like creating emails with replaced placeholders and accessing the template and placeholder management page.
Manage Templates and Placeholders
The Flow
This flow revolves around the Manage templates and placeholder interaction screen. Here, we create, edit, and delete the placeholders or email templates. In the top right, the New placeholder node can be found. Here, we set the PlaceholderLabel
and PlaceholderValue
with a simple form. At the bottom right, there is a sub-flowchart for setting default placeholders. You typically do this only the first time an application is run.
The interaction screen: Manage
Again, on the left, we have the email templates with the subject and message as input fields and a button to add a new one at the top. On the right, we show a list of all placeholders and the options to reset to default or add a custom one. This gives users the ability to make/edit template texts and edit/add placeholders in the runtime letting users set it up.
Replacing PlaceholderLabel
PlaceholderLabel
The replacement flow
In this flow, several key processes are nested: first, there's the email template loop. Within this loop, there's the placeholder loop, which iterates through each placeholder. A decision node within the placeholder loop determines if the conditions are met to continue through Yes or No. This inner process repeats until all placeholders are processed. Then, the flow moves to the next email template, repeating until all templates are complete. The email template loop starts with adding a new email row and setting the subject and message fields with the template. The flow then continues into the placeholder loop.
The following expression is part of the decision node in the placeholder loop:
When this statement is true, the PlaceholderLabel
is replaced with the ReplacementFunction.
when false, the ReplacementValue
is used. The assignments part of the placeholder loop is the core business part of this flowchart. Here, the email message is assigned with the replacement function or value, replacing the original text. This is done with the following expressions:
Summary
Core Concepts:
Placeholder System: Operates through a replace function that scans text for predefined placeholder tags and substitutes them with values from a database. Replacement values can be either user-defined during runtime or calculated by developers using expressions.
Determining Placeholder Values:
User-Defined Values: Set by end users at runtime for dynamic content.
Calculated Values: Defined by developers using expressions for automated and contextual updates.
Data Model Preparation:
Placeholder List: Contains placeholders and their corresponding replacement values.
Email Template List: Stores email templates with subject and message fields.
Created Emails List: Stores generated emails after placeholder replacement.
Flows and Screens:
Mail Home Page: Main dashboard showing email templates, mails with replaced values, and placeholders. Includes buttons for creating mails and managing templates and placeholders.
Manage Templates and Placeholders: Allows users to create, edit, and delete placeholders or templates, and set default placeholders for initial application setup.
Replacement Flow:
Email Template Loop: Iterates through email templates.
Placeholder Loop: Nested within the template loop, replaces placeholders based on a decision node that evaluates whether to use calculated or static values.
Result
Reflecting on the placeholder system we've implemented, it offers a solution for inserting static or dynamically calculated results into user-defined texts. This system accommodates both fixed and computed placeholder values, making it adaptable for various applications. By going through text templates and replacing placeholder tags with the appropriate values, users can effortlessly generate contextually relevant content.
Example use-cases:
Notifications Internal notifications can be enhanced by using placeholders for descriptions or titles.
Email Applications that send standardized emails to lists of people.
Forms and Surveys Questionnaires that are more personal or include current time/date information
Documents Template documents can use placeholders for variable information.
Further Enhancements
Auto-fill PlaceholderLabels
PlaceholderLabels
The concepts made are already used to find the right ReplacementValue
for a function, but they can also help users with adding placeholders to texts.
On the user side of managing the template text, add buttons for each concept/placeholder option. This can be done with a list of 'default placeholders' representing the concepts in a repeater:
When a concept is selected, a flow runs that adds the
concept:'TagLabel'
property to the template text.
Last updated