Are you looking for a way to display content conditionally in Tassos’ extensions? Would you like to show text in Convert Forms Emails or Success Message based on user input? Or perhaps conditionally render content in EngageBox based on conditions such as visitor geolocation or device type? We've got you covered!
You can make all these scenarios happen using our if-else conditional shortcode in specific places in our Joomla extensions. The shortcode is a Pro-only feature and can be used with Convert Forms Pro and EngageBox Pro.
TABLE OF CONTENTS
- The Anatomy of a Shortcode
- Comparison Operators
- Conditions
- Condition Parameters
- Functions
- Shortcode Parameters
- Comparing Numbers
- Comparing Dates
- Troubleshooting
- General Rules
- To-do List
The Anatomy of a Shortcode
The shortcode expressions consist of the following parts:
Brackets
The special characters surround the tags IF and ELSE. Defaults to curly brackets { and }. This is configurable and may change per product.
IF Tag
The word used for opening and closing the shortcode expression. It is always surrounded by the Brackets, and it is case-insensitive. The closing IF Tag must begin a forward slash /. Defaults to the word “if”.
Condition Expression
The main building blocks of the shortcode. These are the rules that tell when the provided content will be displayed. Each condition expression returns TRUE or FALSE.
{if device=desktop}
A condition expression consists of 4 parts.
1. Condition Operand
This represents the left operand of the expression and should be the name of a supported Condition or a function result. The Condition Operand must always be placed before the Comparison Operator.
The resulting value from the Condition Operand will be compared against the Value Operand, and it can be in one of the following formats:
- Text (String)
- Number
- List (Array)
- Date Time
- True / False (Boolean
- Null
2. Comparison Operator
The operator will conduct the comparison between the Condition and Value Operands. This can be the symbol (“=”) or the operator's name (“equals”). See Comparison Operators for a complete list.
3. Value Operand
This represents the right operand of the expression that will be compared against the Condition Operand. It can be a value of Text, List, Number, Date, or a Function result. The type of the Value Operand dictates the nature of the comparison. The Value Operand must always be placed after the Comparison Operator.
{if condition=uservalue}
If the Comparison Operator supports multiple values, separate each value with a comma.
{if condition=1,2,3}
The shortcode can detect condition values without needing quotes (single or double). For instance, to display content on mobiles only, you can use any of the following syntaxes:
{if device=desktop}
{if device="desktop"}
However, when the value contains special characters such as !, =, *, ^, ~, <, >, using quotes is mandatory to prevent unwanted results. Both single and double quotes are supported.
{if condition="some_f^nky_valu3"}
4. Condition Parameters
A condition can have parameters that adjust the condition’s behavior. A condition parameter must be placed right after the Value operand and be prefixed with double dashes.
{if condition=value —-param1=value1}
Multiple condition parameters must be separated with a space.
{if condition=value —-param1=value1 —-param2=value2}
The condition parameters are distinguished into two categories. The local and the global parameters. The global parameters can be used almost by any condition, while local parameters are supported explicitly by certain conditions.
Logical Operators
To chain multiple conditions, you must use the logical operators AND and OR. All conditions in a shortcode must be chained either by AND or OR. Both operators are case insensitive, meaning you can write it either as “and” or “AND”.
To display content when all conditions are met, use:
{if condition1=value AND condition2=value AND condition3=value}
To display content when any of the conditions are met, use:
{if condition1=value OR condition2=value OR condition3=value}
When using the OR operator, the condition evaluation stops when the previous condition is not met to prevent unnecessary operations.
Using AND and OR operators on the same shortcode has yet to be supported. Therefore, the following example is currently not supported:
{if condition1=value AND condition2=value OR condition3=value}
Content
It represents the content displayed when the conditions are met. It must be placed after the opening IF Tag. It can be anything from plain text to HTML or even shortcodes.
{if condition=value}
// Content here
{/if}
Alternative Content
To display alternative content when the provided conditions are not met, place the word “else” surrounded by the Brackets after opening the IF Tag, followed by the alternative content.
{if condition=value}
// Content here
{else}
// Alternative Content here
{/if}
Shortcode Parameters
The parameters that affect the behavior of the shortcode expression. A shortcode parameter must be placed within the IF Tag before the closing Bracket. For a list of supported parameters, see Shortcode Parameters.
Comparison Operators
Comparison operators, as their name implies, allow you to compare two values. Below, you can find a list of all supported operators.
| Title | Syntax Name | Syntax Symbol | Expected Format |
|---|---|---|---|
| Equals | equals | = | Any Format (Multi-value) |
| Contains | contains | *= | Text |
| Starts with | startsWith | ^= | Text |
| Ends with | endsWith | $= | Text |
| Matches | matches | ~ | Text |
| Contains Any | containsAny | List (Multi-value) | |
| Contains All | containsAll | List (Multi-value) | |
| Contains Only | containsOnly | List (Multi-value) | |
| Less Than | lessThan | < | Numeric, Date |
| Less Than or Equal | lessThanEqual | <= | Numeric, Date |
| Greater Than | greaterThan | > | Numeric, Date |
| Greater Than or Equal | greaterThanEqual | >= | Numeric, Date |
| Empty | empty | Any Format |
Equals
Determine whether a value equals another value.
This operator works with any value type and can conduct numerical, date, and text comparisons. The type of the Value Operand dictates the nature of the comparison. When it’s identified as a Date, the comparison is conducted chronologically; if it is identified as a number, it is conducted numerically; otherwise, it proceeds with a text comparison.
Let’s see some examples:
A visitor is detected browsing your site with a Desktop. The following shortcode will return true:
{if device = desktop}
You can also check the opposite; if the visitor is not using a mobile by prefixing the operator with a “!”:
{if device != mobile}
Since the operator accepts multiple values, we can provide a set of values separated by a comma. Supplying multiple values implies that the expression will evaluate to true if any of the values in the set align with the Condition Operand. The following example will return true if the visitor is found to be using a desktop or a tablet device.
{if device = desktop, tablet}
The same behavior concerns list-based conditions such as the User Group, which returns multiple values, e.g., all the visitor’s user groups. When this operator is used with this type of condition, it will return true when the Condition Operand contains the Value Operand or any value in the Value Operand set. Consider this behavior as a shortcut emulation of the Contains Any operator.
Let’s say a logged-in user is assigned to the Registered and Manager groups. The following examples will return true because “Registered” is one of the visitor’s groups.
{if user.group = Registered}
{if user.group = Registered, Author}
Contains
Determine whether a text contains another text.
Let’s say a condition returns “lorem ipsum dolor”. The following shortcodes will return true:
{if condition contains dolor}
{if condition contains lor}
{if condition contains "em ip"}
{if condition !contains "amet"}
White, the following will return false:
{if condition contains ipsumdolor}
{if condition contains " lorem"}
{if condition !contains "lorem"}
Contains Any
Determine whether a list contains any elements in the given set.
Let’s say a condition returns the following list:
- red
- blue
- green
The following shortcodes will return true:
{if condition containsAny red, blue}
{if condition containsAny blue, black}
{if condition !containsAny black}
{if condition !containsAny red, black}
While the following will return false:
{if condition containsAny black, white}
{if condition !containsAny red, blue}
Contains All
Determine whether a list contains all elements in the given set.
Let’s say a condition returns the following list:
- red
- blue
- green
The following shortcodes will return true:
{if condition containsAll red, blue}
{if condition containsAll red, blue, green}
{if condition containsAll red}
{if condition !containsAll black, white}
While the following will return false:
{if condition containsAll red, blue, white}
{if condition !containsAll red, white}
Contains Only
Determine whether a list contains only the elements in the given set, excluding repeated elements. Let’s say a condition returns the following list:
- red
- blue
- blue
- green
The following shortcodes will return true:
{if condition containsOnly red, blue, green}
{if condition !containsOnly red, white}
While the following will return false:
{if condition containsOnly red}
{if condition containsOnly red, blue}
{if condition !containsOnly red, blue, green}
Starts With
Determine whether a text begins with another text. Let’s say a condition returns the text “Saturday night plans”.
The following shortcodes will return true:
{if condition startsWith Sat}
{if condition startsWith Saturday night}
{if condition !startsWith night}
Ends With
Determine whether a text ends with another text. Let’s say a condition returns the text “Cats are the best!”.
The following shortcodes will return true:
{if condition endsWith best!}
{if condition endsWith !}
Matches
Determines whether a text matches against a regular expression. The comparison returns true if at least one match is found. Because regular expression patterns contain special characters, the pattern must be wrapped with quotes (single or double).
Let’s say a condition returns the text: “The quick brown fox jumps over the lazy dog. It barked.”
The following shortcodes will return true:
{if condition matches "[A-Z]"}
How to pass modifiers?
{if condition matches "/[A-Z]/gm"}
Greater Than
This operator is designed to handle both Numeric and Date values. The type of the Value Operand dictates the nature of the comparison. When it’s identified as a Date, the comparison is conducted chronologically; otherwise, it proceeds numerically.
Let's explore some examples of numeric handling. In a scenario where the Condition Operand yields a value of '5', the following shortcodes will evaluate to true:
{if condition > 0}
{if condition greaterThan 4} // You can also use the operator's name
{if condition > 4.5} // Decimal numbers are also accepted.
While the following shortcode will be evaluated as false:
{if condition > 5}
Now, let’s explore some examples of date handling. In a scenario where the condition yields a value of '2023-10-25', the following shortcodes will evaluate to true:
{if condition > 2023-10-20}
{if condition greaterThan 2023-10-23}
While the following will return false:
{if condition > 2023-10-26}
For more details about date comparison, see Comparing Dates.
Greater Than or Equal
This operator is designed to handle both Numeric and Date values. The type of the Value Operand dictates the nature of the comparison. When it’s identified as a Date, the comparison is conducted chronologically; otherwise, it proceeds numerically.
In a scenario where the Condition Operand yields a value of '5', the following shortcodes will evaluate to true:
{if condition >= 0}
{if condition greaterThanEqual 5} // You can also use the operator's name
As with the Greater Than operator, this operator can also compare dates.
Less Than
This operator is designed to handle both Numeric and Date values. The type of the Value Operand dictates the nature of the comparison. When it’s identified as a Date, the comparison is conducted chronologically; otherwise, it proceeds numerically.
In a scenario where the Condition Operand yields a value of '5', the following shortcodes will evaluate to true:
{if condition < 10}
{if condition lessThan 4} // You can also use the operator's name
As with the Greater Than operator, this operator can also compare dates.
Less Than or Equal
This operator is designed to handle both Numeric and Date values. The type of the Value Operand dictates the nature of the comparison. When it’s identified as a Date, the comparison is conducted chronologically; otherwise, it proceeds numerically.
In a scenario where the Condition Operand yields a value of '5', the following shortcodes will evaluate to true:
{if condition <= 10}
{if condition lessThanEqual 4} // You can also use the operator's name
As with the Greater Than operator, this operator can also compare dates.
Empty
Determine whether the Condition Operand holds a meaningful value. The expression evaluates to true if the Condition Operand meets any of the following criteria:
- Is invalid: The condition is not recognized or misspelled.
- Is null: The value is explicitly set to null.
- Is an empty text: The value is an empty text or string.
- Is false: The value is boolean false or equals to a “false” string.
This operator is the sole exception, as it does not accept a Value Operand.
{if condition empty}
To check the opposite and evaluate if the condition is not empty, you can use either of the following:
{if condition !empty}
{if condition}
Both of these shortcodes will yield the same result. Use the exclamation mark (!) as a prefix to signify negation, or simply omit the operator for a clearer and more concise expression.
General Rules
- An operator can be written with its name or symbol if it has one.
- All text-based operators perform a case-insensitive search. To work around this, provide the caseSensitive parameter.
- To signify negation and perform a negative comparison, prefix the operator with a “!”.
Conditions
| Title | Syntax Name | Return Format | Expected Value |
|---|---|---|---|
| User Group | user.group | LIst | The ID or the title of the User Group |
| User Access Level | user.access | LIst | The ID or the title of the Access Level |
| Menu | menu | Numeric | The ID of the menu item |
| Component | component | Text | The Joomla component name prefixed by com_. |
| Homepage | isHomepage | Boolean | True or false |
| Language | language | LIst | The 2-letter ISO 639-1 language code. |
| URL | url | Text | Part of the URL or the complete URL |
| Referrer | referrer | Text | Part of the URL or the complete URL |
| Device | device | Text | Any of desktop, tablet, mobile |
| Cookie | cookie | Text | A text representing the cookie value |
| IP | ip | Text | An IPv4 address, part of an IPv4 Address or an IPv4 range |
| New Visitor | isNewVisitor | Boolean | True or false |
URL
Display content based on the URL the visitor is currently browsing. The condition returns the complete URL, including the query string. In the Value Operand, you either pass a part of the URL or the exact URL.
To determine whether the visitor is browsing a specific URL, use:
{if url = https://www.mysite.com/path/page/}
To determine whether the visitor is browsing any page under your site’s Blog section, use:
{if url contains /blog/}
The above shortcode will match all the URLs containing “/blog/”.
Referrer
Display content based on the user’s previous URL. The value the condition returns can be a URL from your website’s domain or other domains, including the query string. In the Value Operand, you either pass a part of the URL or the exact URL.
Let’s say you have a single contact form on your site but multiple pages pointing to it. To determine whether a specific page referred the visitor, just provide the path of the URL:
{if referrer contains /mypage/}
To determine whether a visitor came from Facebook, provide Facebook’s hostname:
{if referrer contains facebook.com}
Device
Display content based on the visitor’s device category. Device categories include ‘Desktop’, ‘Mobile’, and ‘Tablet’. The following shortcode will display its content when the user is found to be using a desktop computer.
{if device = desktop}
To hide content from mobile users, use:
{if device! = mobile}
User Group
Display content based on the visitor’s user group. This condition returns a list of all visitors’ User Groups. It accepts either the ID or the English title of the user group as the Value Operand.
For instance, to output content only to registered users, use:
{if user.group=registered}
Or you may provide the ID of the Registered User Group:
{if user.group=2}
Use commas to separate multiple user groups:
{if user.group = 2,7,10}
To hide content from non-logged-in (guest) users, you can check whether the visitor belongs to the Guest user group:
{if user.group != guest} … {else} Please log-in first {/if}
User Access Level
Display content based on the visitor’s access level. This condition returns a list of all user access levels, and the Value Operand expects either the ID or the English title of the access level.
For instance, to output content only to registered users, use:
{if user.access = Registered}
Or you may provide the ID of the Registered Access Level:
{if user.access = 2}
Menu
Display content based on the Menu Item the visitor is currently browsing. The condition returns a number representing the ID of the menu item.
To determine whether the visitor is viewing a specific page, provide the ID of the menu item:
{if menu = 456}
To check multiple menu items at once, separate IDs with a comma:
{if menu = 123,456,789}
To determine whether the visitor is currently viewing a particular menu item or any of its child menu items, provide the "includeChildren" parameter.
{if menu = 456 -–includeChildren}
To determine whether the visitor is viewing any menu item that belongs to a particular menu type, provide the unique name of the menu type prefixed by “type.”. For instance, if your Menu Type is called “bottom”, use:
{if menu = type.bottom}
Homepage
Determine whether the visitor is on the homepage. This condition does not require to provide any value.
{if isHomepage}
To check if the visitor is not on the homepage, simply prefix the condition name with an exclamation:
{if !isHomepage}
Cookie (Coming Soon)
Show content based on the presence of a cookie or its specific content. This condition returns the value of the cookie if it exists.
To determine whether the cookie with the name ‘oreo” exists, use:
{if cookie.oreo}
To determine whether the value of our cookie equals a specific value, use:
{if cookie.oreo = myValue}
To determine whether our cookie starts with a specific value, use:
{if cookie.oreo startsWith myValue}
To check the presence of multiple cookies, use:
{if cookie.oreo AND cookie.chocolate}
Language
Show content based on the site's language by passing the 2-letter ISO 639-1 language code (en). You can also pass a language tag defined in RFC 3066 (en-GB) if you want to be more specific.
For instance, to determine whether the language is in Greek, use:
{if language = el}
Component
Show content based on the Joomla component the visitor interacts with by providing the component’s name prefixed by “com_”. For instance, to determine whether the visitor views a page from the Content component, use:
{if component = com_content}
IP
Show content based on the visitor's IP v4 address. For instance, to catch a specific IP address, use:
{if ip = 150.20.25.56}To catch all IP addresses starting with a certain number, use:
{if ip = 180.50}To catch an IP address range, define the range with a dash. The following example will catch all IP addresses starting from 180.50.0.1 up to 180.50.0.100
{if ip = 180.50.0.1-100}New Visitor (Coming Soon)
Show content based on whether the visitor is new or returning. This condition returns true or false; therefore, it does not require a Value operand. For instance, to target users who are coming to your site for the first time, use:
{if isNewVisitor}To catch a visitor returning back from a previous session, use:
{if !isNewVisitor}This condition relies on the following two cookies to work:
- tvp: The Visitor Persistent Cookie. It is always set whenever the Condition is used until the cookie is removed from the visitor's browser.
- tvs: The Visitor Sesssion Cookie. It expires after 20 minutes of inactivity.
Condition Parameters
The parameters that affect a condition’s behavior. They are supposed to be used with any condition. A condition parameter must be placed right after the condition’s value.
caseSensitive
The default setting for text comparisons is case-insensitive, meaning that letter case is disregarded. This means you are not required to know the precise case of the value returned by the condition to obtain a match with the Value Operand. For example, if you intend to showcase content exclusively to desktop users, you can input the Value Operand as "desktop", "DESKTOP", or even "DeSkToP" without affecting the matching process.
{if device=Desktop}
{if device=DeSkToP}
To work around this, provide the caseSensitive parameter as follows:
{if device=desktop —-caseSensitive}
Functions
Below is a list of built-in functions that can be used with the Condition and Value Operands.
today()
Returns the current date (without time) in the site’s timezone. This is useful when you want to check whether a date is in the future or the past.
{if date > today()}
Given that the today() function returns a date without time, the comparison ignores the time in the Condition Operand.
now()
Returns the current date and time in the site’s time zone. This is useful when checking whether a date, including the time, is in the future or the past.
{if date > now()}
date()
Parses the given date, which is formatted in the given format. This function makes shortcode treat a value as a date instead of plain text. If you are a developer, consider this function the equivalent of the createFromFormat PHP method.
Syntax:
date(date_expression, date_format, timezone)
The expression can be either a standard date format like 2023-20-18 or a relative format like “+5 days”, “tomorrow” or “2 days ago”.
dateDiff()
Returns the difference in days between 2 days. The function can accept a condition or a custom date in both arguments. The recommended date format for input is the US format: MM/DD/YY.
For instance, comparing the dates 07/20/2023 and 07/25/2023 will return 5.
{if dateDiff(07/20/2023, 07/25/2023) = 5}
count()
Returns the total numbers in a list. If used with text, it will return the total number of characters. This is rather useful
{if count(condition) = 2}
Shortcode Parameters
The parameters that affect the behavior of the shortcode expression. A global shortcode parameter must be placed within the IF Tag before the closing Bracket.
debug
If the shortcode doesn't produce the anticipated result, append the 'debug' parameter to reveal comprehensive information about the parsed shortcode. This detailed data will assist you in troubleshooting any potential issues.
{if condition=value —-debug}
noPrepareContent (To-do)
By default, the Content and Alternative Content are prepared using the Joomla Content Plugins before they are rendered. This is helpful when using shortcodes within the content you want to display conditionally. If you don’t want to prepare the content, set the prepareContent parameter to false as follows:
{if condition=value —-noPrepareContent}
excludeBots (To-do)
Restricting access to the content on your website for SEO bots and web crawlers like Google and Yahoo may cost you quite a bit. Of course, the content of your website is what drives the search results, so restricting SEO bots and web crawlers from accessing the content will inevitably position your website lower in the search results than you want. Our shortcode offers the excludeBots parameter for bypassing content restriction to non-human visitors.
{if condition=value —-excludeBots}
The bots are identified by certain HTTP_USER_AGENT strings.
Comparing Numbers
The Value Operand must be identified as numeric to conduct a numerical comparison. To compare numbers, you must use the following operators in the expression:
Let's explore some examples. In a scenario where the Condition Operand yields a value of '150', the following shortcodes will evaluate to true:
{if condition > 100}
{if condition >= 150}
{if condition lessThan 1000}
Check if a Number is Within a Range
To determine whether a number falls within a range, chain the Greater Than or Equal and Less Than or Equal operators with the AND logical operator. The following example checks if a number is between 100 and 200.
{if condition >= 100 AND condition <= 200}
Comparing Dates
To conduct a chronological comparison, the Value Operand must be identified as a Date. The suggested date format for input is the US format using the slash delimiter, ensuring that the first digit represents the month: MM/DD/YY.
If the Value Operand fails to be treated as a date, pass the value to the Date() function.
To compare dates, you must use the following operators:
Let’s say a condition returns the calendar date “7 October 2023 18:00”. The following shortcodes will return true:
{if condition = 10/07/2023}
{if condition > 10/06/2023}
{if condition < 10/08/2023}
The correct input date format is crucial for accurate results. The first digit must always represent the month. If, for any reason, the day is mistakenly placed as the first digit, the expression will yield unpredictable and incorrect outcomes. For example, the following condition will evaluate to false:
{if condition = 07/10/2023} // The detected date is: July 10th
Check if Date is Between Dates
To determine whether a date falls between a date range, combine the Greater Than or Equal and Less Than or Equal operators on the same shortcode. For instance, to check if a date is between 5 and 10 June, use:
{if condition >= 06/05/2023 AND condition <= 06/10/2023}
Compare Today
Use the today() function to compare a date to the current date. For example, the following shortcode checks if the condition date is in the future.
{if date > today()}
Calculate the Difference Between Dates
Use the dateDiff() function to calculate the difference between two dates in days. The following example checks if the number of days between two dates is more than 10.
{if dateDiff(check_in, check_out) > 10}
General Rules for Date Comparison
- If a date is provided without a specific time in the Value Operand, the comparison will also disregard the time in the Condition Operand.
Troubleshooting
Error Codes
001 - Syntax Error
002 - Invalid Condition
Condition X does not exist.
003 - Unknown Comparison Operator
The comparison operator X does not exist.
004 - Value Operand Must Be Quoted
A value that contains the special characters !, =, *, ^, ~, <, > must always be quoted with single or double quotes.
005 - Unsupported Comparison Operator
This error arises when a comparison operator designed to handle multi-value Condition Operands is provided with a single value. These operators are Contains Any, Contains All, and Contains Only.
In this case, we will see the following error:
“The Comparison Operator “containsAny” can only be used with Condition Operands that return multiple values. The Condition X returns a single value.”
This error also arises when a comparison operator designed to handle a single-value Condition Operand is provided with a multi-value. These operators are Contains, Starts with, Ends with, Matches, Less Than, Less Than or Equal, Greater Than, Greater Than or Equal
In this case, we will see the following error:
“The Comparison Operator “startsWith” can only be used with Condition Operands that return a single value. The Condition X returns multiple values.”
General Rules
- Conditions are processed from left to right.
- A Boolean Condition does not require a Comparison Operator and Value Operand.
- Whitespaces are allowed between conditions/parameters and their values.
What’s on the to-do list
Here is a preview of upcoming features on our roadmap, slated to be supported in an upcoming release.
- Support both AND & OR in the same expression
- Nested shortcodes
- Else-if
- Support parsing 3rd party shortcodes within the content
- Accessing Condition Operand value within the content
- Excluding bots from shortcode’s content
- Cookie Condition
Do you need a feature added to our to-do list? Let us know.