Tokens

Tokens are a way of allowing textual references to dynamic values - for example, the current users name. This means you can make a "Hello FIRSTNAME!" without actually putting it in the code, which makes it easier to handle content which is typically edited regularly such as an email template.

Tokens are modelled on Javascript template literals. Javascript template literals are directly supported by the localisation system as well meaning both tokens and translatable text in your source are very closely related.

Hello firstname!

Let's take an example - the following string:

Hello ${session.user.firstName}!

This could be a prop on a component provided by the editor in the admin panel. In the code, if we know we have been given a string that may contain tokens, the tokens can then be swapped out like so:

// Assuming a hooks based React component. Non-hooks is further down.
import {useTokens} from 'UI/Token';

...


// Assuming "bodyText" contains the above string.
var inputText = props.bodyText;

// Swaps the ${tokens} with their underlying value.
var processedText = useTokens(inputText);

return <h1>{processedText}</h1>; // Hello You!

Note that as this is accessing the session, it works with any value you have in there. Specifically for the example above, your User type must have a FirstName field on it (which isn't available by default but is after installing Api/UserFullNames).

session.locale.name, session.user.username, session.user.id and so on - are all available textually to the person using the editor.

If you're writing a traditional React component (one without hooks):

import { TokenResolver } from 'UI/Token';

...

var inputText = 'Hello ${session.user.firstName}!'; // Assuming this is from a prop. If it was actually inline like this, use a JS template literal instead.

return <TokenResolver value={inputText}>
 {processedText => {

     return <h1>{processedText}</h1>;
 }}
</TokenResolver>;

Automatic Tokens

If you have a jsx prop in your propTypes, the editor will assume that the prop can receive a JSX structure. The editor then allows inline visual editing of the props value and that includes adding a Token into it amongst all other formatting. With the editor, add a Token and inside it type out the name of the value you want (such as session.user.username). Internally it will then be substituted when the token is rendered.