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
- In your Editor, click the element you want to connect to the CMS (e.g. text, button, gallery).
- Click the Connect to CMS icon
. - 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.
- Click the relevant drop-down under Connection options and select Expression.
- Click the Expression field.
- 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.
- Type an opening parenthesis: (
- 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.
- 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.
Show me how to combine functions and display the year without the month or day
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:
DATE
DATEVALUE
YEAR
MONTH
DAY
HOUR
MINUTE
SECOND
DAYS
DAYS360
EDATE
EOMONTH
NETWORKDAYS
NETWORKDAYSINTL
NOW
TODAY
TIME
TIMEVALUE
WEEKDAY
ISOWEEKNUM
WEEKNUM
WORKDAY
WORKDAYINTL
YEARFRAC
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:
Convert a number to a currency format
Convert a number to a percentage (%) format
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.
Which elements can I use expressions with?
Where can I find the field IDs?
in the 
Did this help?
|