Vacation Rental Management for busy people!

Tokens and Conditional Text

Using Tokens and Conditional Text means a single Template/Stationery can be created that applies to all reservations. The goal is that no editing of an email letter should be required, in normal circumstances, to sent it to a guest.

Tokens

Tokens are text in a Template or Stationery that get replaced by something else when the Template/Stationery is used. An example token would be {{GuestFirstName}} that would be replaced by a guest's first name as it is defined in the Reservation >> Guest tab. Whenever this token appears in the Template/Stationery it will be replaced by the appropriate reservation guest's first name. Tokens are NOT case-sensitive but are usually displayed with capitalization to make them easier to read.

What Tokens are there?

When on the Setup >> Templates or Setup >> Stationery pages, look to the top-right of the page under the menu bar for the column titled Tokens.

Click on any of the sections to see it open up and give a list of tokens that are available under that section. Place your mouse cursor over the list items to see a description of the token and its usage.

How do I insert a Token?

  1. Identify the Token that you wish to insert.
  2. Place your cursor in the Subject or Template text fields at the location you want the token inserted.
  3. Either click on the token in the list or type in the token (remember to use the "{{" and "}}" around it)

A Token may allow you to add a Modifier to change or control the way the information is displayed. These modifiers are added after the ":" and before the closing "}}". See the mouse-over descriptions in the tokens list for the modifiers that can be used for each Token.
Modifier Example: in one letter you may want an address displayed on a single line with commas separating each part of it, but in another letter you want it in the form used to write on an envelope. The tokens that produce addresses and lists allow you to specify the "separator" used between these items. You can write:

  • "{{GuestAddress:, }}" for the first letter (single line)
  • "{{GuestAddress:}}" for the latter (the default is to put main address components on separate lines)

Notes

Currency amounts: By default a Token that is substituted with a currency amount is formatted with a comma to separate the thousands. This is the most common use of such tokens. When comparing currency amounts the comma should be removed and can be done so my appending the "raw" Modifier, eg: {{OutstandingAmount:raw}}


Conditional Text (for advanced users)

Sometimes it is desirable to use certain text in one set of circumstances and different text in another.

For example, in quotations if there are no quotes (because of unavailability perhaps) then it may still be desirable to send an email saying that the dates are not available but take a look at our website for other dates when the inquiry is a direct one. There are different texts depending on whether there are any quotes and this can be written in a single Template. The Predefined Quote template makes extensive use of Conditional Text to produce a sensible email response.

How do I use Conditional Text?

There's a new syntax for conditional text that allows the use of the WYSIWYG text editor. The previous way still works (for now) but it is recommended that everyone uses the new way going forward.

The new way (so you can use the Rich Text editor)

I've adopted an common industry format called "Smarty" now. This means that it's more flexible and there's more documentation for it. If you have questions about how to use it you can look here.

Please note the following guidelines:

  1. There are no Smarty variables (things with a $ at the front, eg $name) - use the tokens instead
  2. When entering "Qualifiers" use the Alternate, text, operators:
    • Enter this: {if ({{token}} gt 0) and ({{token}} ne 5)}
    • Rather than this: {if ({{token}} > 0) && ({{token}} != 5)} - it will work but the editor will change '<', '>' and '&' into a different representation and it will look odd to you.
  3. Always use a Qualifier, don't assume a test for true or false:
    • Enter this: {if {{IsDeparted}} ne 0} to check for post-departure
    • Rather than this: {if {{IsDeparted}}}
  4. Don't put spaces after an opening { or before a closing }
    • Enter this: {if ({{PaymentTotal}} eq {{totalAmount}})}
    • Rather than this: { if ({{PaymentTotal}} eq {{TotalAmount}}) }
  5. If a token could produce a negative number, don't let it be the first thing after a opening "if"
    • Enter this: {if ({{RefundableAmount}} ne 0)}
    • Or this: {if 0 ne {{RefundableAmount}}}
    • Rather than this: {if {{RefundableAmount}} ne 0}
  6. If comparing strings, surround a token with quotes
    • Enter this: {if '{{ReservationStatus}}' eq 'Confirmed'}
    • Rather than this: {if {{ReservationStatus}} eq 'Confirmed'}
  7. If you have styles or anything else with a "{" or "}" embedded in your HTML
    • Wrap it in {literal} smarty tags to stop the processor getting confused:
      {literal}
      <style>
      body {background-color: #eee}
      </style>
      {/literal}
Conversion guide

If you already have customised Templates or Stationery that use conditional text then consider changing then over to the new format so that they can be edited more easily in future. Follow these guidelines to help with the conversion:

"#if" lines:

  • Replace the # and if by "{if" - no spaces between the "{" and the "if"
  • Put a "}" at the end of the line (being sure the leave a space between any token's "}}" at the end)
  • Replace the operators with their text alternative ('>' with "gt", '<' with 'lt', '>=' with 'ge', '<=' with 'le', '==' with 'eq', '!=' with 'ne' etc - according to this table).
  • Replace the boolean operations with their text alternatives ('&&' with 'and', '||' with 'or' etc)

"#else" lines:

  • Simply replace the # and else by "{else}" - no spaces inside

"#endif" lines:

  • Simply replace the # and endif by "{/if}" - no spaces inside

Other lines with "#" as the first visible character:

  • These all need to be removed. For comments, either delete them, turn them into HTML comments or surround them with "{*" and "*}"
    Replace "#: comment" with "<!-- comment -->" or "{* comment *}"

Wrap any styles with the {literal} tag


The old way (no Rich Text editor) - Discouraged, will not be supported for long

The system uses simple directives amongst the text, each directive on its own line and the first character on the line must be a '#'. When editing Templates/Stationery that contain Conditional Text ensure that each of the directives stays on its own line for it to continue to work correctly. If you use a WYSIWYG/Rich Text editor then often these will reformat the text and the Conditional Text will not work any more. For this reason it is strongly recommended that a WYSIWYG/Rich Text editor is NOT used - use an HTML or Plain Text edit instead.

Syntax and usage of the directives

Directive syntax using Perl Regular Expressions:

if: ^\s*#\s*if\s+(.*) - the () contains the condition
else: ^\s*#\s*else
endif: ^\s*#\s*endif

Examples:

#if <condition>
<Text to include if condition is true>

#endif

or for alternatives use else:

#if <condition>
<Text to include if condition is true>
#else :: this is a comment
<Text to include if condition is false>
#endif

The if/else/endif directives can be nested:

#if <condition1>
<Text to include if condition1 is true>

# if <condition2>
<Text to include if condition2 is true>
# else :: this is an end-of-line comment
<Text to include if condition2 is false>
# endif

#endif

Syntax and usage of the condition

The condition can be a combination of expressions that are associated with logical "and" or logical "or". The expressions would normally include at least one Token so that the condition may change.

Condition Syntax:

expr1 [[LOP expr2 [LOP expr3]...]

where:

exprN is an expression,
LOP is a Logical Operator - either && for Logical AND or || for Logical OR
[] are optional

Expression Syntax:

val1 [COP val2]

where:

valN is a value, a calculation or a Token the evaluates to a value,
COP is a Comparison Operator - such as ==, !==, ===, !==, <, <=, >, >=
[items] are optional

Comparison Operators:

  • No COP : will evaluate to true if val1 is non-zero
  • == : numerically equivalent to (eg TRUE: 3-2 == 1, "hello" == 0, "1.00" == 1; FALSE: 3-2 == 2)
  • === : literally equivalent to (eg TRUE: "hello" === "hello"; FALSE: "1.00" == 1)
  • != , !== : complement of the above == and ===
  • < : Less than
  • <= : Less than or equal to
  • > : Greater than
  • >= : Greater than or equal to

Condition Examples:

  1. Are there any quotes (use in the Quot template only)?
    {{Quoted}}
    This is zero is no quotes and so would evaluate to false
  2. Is there any balance outstanding (rent + refundable amount)?
    {{OutstandingAmount:raw}} > 0
    If this is zero or less it would evaluate to false, otherwise true
    "raw" is needed here to ensure that the amount does not contain any formatting charcters in the number - the default display is to include commas to separate the thousands.
  3. Is there a charge for some damages (entered into the Extra field of the Reservations->Quote tab)?
    {{ExtraAmount:raw}} > 0
    If this is zero or less it would evaluate to false, otherwise true
  4. Has the Guest left yet - is it after departure date?
    {{IsDeparted}}
    True if departed, otherwise false (up to departure date)
  5. Is there an amount that needs to be refunded after departure?
    {{IsDeparted}} && {{OutstandingAmount:raw}} < 0
    If this is zero or less it would evaluate to true, otherwise false