Both Chronoforms v6 and ChronoConnectivity v6 have a new powerful feature, its the variable shortcodes, for example, you can now capture request data and pass it to any element in your form, including the form fields interface or the email or any database action, there are so many shortcodes supported and knowing them can simplify many tasks which required writing php code in previous versions.
in this article, some of the supported shortcodes are demonstrated, sometimes with example usage.
Healeyhatman has a list of shortcodes here with examples and explanation that you can add to your site as a ChronoForm to have the info close to hand.
Request data
Use {data:field_name} or {data:url_parameter_name} anywhere you want to use the value of a request parameter, for example you can include a field value in an email, a message to the user or in a PDF file, you can also use shortcodes in field settings, like a field label or value.
Using {data:} only will return the full request data array, this may be used, for example, when saving the form data to the database, the "Save data" action requires a dataset to use it as the storage data source.
Please note that the shortcodes allow you to access array data, so using {data:array.field} will get the value of the "field" key under the "array" key data in the request data.
Some shortcodes have some methods to apply to the data before returning the result here are some examples:
- Empty: return true or false, based on the variable value: {data.empty:param}
- Count: return the count of an array, example: {data.count:checkboxes}
- Print: print a variable in a readable format, example: {data.pr:}
- Break: Convert new line characters to line breaks, useful for getting a formatted output of textareas. {data.br:textarea}
- Json encode: Encode the value in json format: {data.jsonen:checkboxes}
- Json decode: Decode a json encoded value: {data.jsonde:stored_value}
- Join: Join an array of values into a single string: {data.join:values} or {data.join[,]:values}
- Split: Split a joined string into an array of values: {data.split:string}
- Clear: clear the variable value and set it to null: {data.clear:not_needed}
You can also set a default value to be used in case the called variable value is null or undefined: {data:non_existent/1}, this call will return 1 if the variable is not defined or not available in the request data.
You can nest shortcode calls in each other. So if you want to set a data field to the value of a variable call, for example. {data.set:field_name$(var:action_name)}
You can not use the shortcode directly in a PHP action, use these functions instead.
To read a value from the form data:
$this->data("field_name", "default value");
Or to add a new value into the form data
$this->data("field_name", "value", true);
Functions/Actions data
Almost every processed function (action) returns a result variable, the variable type is different, some will return a boolean true or false, others will return an array of values, this variable can be accessed using this syntax: {var:function_name}
The function_name is visible inside a black label inside the function/action body and inside the "Name" setting box (in Connectivity).
So for example, the "Read Data" function returned result(s) are available under this variable: {var:read_data1}, assuming the function name is read_data1
The variable value is available ONLY AFTER the function has been processed.
In PHP you can use the following code to set and get variables:
$this->set("var_name", "value"); and $this->get("var_name", "default");
Session data
Get a session variable using {session:variable_name} and set it using {session.set:var_name$value}
if you need to get or set the session variables in PHP then you can use the following functions:
\GApp::session()->get("var_name", "default_value");
\GApp::session()->set("var_name", "new_value");
URLs and Paths
- {url:_self} to get the current page url
- {url:event_name} to get a partial form event url, e.g. {url:submit}will give /index.php?option=com_chronoforms6&cont=manager&chronoform=form_name&event=submit
- {url/full:event_name} to get a full form event url, e.g. {url/full:submit} will give https://my_domain.com/index.php?option=com_chronoforms6&cont=manager&chronoform=form_name&event=submit
- You can add parameters to the url query strings like this {url:submit$param=value}
- {path:root} to get the server root path e.g. /home/my_domain/my_domain.com
- {path/url:} will get the URL of the chronoforms folder e.g. https://my_domain.com/components/com_chronoforms6/chronoforms
- {path:} to get the path to the chronoforms folder e.g. /home/my_domain/my_domain.com/components/com_chronoforms6/chronoforms
NB the path strings will include the /administrator/ folder if viewed from the back-end of the site.
Redirect
Redirect to any url: {redirect:url_here}, or to a form event: {redirect:event_name}
Use variables inside the redirect shortcode: {redirect:http://domain/form$param=(data:some_var)}
User data
Get the current user data using the {user:} shortcode e.g. {user:id}, {user:username} or {user:email}
Date and Time
Get the current UTC date in Y-m-d H:i:s format: {date:},
Pass a desired date/time format using the PHP format strings: {date:H:i}
Pass a date value to be formatted: {date:Y-m-d$(var:some_date_value_or_timestamp)}
Set the timezone to the one used by your site {date/site:}
Set a timezone {date/region/time_zone:format_string}
From CFv6.0.21 you can use this provided that the Region and Timezone are recognised by PHP - see the PHP docs here. If your entries are not valid you will get an Error :-(
Set a future date/time {date:format_string $+ xx days yy hours}
These can be combined as in this example from user healyhatman {date/AEST:h:i:s a d-m-Y e$+ 10 days 3 hours} which returns a date string like this: 02:04:36 pm 23-04-2018 Australia/Sydney
NB CFv7 uses . instead of / for these shortcodes so use e.g. {date.site:}
Page information
Get information about the current page: {page:url} or {page:title}
Locales
Get a locales string value: {l:string} or {lang:string}
Messages
{error:[message]} or {success:[message]} or {info:[message]} or {warning:[message]} will each display a Joomla! system message of the specified type e.g. 'error'
Other useful shortcodes:
- {rand:} to get a random number.
- {uuid:} to get a UUID string.
- {ip:} to get the current user's IP address.
