Using Smart Tags in Tassos extensions
Do you want to capture or display additional user or site data on your site? It can be tricky if you need more information like where the user came from or the page URL or want to automatically capture the logged-in user's name or email address. All of these things can be tracked efficiently with the help of Smart Tags.
This tutorial will show you how to use Smart Tags in Tassos extensions.
What is a Smart Tag?
A Smart Tag is a small piece of code that can be used in the settings of any Tassos extension that provides you valuable information about almost everything related to the moment the page is rendered. Smart Tags use curly brackets and look something like this:
{smart_tag}Site
Here, you will find a list of Smart Tags that return information about the site.
{site.email}
Returns the site's email address as set in the Joomla Global Configuration page.
{site.name}
Returns the site's name as set in the Joomla Global Configuration page.
{site.url}
Returns the site's base URL. An example of a base URL would be http://www.tassos.gr
Page
Here, you will find a list of Smart Tags containing information about the page being browsed.
{url}
It returns the complete URL of the page, including the query string.
Example:
https://www.site.com/blog/?category=123{url.path}
It returns the page URL without the query string. Example:
Example:
https://www.site.com/blog/{url.encoded}
It returns the complete URL of the page, including the query string, but encoded. For instance, if the current URL is https://www.site.com/blog/?category=123 the Smart Tag will return https%3A%2F%2Fwww.site.com%2Fblog%2F%3Fcategory%3D123. This is useful when you want to pass the URL as a parameter in another URL.
{page.title}
It returns the title of the page. If the page is behind a Menu Item, its Browser Page Title will be returned if not empty; otherwise, it falls back to the title as seen in the browser tab. Note that this Smart Tag may contain the site's name depending on whether or not the "Global Configuration > Site > SEO > Site Name in Page Titles" option is turned on.
If you want to display the title of a Joomla Article, use the {article.title} Smart Tag instead. Similarly, you can use the {menu.item} Smart Tag to fetch the Menu Item's title.
{page.desc}
It returns the page’s meta description. If the page is a Joomla Article with a meta description set, it will be returned. Otherwise, it falls back to the menu item’s page meta description.
{page.lang}
It returns the language code of the page. For example, if the page’s language is English or Greek, expect en-gb and el-GR as the returned value, respectively.
{page.langurl}
It returns the first part of the language code of the page. For example, if the page’s language is English or Greek, expect en and el as the returned value, respectively.
{page.generator}
Returns the value of the generator meta tag.
{page.browsertitle}
Returns the menu item’s Browser Page Title option even if it is empty.
{querystring.KEY}
Returns the value of a URL query string parameter as found in the $_GET superglobal array. For example, if the page URL is http://example.com/page.php?key1=red&key2=blue, the {querystring.key2} Smart Tag will return blue.
{post.KEY}
Returns the value of a post data as found in the $_POST superglobal array. For example, if you submit a form that consists of the “email” and “name” input fields, you can use {post.email} and {post.name} Smart Tags in the submitted URL to retrieve the value of any form input.
Menu Item
Use the {menu} Smart Tags to retrieve information about the currently visited Menu Item. This Smart Tag can return the value of any property from the Joomla MenuItem object as long as you know the property's name.
Syntax:
{menu.ITEM_PROPERTY}Below is a list of this category's most popular Smart Tags.
{menu.id}
Returns the ID of the Menu Item.
{menu.title}
Returns the title of the Menu Item.
{menu.alias}
Returns the alias of the Menu Item.
{menu.link}
Returns the actual link the Menu Item refers to.
Joomla User
Use the {user} Smart Tags to retrieve information about the currently logged-in user. This Smart Tag can return the value of any property from the Joomla User object as long as you know the property's name.
Syntax:
{user.USER_PROPERTY}Below is a list of this category's most popular Smart Tags.
{user.id}
Returns the ID of the user.
{user.name}
Returns the name of the user.
{user.firstname}
Returns the first name of the user.
{user.lastname}
Returns the last name of the user.
{user.login}
Returns the username of the user.
{user.email}
Returns the email address of the user.
{user.registerDate}
Returns the registration date of the user.
{user.groups}
Returns the IDs of the user groups comma-separated. Eg: 1,2,5.
{user.groupTitles}
Returns the titles of the user groups comma-separated. Eg: Public, Registered
{user.authLevels}
Returns the IDs of the user access levels comma-separated. Eg: 1,2,6
{user.authLevelTitles}
Returns the titles of the user access levels comma-separated. Eg: Public,Registered,Special
{user.field.FIELD_NAME}
Returns the value of a user custom field. Replace FIELD_NAME with the name of the custom field.
Notes
- All Smart Tags in this set will return an empty string if the user is not logged in.
- For security purposes, the “password” property can’t be accessed.
Joomla Content
Use the {article} Smart Tags to retrieve information about a Joomla article. This Smart Tag can return the value of any property from the Joomla Article object, including custom fields, as long as you know the property's name. It can access details from the current browsing article and any article by providing the article's ID using the --id property.
Syntax:
{article.PROPERTY [--id=ARTICLE_ID]}Replace PROPERTY with the name of the property from the article's object. To pull the property from a specific article, provide the --id option and replace ARTICLE_ID with the article's ID. Omit the --id option to use the currently browsing article.
Below is a list of this category's most popular Smart Tags.
{article.id}
Returns the ID of the article.
{article.title}
Returns the title of the article.
{article.introtext}
Returns the intro of the article.
{article.fulltext}
Returns the complete text of the article.
{article.images.image_intro}
Returns the intro image of the article
{article.images.image_fulltext}
Returns the full text image of the article
{article.alias}
Returns the alias of the article.
{article.link}
Returns the SEF URL of the article.
{article.user}
Return information about the article's author, such as the name, email address, or even a custom field. This Smart Tag can return the value of any property from the Joomla User object as long as you know the property's name. This property mimics the behavior of the User Smart Tag.
For instance, to retrieve the author's ID, use:
{article.user.id}To return the author's name, use the following:
{article.user.name}To retrieve an author's custom field value, use:
{article.user.field.FIELDNAME}{article.field}
Returns the value of an article custom field and any property from the field object, such as the title or the id.
Syntax:
{article.field.NAME.[PROPERTY] [--id=ARTICLE_ID]}Replace NAME with the name of the custom field. To pull the custom field value from a specific article, provide the --id option and replace ARTICLE_ID with the article's ID. Omit the --id option to use the currently browsing article.
For instance, let's say you have a custom field named "favoriteColor". To return its prepared value from the article with ID 150, use:
{article.field.favoriteColor --id=150}To return the field's raw value, use:
{article.field.favoriteColor.rawvalue --id=150}To return the field's ID, use:
{article.field.favoriteColor.id --id=150}The same goes for the Subform field. Let's say you have a subform field named "customers" which consists of 2 fields, "name" and "age".
The following shortcode will return all subform rows in a bullet list.
{article.field.customers}To display all the values of a specific row, you need to access the rawvalue property of the field and provide the row index:
{article.field.customers.rawvalue.0}The display the value of a specific field from a specific row, access the rawvalue property of the field, and provide the row index and the field's name.
{article.field.customers.rawvalue.0.age}Visitor Technology
This set of Smart Tags returns information about the visitor’s used technology, such as the device and the operating system used to browse the site.
{client.device}
Returns the type of device the user uses. Possible values:
- desktop
- mobile
- tablet
{client.os}
Returns the operating system of the user. Possible values:
- windows
- windows phone
- iphone
- ipad
- ipod
- mac
- blackberry
- android
- android tablet
- linux
{client.browser}
Returns the name of the user's browser. Possible values:
- ie
- firefox
- chrome
- safari
- opera
- edge
{client.useragent}
Returns the user agent string of the user.
Example:
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36{client.id}
Returns the 8-character hexadecimal ID representing the visitor's unique ID as stored in the nrid cookie in the visitor’s browser.
Example:
03bc431d0d605ce4Geolocation
This set of Smart Tags returns information about the visitor’s physical location. For this Smart Tags work, the Geolocation features must be enabled.
{geo.country}
Returns the visitor's country name. Eg: Greece.
The value of this Smart Tag supports translations via the NR_COUNTRY_[COUNTRY_CODE] language string.
{geo.countrycode}
Returns the visitor's country code. Eg: GR
{geo.city}
Returns the visitor's city name. Eg: Athens
{geo.region}
Returns the visitor's region.
{geo.location}
Return the visitor's geolocation (Country, City, Region).
Date Time
This set of Smart Tags returns information about the current date time respecting the timezone selected in the site’s global configuration.
{date}
Returns the current date time in format Y-m-d H:i:s. Eg: 2023-09-12 11:22:52.
To output the date with a custom format, pass the --format=FORMAT_OPTIONS option. List of available format characters.
- To output a date as 09/12/2023 use, {date --format=m/d/Y}
- To output a date as Tue, 12 Sep 2023, use {date --format=D, d M Y}
{day}
Returns the numeric representation of a day of the month without leading zeros. Eg: 22.
Use the {date} Smart Tag to output the current date of the week in another format. Examples:
- Day of the month, two digits with leading zeros such as 01 or 31. {date --format=d}
- A textual representation of a day, three letters, such as Mon or Sun. {date --format=D}
- A full textual representation of the day of the week, such as Sunday or Monday. {date --format=l} (lowercase 'L')
- ISO 8601 numeric representation of the day of the week, such as 1 (for Monday) through 7 (for Sunday). {date --format=N}
- Numeric representation of the day of the week, 0 (for Sunday) through 6 (for Saturday). {date --format=w}
- The day of the year (starting from 0) 0 through 365. {date --format=z}
{month}
Returns the numeric representation of the month without leading zeros. Eg: 5.
Use the {date} Smart Tag to output the current month in another format. Examples:
- A full textual representation of a month, such as January or March: {date --format=F}
- Numeric representation of a month, with leading zeros such as 01 or 12. {date --format=m}
- A short textual representation of a month, three letters, such as Jan or Dec. {date --format=M}
{year}
Returns a 4-digit numeric representation of the year. Eg: 2023. To output a 2-digit year, use {date --format=y}
{time}
Returns a 24-hour format of an hour with leading zeros. Eg: 20:30.
Utilities
This Smart Tags category consists of helper Smart Tags, such as retrieving the value of a cookie name or the visitor’s IP address or even crawling the DOM.
{cookie.COOKIE_NAME}
Returns the value of a cookie as stored in the visitor’s browser. Replace COOKIE_NAME with the name of the cookie.
{language.CONSTANT}
Returns the text of a language string. Replace CONSTANT with the language constant you want to return its text. For instance, to return the text of the language string COM_CONTACT_DETAILS, use {language.COM_CONTACT_DETAILS}.
{ip}
Returns the IP address of the visitor.
{referrer}
Returns the webpage URL where a person clicked a link that sent them to your site.
{randomid}
Returns an 8-character hexadecimal random ID. Example: 03bc431d0d605ce4.
{crawler}
Returns the value of a DOM element represented by a CSS selector. For instance, to get the div's text with a class “.phone”, use {crawler --selector=.phone}.
This Smart Tag supports the following functions:
- Return the text of a DOM element
Syntax: {crawler --selector=selector [--fallback=value]} - Return the HTML of a DOM element
Syntax: {crawler.html --selector=selector [--fallback=value]} - Return the Inner HTML of a DOM element
Syntax: {crawler.html --selector=selector --innerhtml=true [--fallback=value]} - Return the number of elements found
{crawler.count --selector=selector [--fallback=value]}
Note: If this Smart Tag is called before the onAfterRender event and the given CSS selector represents elements in the module's output, no nodes are likely found because the module's output still needs to be rendered.
To learn more details about CSS Selectors, visit: https://www.w3schools.com/cssref/css_selectors.php
Integrations
Below is a list of Smart Tags for 3rd party Joomla Extensions.
{acymailing.subscriberscount}
Returns the total number of subscribers of a specific list.
Syntax:
{acymailing.subscriberscount --list=LIST_ID}For instance, to count the subscribers for the list with ID 5, use {acymailing.subscriberscount --list=5}
Modifiers
Below is a list of options that can be used across all Smart Tags.
--layout
By default, all Smart Tags return a plain text value. For instance, the {device} Smart Tag will output “desktop” on desktop users. What if you want to wrap the value with a div and make it bold?
To do so, write:
{device --layout=<div><strong>%value%</strong></div>}The layout option expects a text or HTML with the %value% variable representing the Smart Tag value.
You may think that you don’t need this option as you can get the same result by just inserting the HTML and shortcode directly in the page like:
<div><strong>{device}</strong></div>You have a point that will work, but the main drawback of this method is that the outer HTML will be outputted in the page even if the Smart Tag returns an empty string. If the Smart Tag cannot determine the device type, you will be left with orphaned HTML tags. This may result in an undesired behavior. The layout option solves this issue by outputting the shortcode value only if it is not empty.
--prepareContent
If a Smart Tag returns a value that contains other shortcodes, those shortcodes will likely remain unparsed. To work around this, pass the --prepareContent option to enable Joomla Content plugin parsing.
{SmartTag --prepareContent=true}--shortNumber
Converts a number into a short version, eg, 1000 -> 1k and 10000 =-> 10K
{SmartTag --shortNumber=true}--filter
Use this modifier to filter the output of a Smart Tag based on certain rules and increase security. The available filter options are:
- INT: Returns the first integer found in the value. For example, if the value is "abc123def456," then the return value from applying this filter would be 123 (as an integer).
- UINT: Returns an unsigned int. For example, if the value is -2, this filter will discard the minus sign, and you will get the value 2.
- FLOAT: Returns the first float found.
- BOOLEAN: A boolean value
- WORD: Filters out any characters which aren't letters or an underscore
- ALNUM: Filters out any characters which aren't letters or numbers
- CMD: Filters out any characters that aren't letters, numbers, underscore, dot or dash, and removes any leading dots from the result
- BASE64: Filters out any characters that aren't letters, numbers, forward slash, plus, or equals. base64 can be used to encode a URL as a string of text.
- STRING: Converts any HTML entities to their corresponding characters.
- HTML: Removes HTML tags, but without previously converting HTML entities.
- ARRAY: Performs no filtering, just tries to convert the parameter to an array.
- PATH: Converts the input into a string and validates it as a file path (e.g. path/to/file.png or path/to/dir), checking it first against the pattern for a linux path, and then against the pattern for a Windows path. Note: Does NOT accept absolute paths, or paths ending in a trailing slash. If it fails to match against a valid path then the empty string is returned.
- TRIM: A string trimmed from normal, non-breaking, and multibyte spaces
- USERNAME: Filters out characters not permitted in a Joomla username
{SmartTag --filter=FILTER}You can create custom filters using regular expressions if the available filters don’t meet your requirements. Prefix your regular expression with “re:” in the filter property.
For example, the following expression removes all whitespace from the output:
{SmartTag --filter=re:\s+}Smart Tags Rules
- You can use nested Smart Tags.
- You can use the same Smart Tags multiple times on the page without worrying about performance issues, as Smart Tags use caching.
Rated: 