Learn WorkXpress
The Expression Builder
In this class we'll discuss the Expression Builder, a visual tool that will enable you to build simple or elaborate expressions to manipulate information from your data layer and display it in your application.
Prerequisites
What You'll Learn
After finishing this lesson, you should be able to answer these questions:
- What is the Expression Builder?
- How do I access the Expression Builder?
- What are the individual parts of the Expression Builder and what are their uses?
What is an Expression?
An expression is something commonly thought of as a "formula". It is a combination of three things; (1) starting values, (2) manipulation of those values, and (3) a resulting value(s). Each of these properties of an expression is explained in greater detail below.
Starting Values
Starting values for an expression, if they exist, always come from the database. It is very important to note that you may have a static expression whereby you don't start with any values from the database. In a static expression you simply type in the result that you want to see output. When an expression starts with data from the database, it is referred to as a dynamic expression, because the expression results are variable based on the starting data pulled from the database.
Manipulation
Manipulation involes taking the starting data and transforming it into something else. Manipulation can involve the data itself or merely the appearance of the data (for example adding "bold" or increasing the font size). Manipulation may include the use of some combination of text or numerical functions, mathematical functions, application of html markup, and looping expressions and subexpressions.
In static expressions, manipulation simply involves entering the static values you wish your expression to output and, possibly, formatting them.
Resulting Value
What comes out of an expression is its resulting value. This is always the product of your starting values and the subsequent manipulation.
Your results can be either plaintext or html-enabled. Enabling html will attempt to present your results with html formatting enforced. Plaintext, on the other hand, will simply display all characters in the result, including any html tags that may be present.
Where is it?
To access the tool, click its icon (
) wherever you find it in the Block Editor or Action Manager tools. The
Expression Builder will launch in a separate browser window, and it
always launches with an attached Query Builder because the tools work
in tandem. The Query Builder is used to define starting data for your Expression Builder.
The Expression Builder has Seven (7) Parts
Let's break down each area of the Expression Builder and examine its use.
Fields, Field Parts and Output Format Selector
The image below shows the Expression Builder, with the Field/Part/Output Format selector highlighted.
Simply choose the Field, Field Part or Output Format you want, and press the green arrow to insert it into your Expression.
Function
The Field Selector reads Fields chosen in the attached Query Builder and allows you to select them to use in your Expression.
Often, a Field's Parts will be available in this selection area as well. Additionally, you can sometimes also choose Output Formats in this area. Field Parts and Output formats are described below. Fields, Field Parts and Output Formats populate the select list automatically once you have chosen their respective Field in the attached Query Builder.
Simply choose your Field, Field Part, or Output Format in the selectors and then press the green arrow to move that selection into the Expression Box area.
Field Parts
Field Parts are the components that taken together make up a certain Field. In the Query Builder you need only identify the Fields you want to pull from, but here in the Expression Builder you can break that Field into its Parts. For example, when you pull an Address Field from the Query Builder, you can work with the entire address in your expression but you can also work with its Field Parts such as City, State and Zip.
Output Format
Sometimes a Field could also give you Output Formats to work with. Output Formats are different ways to represent the same piece of information. For example a Date Field doesn't have any Field Parts, but it does have many possible Output Formats. Some examples include: Month Name, Month Name Abbreviated, Month Number, and Month Number with Leading Zero. These Output Formats display as January, Jan, 1 and 01 respectively.
HTML Formatting Options
This section of the Expression Builder allows you to add a variety of HTML formatting to the output of your expression. Use this section to cut, copy or paste text into and out of the Workspace, manipulate fonts and styles, change alignment, and create lists.
These controls insert actual hypertext markup language (HTML) into your Expression, however the Expression Box itself does not display the raw HTML, only the formatted results of it. To see the full expression as its HTML source code click the HTML button in the upper right hand corner of this section.
Functions
This section of the Expression Builder allows you to apply a variety of mathematic or text based functions.
Math Functions
Math functions require number fields, or strict numeric text extracted from a text field, function or subexpression in order to function properly. Use the "Arithmetic Function" choice to perform any type of mathematic calculation.
Choose the function you want and use the green arrow to insert it into the Expression Box. It will appear with its variables in place, but you will need to substitute your values or variables for the default ones.
Here is a list of math functions:
Arithmetic Functions Ceiling Count Count Distinct Currency to Text Display in Timezone Floor Now Number to Letters Product Round Sum
Text Functions
Text Functions perform in every way like the Math Functions above except they are focused on text or "string" manipulation.
Choose the function you want and use the green arrow to insert it into the Expression Box. It will appear with its variables in place, but you will need to substitute your values or variables for the default ones.
Here is a list of text functions:
Add to List Concat Implode Lowercase Remove from List Random String String Padding Substitute Substring Uppercase
Looping Functions
Sometimes you will develop data in your Query Builder that returns multiple items. You will need to understand how you want your expression to loop over each of these items to achieve your desired result.
For example, you may want to sum the "amount" Field for each value. Or, you may want to "concatenate", or join together, the names of each item in the result set, separated by commas.
Some functions are inherently "looping" functions, meaning by default they will loop over each item in the result set. The "Sum" function is a good example of an inherently looping function.
Other functions are designed to operate on a single result from a single item, and become "confused" when you pass it multiple items.
Turning on or off the "Looping Controls" intrinsically instructs the Expression Box to act as though it will or will not receive multiple items. This concept will be covered more in an advanced topic.
Loop Control
You may toggle the Loop Control function to allow this expression to loop through its results for those functions which do not inherently use looping, as described above. Please see the advanced topic on looping for a greater discussion of how and when to enable or disable looping controls in the Expression Builder tool.
Subexpressions
A subexpressions is simply a complete expression (including Query Builder) that is evaluated independently, and whose result is inserted into an expression. You can nest as many subexpressions as you like into your expression, or into each other. The diagram below highlights a newly created tab for "Subexpression 1".
To create a subexpression, simply click the + sign. This will add a Subexpression Tab to the top of your Expression Builder tool, and that tab will contain a full Expression Builder interface. To insert a subexpression result into your expression, simply select it and press the green arrow to insert it into your Expression Box.
Expression Box
The Expression Box contains the body of the expression you are building. Here, you will manipulate your starting values (Fields, Field Parts, Output Formats) and this is where you will apply HTML formatting. You will insert Math and Text Functions, as well as subexpressions, here.
Of course, as the example above shows, you an always just type in static text (referred to as a static expression). in this example, the result of this expression will always simply be the words "Search Contacts" and it will always be formatted exactly as shown.
HTML/Text toggle
The HTML/Text toggle allows you to choose to return results as HTML or plaintext. Choosing to display your results as HTML will output formatted HTML with any of the HTML options you've chosen to use in your expression. Outputting the results of your expression as plaintext allows you to preserve and present any HTML source code in addition to the values you intended to output.
Said differently, Use the HTML/Text toggle to determine how you want to present your results.
So for example, lets say you are outputting the word "result" but bolded to appear as "result". with HTML toggled on, your expression will output "result". With Text toggled on, your expression will output <strong>result</strong>
Conclusion
This class introduced you to the Expression Builder in WorkXpress. You access the Expression Builder from a Field Type in either the Edit Blocks or Actions Manager tools, and you use the Expression Builder to build dynamic or static expressions. Dynamic expressions involve querying the database using the attached Query Builder, manipulating those query results, and finally, outputting your expression result.
For starting values you can use Fields, Field Parts, and Output Formats of Fields. To manipulate those you can use HTML, mathematical and text functions, subexpressions, looping controls, and the Expression Box.
Finally, you can toggle whether to output your results as HTML or as Text. Whatever you choose, the fourth of our five Tools, the "Expression Builder", is a very powerful device to manipulate data in WorkXpress, and you will use it frequently.
We'll finish our examination of the five fundamental WorkXpress tools in The Action Manager.
