The syntax draws inspiration from Markdown, a little from the PHP programming language as well as a few ideas from the template system in my pre-Ubuntu favourite music player foobar2000. I’ve tried to keep it as easy to read as possible, but in quite a few places I have chosen to put power and flexibility first.
The basics are very similar to other languages, put a single ‘*’ on either side of text to make it bold, or a double ‘’ for italic. There is also support for basic footnotes, with any number of starts inside a square brackets ‘[*]‘ or ‘[]‘. This will display the stars in red in order to attract attention.
Headings are also according to the normal standard. Place a ‘=’ sign on either side for a first level heading, and put two for a sub-heading. You can place up to six equal signs for the smallest heading.
Heres an initial example with all of these:
*Hi there*, how **are** you? => Hi there, how are you? == Login Details == *Username:*[*] josh [*] This is the username you chose at signup => Login Details => Username:* josh => * This is the username you chose at signup.
In the example above we hard-coded the name ‘josh’ into the template where the username was meant to go. While this produced the results as expected, its not really useful to have a template with fixed values.
Inserting variables into the template is used by placing a dollar ‘$’ sign before the variable name. In the example above instead of writing “josh”, we could have written “$username” for the same effect.
Some variables hold values that we might want to be formatted according to a set of rules. For instance if we had $date with today’s date in it, putting it in the template would write “2011-01-14 14:03:35″. While sometimes that’s what we want, sometimes you would want to write it as “January 14th”, and sometimes as “14 Jan, 2:03pm”. In order to allow for all of these options we have a formatting option for variables.
In order to format a variable, simply put parenthesis straight after the variable without any spaces. Each variable is formatted differently, according to its type. A date variable is formatted according to the PHP date function so “$date(F jS)” would write out “January 14th”. Most other variables are formatted according to printf formatting.
Some variables can even be formatted according to other variables. This is the case you would generally use with formatting according to currency. If you have the client credit of 14.65 in $credit you would simply call “$credit($client→currency)” which would then print out R14.65 if your client is using South African Rands :) .
Lastly, if you notice in the paragraph above I used the variable “$client→currency“. This is present in most of the templates, in which it gets the $currency variable for the current $client following PHP style.
Hi $firstname $surname, Your account was created at *$client->created(ga)*. You currently have $client->credit($client->currency) credit. => Hi John Smith, => => Your account was created at 5pm. => You currently have $13.65 credit.
Unfortunately just as everything doesn’t always go as planned, not all variables are always available for your use. While us allowing you to create clients without filling in their surname is useful, it would create a problem in the template listed above.
The first line would read “Hi John ,” – notice the space before the comma. While this isn’t really a train-smash, there are a couple places where the functionality is quite important. To deal with these instances we introduce curly brackets (a.k.a. stache’s).
Any content inside curly brackets will not be displayed if any of the variables were not available. In the example above if we had written “Hi $firstname{ $surname},” as the first line – it would have displayed neat text whether or not the surname was available. In this simple example if $surname is not set, the space before it is hidden.
There is also the case where you would like to display something instead of the missing variables. For example in one particular email we might like to say “You can login with the username $username at our site.”, but if the client does not have a username yet we would rather say “You can signup for a username at our site.”.
This nifty trick is performed by simply typing |or| inside the curly brackets. If the system picks this up it will display whichever one matches. Performing the operation in the paragraph above becomes simple as demonstrated.
You can {login with username '$username'|or|signup} at our site. => You can login with username 'josh' at our site. (and sometimes) => You can signup at our site.
There are a few more features that have not been covered yet. The first important one is including links in your template. This is achieved by wrapping an address in double square brackets such as “http://www.google.com”. We also allow link captions that are different from the address, by including a vertical bar: “Google Website”
Variables can also be formatted according to a bunch of specific rules. In order to pass the variable to be formatted the code looks like $username(>upper) which will pass the username to the ‘upper’ function (will look something like “JOSH”). The complete list of current functions available is: upper (upper-case), lower (lower-case), u2s (underscores to spaces), ucwords (upper-case first letter of each word), ucfirst (upper-case only first letter), and empty (coverts to nothing – which is sometimes useful when combined with the missing variable syntax).
The ternary operator is also available as a formatting function. We use the C syntax with <test> ? <if true> : <if false>. If the <if true> section is not specified it defaults to being the same as the <test>. This is all most easily demonstrated with sample code.
Please visit [[http://www.google.com]], or [[http://www.yahoo.com|yahoo]] => Please visit http://www.google.com or yahoo HOW IS $username(>upper) TODAY? => HOW IS JOSH TODAY? $category(>ucfirst) was chosen as the category. => Books was chosen as the category. Did $staff(?:the staff member) mention the issue to you? => Did Josh mention the issue to you? (and sometimes) => Did the staff member mention the issue to you?
Heres a piece of sample template used for the user welcome email mentioned right at the start.
= Hi $user->name, = Welcome to Lusion Technologies, Firstly thank you for choosing Lusion Technologies. We strive to ensure you are completely satisfied with the services you will be receiving from us. == General Account Information == *Username:* $username *Password:*{ $password|or|[*] **not stored** [*] We do not store your passwords for security reasons. If you do not remember it, you can reset it through our client system at [[http://lusion.snapbill.com/lost_password]].} == Accessing Billing Manager == To access your billing manager you can go directly to: [[https://lusion.snapbill.com/login]] If you require any additional information or we can be of any further assistance please do not hesitate to contact us. Kind Regards, Lusion Technologies [[http://www.lusion.co.za]]