Dictionary: custom text variables

Owned by Johannes Laatu (Deactivated)
Last updated: May 10, 2023 by Madzy Soetman
3 min read

It’s possible to create Custom text variables, which you can use with or without the language switcher. 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: Dynamic text on sites and portalsarchived

  1. Go to the Refined Administration > the Languages tab.

  2. Go to the under the Dictionary section.

  3. Add text variabbles or import/export a dictionary.

Define text variable keys by surrounding text with two $ characters, for example: $myKey$.

Define custom text variables

Default value

Each variable has 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: dynamic content:

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

Limitation

If using the custom text variables with nested text variables in the Site builder (https://refined.atlassian.net/wiki/pages/createpage.action?spaceKey=JDC&title=How%20to%20find%20the%20Site%20Builder) 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.

When importing a dictionary all current keys will be merged with new ones. Duplicates will be overwritten by the imported file.

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.