CMS: Using CMS Expressions to Manipulate Text Strings

17 min read
Use CMS expressions to unlock the full potential of your CMS without the use of Velo or JS code.
 
Expressions allow you to combine static text with dynamic values from multiple collection fields in a single string of text. Apply formatting to dynamic dates, times, and numbers to display them as needed. Construct mathematical equations that use Number fields in their calculations. You can even combine functions in the same expression to unlock endless possibilities.

About CMS expression functions

A CMS expression combines functions, literal values, and collection field values to present data on your site in new ways. 

After connecting a supported page element to a dataset, you can connect its text value(s) to a CMS expression. You then create an expression consisting of functions, field IDs, strings, numbers, and other syntax. The text in your connected element then displays the results of calculating the expression. 

Expressions consist of the following structure:

  • Functions: Define how to calculate the values that appear in parenthesis after the function, with values separated by commas (e.g. MULTIPLY(price, count), DAYS(_createdDate, NOW()), CONCAT("Created on ", _created Date)).
  • Field IDs: The unique identifiers of each collection field (e.g. title, _createdDate, clientName).
  • Strings: A sequence of characters that can include letters, numbers, symbols and spaces. 
    • String literals: A sequence of characters enclosed in quotes used to show static text (e.g. "Hello", 'Hello', '"Errata" by Kevin Young', "\"Errata\" by Kevin Young", "backslash is \\, forward slash is /").
    • Number literals: Numeric values used by the function (e.g. 123, 1000, 3.14).
    • Array literals: A way to express an array, which is an ordered collection of values, typically of the same type, enclosed in square brackets (e.g. [1,2,3], ["cat", "dog", "mouse"]). 
  • Special Constants: Predefined values that have a specific meaning within the scope of the function (e.g. true, false, undefined, null). 
Keep in mind that expressions are case-sensitive. When using fields within expressions, use field IDs rather than field names, and remember that field IDs are also case-sensitive.

As you type your expressions, you'll receive suggestions to help you correctly use the functions and field IDs. To make it easier to see the field IDs in your Editor, enable Dev mode.
Important info about writing expressions:
  • Enter the field IDs instead of the field names when referencing collection fields. Field IDs are unique identifiers for each collection field, unlike field names. 
  • Functions and field IDs are case-sensitive. Pay attention to the capitalization used in both.
  • For CONCAT functions, put 'static' string literal values in quotation marks. This includes static punctuation marks and spaces between referenced fields. 
  • If the function doesn't work, check the error message at the bottom of the Expression field for clues on how to fix the issue.  

Connecting elements to expressions in the dataset

To get started, connect the relevant element to the CMS and choose the Expression connection option. Then enter the expression you want to use. See the next sections for help with creating your expression.
Wix Editor
Editor X
Studio Editor
  1. In your Editor, click the element you want to connect to the CMS (e.g. text, button, gallery).
  2. Click the Connect to CMS icon .
  3. Click the Choose a dataset drop-down and select an existing dataset that connects to your collection. Alternatively, click Create a New Dataset, then choose the collection you want to connect.
  4. Click the relevant drop-down under Connection options and select Expression
  1. Click the Expression field.
  2. Enter the name of the function you want to use (e.g. CONCAT, DATE, TEXT).
    Tip: Once you start typing, you can select from a list of possible functions to use. 
  1. Type an opening parenthesis: (
  2. Enter the field IDs or values you want to use in the expression. As you type, a list of matching field IDs that you can select from appears. 
  3. Type a closing parenthesis: )

Expression examples

Check out the examples for writing different types of expressions in the following sections. 

Combining values from several fields using string concatenation

Use the CONCAT function to combine values from several different collection fields into a single text field. Add your own text to the function to combine static characters with dynamic values. The static characters don't change, while the dynamic values change based on the item retrieved by the dataset. Make sure to put all static text in quotes, including spaces and punctuation marks (e.g. " " or ",").
 
You can use different functions to do similar things, and you can also combine functions within functions for more advanced tasks. If there's a problem with the expression, check the error message for clues on how to resolve it.
An example for using the CONCAT function is to create custom text for a dynamic item page introduction. The text could introduce each member by name, mention their job title, and how long they've been with the company. Here's what that expression would look like:
1CONCAT("Our ",jobTitle,", ",title,", has worked here since ",date,".")
In this example:
The jobTitle field ID represents the collection field with each member's job title. The title field ID is for the field with the names of each member. The hireDate key is from a field with the employee start date of each member. Notice how all the static text and punctuation is surrounded by quotes. 
View the table below for more basic examples of using the CONCAT function:
Use case
Expression
Example
Result
Combine field values without spaces or punctuation
CONCAT(value,value)
CONCAT(title,jobTitle)
Brian ChangVP Product
Combine field values separated by a comma and a space
CONCAT(value,", ",value)
CONCAT(title,", ",jobTitle)
Brian Chang, VP Product
Combine static text with field values
CONCAT("Hello, ",value)
CONCAT("Hello, ",title)
Hello, Brian Chang
Combine field values with static text at the beginning and end
CONCAT("Hello, ",value,", welcome back.")
CONCAT("Hello, ",title,", welcome back.")
Hello, Brian Chang, welcome back.

Date/time formatting

When you want to control how dates and times are formatted on your live site, or calculate values from dates, use date/time functions. These functions work with Date, Time, and Number field types.
In the example above:
The DAYS function returns the number of days between a dynamic dueDate field and today's date. Notice how it combines the DAYS function with the TODAY function, as well as the CONCAT function used for merging static and dynamic text. 
Click the relevant function below to learn more about it:

Number formatting with the TEXT function

Use the TEXT function to apply formatting to numbers. For example, you could format values from a Number field type as a currency or percentage. 
In the example above:
The TEXT function formats a Number field type (price) as a dollar amount. Notice how the TEXT function is inserted within a CONCAT function, which adds the static text before the price. 
Click below for examples of using the TEXT function:

Mathematical functions

You can use mathematical functions to perform calculations based on different Number field types and/or static numbers. 
In the example above:
The MINUS function calculates 20-11=9. The 20 value is static, while the Number field value (rewardPoints) is dynamic. Notice how the expression inserts the MINUS function within the CONCAT function, which combines static text with dynamic values. 
View the table below for more examples of using mathematical expressions: 
Use case
Expression
Examples
Results
Calculate the sum of 2 numbers
ADD(value,value)
ADD(number1,number2)

ADD(4,20)
24
Calculate the difference between 2 numbers
MINUS(value,value)
MINUS(number1,number2)

MINUS(100,1)
99
Calculate multiplying 2 numbers
MULTIPLY(value,value)
MULTIPLY(number1,number2)

MULTIPLY(2,4)
6
Calculate 1 number divided by another
DIVIDE(value,value)
DIVIDE(number1,number2)

DIVIDE(10,2)
5
Return "true" if 2 values are equal and "false" otherwise
EQ(value,value)
EQ(number1,number2)

EQ(200,200)
true
Raise a number ('x') to the power of another number ('y')
POW(x,y)
POW(2,3)
POW(3,3)
8
27
Checks if two values are equal
EQ (Equal)
EQ(5,5) 
true
Checks if two values are not equal
NE (Not Equal)
NE(5,7)
true
Checks if one value is greater than another
GT (Greater Than)
GT(7,5)
GT(7,7)
true
false
Checks if one value is less than another
LT (Less Than)
LT(5,7)
LT(7,5)
true
false
Checks if one value is greater than or equal to another
GTE (Greater Than or Equal)
GTE(7,5)
GTE(5,5)
GTE(5,4)
true
true
false
Checks if one value is less than or equal to another
LTE (Less Than or Equal)
LTE(5,7)
LTE(5,5)
LTE(5,4)
true
true
false

FAQs

Click below for answers to common questions about using expressions. 

Did this help?

|