Custom text variables & Dictionary

Expanding on the default offering of Text Variables , it’s possible to create Custom text variables by defining key → value mappings. You can use custom text variables with or without Site Languages. In the latter case, you can create a dictionary where custom text variables can provide separate values for each configured language.

Working with custom text variables

For an overview and walkthrough of the feature see the written tutorial below.

Tutorial: Dynamic text on sites and portals (from version 3.2)

Defining custom text variables

You can defined custom text variables under the Dictionary section via Refined admin > Languages. A custom text variable key is identified as being surrounded by two $characters.

Example:$myKey$

Default value

Each variable will have a Default value. This is where the value should be entered. If used together with the Languages feature, if the users current language is not present, the variable will fallback on the Default value.

Copy from default

When adding values for languages you also have the option to copy the value from the Default Value field. Useful to easily start from the same value or even keeping it the same for this language without having to manually retype it.

Filters

From the Admin UI under Languages you can filter on custom text variables in the Dictionary section. It’s possible to filter on Empty / Translated values and text/key search. You can also further filter the result by language or tags.

Tags

For each text variable you can add Tags. This can be done when creating the text variable or added in later. Tags are meant to be a tool to help you organize or group your text variables in whatever way you see fit.

Nested variables

You cannot nest custom text variables, i.e. the following will not work properly:

-- Not supported --
$first$ = Coffee
$second$ = I like $first$

However, it is possible to use the list of pre-defined variables found here: Text Variables:

-- Works! --
$welcome$ = Welcome to $sitename, $userfirstname!

Limitation

If using the custom text variables with nested text variables in the Site builder (How to find the Site Builder) note that only the $user* text variables are supported.

Scripted text variables & Logic syntax

The custom text variables support executing small scripts. This can be useful for displaying dynamic values or adding a condition to them. You could for example have a message to say “Good morning” during the morning and “Good afternoon” during the afternoon.

Syntax

You’ll wrap your script in curly brackets: { script }. Whatever the script-part defined as the returned value is what will be used to replace the brackets section.

Examples:

$copyrightMessage$: "Copyright ACME {return (new Date()).getFullYear()}"
$greeting$: "{if ((new Date).getHours() < 12) { return "Good morning" } else { return "Good afternoon" }}"

Implementation

The variables will find whatever content is present inside the curly brackets and executes it using a Function() constructor.

Limitation

The logic syntax is not supported when adding custom text variables to the Site structure items via the Site builder.

Import / Export

It’s possible to import and export the custom text variables as .properties files.

When exporting a zip file is created containing a .properties file for each language. When importing you can import a zip with multiple languages, or you can upload single language files as well.

You can edit and create the files in whatever tool you see fit but it’s important that they are saved using the UTF-8 encoding to ensure they are read properly upon importing. When the files are exported any non-ascii characters are escaped and written as their unicode counterpart.