#1190 - The power of tempcode

The Power of Tempcode

Tempcode is the base template language of Composr, and its very powerful and also serves as a complete programming language with support for control structures, built-in core functions and variable substitutions.
Tempcode provides four constructs other than the plain text of the template itself:

Parameters: {PARAMETER} where PARAMETER is a code-name of something that was actually passed to the template
Language strings: {!STRING,<parameters>...} where STRING is a real language string from a loaded language file (e.g. Banner code could use strings from banners.ini, but most other code could not; global.ini contains strings usable anywhere)
Symbols: {$SYMBOL,<parameters>...} where SYMBOL is a real symbol Composr supports. Embedding a symbol is like making a function call or running a command in the complex place, or a substitution in the simple case
Directives: {+START,DIRECTIVE,<parameters>...}...{+END,DIRECTIVE} where DIRECTIVE is a real directive Composr supports. Directives essentially wrap portions of the template, controlling that portion; they are generally used for types of condition checking (e.g. IF) or loop. There are also directives like {+IMPLODE,<parameters>...} that do not wrap, but work outside the normal "string manipulation" bounds that symbols do

Examples below should help you understand how to use Tempcode practically,

The [semihtml] tag is a special tag that allows Comcode and HTML to be naturally mixed together,

eg:
[semihtml]
{+START,IF,{$LT,{$RAND},8000}}
    

This shows 1/4 of the time. How does it work? RAND picks a random number between 0 and 32000, so the number will be less than 8000 1/4 of the time.

{+END}

The next example demonstrates how built-in language constructs like SET_RAND can be used to randomly make a selection from given options,

<p style="color: {$SET_RAND,red,green,blue,#EE1167};">
    I think you are a {$SET_RAND,lovely,beautiful,groovy} person.

    We randomly selected a word, and randomly picked a text colour.

This would resolve to something like this,

eg:
<p style="color: green">
    I think you are a groovy person.

    We randomly selected a word, and randomly picked a text colour.

Tempcode is also equipped with security aspects such as obfuscating a mail, get an obfuscated "mailto: " string which makes it hard for e-mail scavengers to read it and hence preventing spam,

eg:

    I want to let people {$OBFUSCATE,mailto:[email protected]}, but I don't want spam so I will confuse spam-bots.

TRUNCATE_LEFT can be used to trim data from the left, you can use TRUNCATE_RIGHT to do the same from right, and TRUNCATE_SPREAD to keep an equal left/right portion, all the three functions have the same parameter order, parameter order is as follows,
{$TRUNCATE_LEFT, data, truncation length, optional binary value to show a tool tip, optional binary value for whether the input text is already in HTML format}

eg:

    {$TRUNCATE_LEFT,Sometimes you get data that is too long for your layout.,10,1,1}

The menu system can use match-keys for matching against the URL the menu is being viewed from, and we can use that show a specific message only if a condition is satisfied,

eg:
{+START,IF,{$MATCH_KEY_MATCH,site:downloads:browse:3}}
    

        Maybe I want to add this message to DOWNLOAD_CATEGORY_SCREEN.tpl but to only display if viewing download category 3.

        (the page-link means "'site' zone, 'downloads' page, 'browse' screen type, '3' ID)")
    

{+END}

This is an alternative way of achieving the same result as above, we perform a string equality here(EQ) on the ID parameter, if it is equal then the message will be displayed.

{+START,IF,{$EQ,{$_GET,id},3}}
    

        Or we could do it this way, given DOWNLOAD_CATEGORY_SCREEN.tpl is always under site:downloads:browse anyway, and the 'id' parameter is the only thing altering.
    

{+END}


It's useful to know which browser is being used by the user to view the web page. We might have to make some tweaks specifically for browsers like Internet Explorer to ensure cross-browser compatibility,

eg:
{+START,IF,{$BROWSER_MATCHES,ie}}
    

        You're an Internet Explorer user.
    

{+END}


This functionality can be used to display messages or alerts specifically for admins,

eg:
{+START,IF,{$IS_ADMIN}}
    

        Only admin's see this.
    

{+END}

This functionality is similar to IS_ADMIN it checks if the member belongs to 1, 3,4 or 5 if yes , then the message will be displayed,

eg:
{+START,IF,{$IS_IN_GROUP,1,3-5}}
    

        Only members in groups 1/3/4/5 see this.
    

{+END}

Dynamically change the image resolution of your avatar to make it a thumbnail using the THUMBNAIL language construct, current avatar can be fetched using AVATAR and the second parameter defines the resolution,

eg:
<img alt="Your avatar made into a really tiny thumbnail" title="Your avatar made into a really tiny thumbnail" src="{$THUMBNAIL*,{$AVATAR},20x20}" />
[/semihtml]

This will work within Tempcode only (i.e. a template), we can use loops within tempcode using the LOOP language construct, and the loop variable can be fetched within the loop using the _loop_var variable,
In this example, it loops from A to I and in the loop it uses the language construct CYCLE to go through the parameters passed to it in a sequence, so the first in loop the background property will be set to the first value i.e #EEE and _loop_var will display the current loop value which should be A,

eg:
<div>
    Zebra-striping by setting up a named cycle (we use the loop to simulate an arbitrary repeating situation to use the cycle within):
    {+START,LOOP,A\,B\,C\,D\,E\,F\,G\,H\,I}
        <div style="background: {$CYCLE,bgcol,#EEE,#AAA}">
            {_loop_var}
        </div>
    {+END}
</div>

The Power of Tempcode

Tempcode is the base template language of Composr, Tempcode allows you to control the flow or layout of your website, and it also serves as a complete programming language with support for control structures, built-in core functions and variable substitutions.

Tempcode is commonly used to customize a block, a block can be anything like group of links/tags, poll, gallery, a web service etc we define a template for each block and then edit the corresponding template file to customize the block as we like,

Tempcode provides four constructs other than the plain text of the template itself:

Parameters: {PARAMETER} where PARAMETER is a code-name of something that was actually passed to the template
Language strings: {!STRING,<parameters>...} where STRING is a real language string from a loaded language file (e.g. Banner code could use strings from banners.ini, but most other code could not; global.ini contains strings usable anywhere)
Symbols: {$SYMBOL,<parameters>...} where SYMBOL is a real symbol Composr supports. Embedding a symbol is like making a function call or running a command in the complex place, or a substitution in the simple case
Directives: {+START,DIRECTIVE,<parameters>...}...{+END,DIRECTIVE} where DIRECTIVE is a real directive Composr supports. Directives essentially wrap portions of the template, controlling that portion; they are generally used for types of condition checking (e.g. IF) or loop. There are also directives like {+IMPLODE,<parameters>...} that do not wrap, but work outside the normal "string manipulation" bounds that symbols do

We will look at some examples below which demonstrates various aspects of tempcode, but before that lets see how to add a template file for a sample block in 3 steps which we can then edit and test different examples,

1. Adding a new Block -
Lets start by adding a new sample block to our front page so that we can test different examples of tempcode, go to the 'sources_custom' directory, there you will find a sub folder 'blocks', within 'blocks' create and add a new block file 'main_first_block.php'.
Now lets add something to our block file, edit 'main_first_block.php' using your favorite text editor and add the following,

class Block_main_first_block
{

function run()
{
return do_template('BLOCK_MAIN_FIRST_BLOCK',array());
}
}

In this code we are simply creating a new class for our block and then defining the standard run() method which is executed when the block is invoked which in turn calls this class and executes run(),
As you might have noticed we are calling a template file 'BLOCK_MAIN_FIRST_BLOCK' in the run() method using the do_template() function, this tells the system to use this template file for our block and that is our next step, creating a template file for the block.

2. Creating a Template file -
Go to 'themes' folder where you will find a folder 'default', go to 'default', and there you should find two templates folder 'templates' and 'templates_custom' , the main 'templates' folder has all the pre-defined templates which the system is using already so we don't have to make any changes there, the 'templates_custom' folder will have all the user defined templates or the customized templates, our template file will go here,
Create a new blank file 'BLOCK_MAIN_FIRST_BLOCK.tpl' and save it in to 'templates_custom' , .tpl is the default extension we give to template files,

3. Adding the block to front page -
Now that we have the block and template file ready, lets add the block to our front page so that we can test the examples. To add a block to the front page we will have to make the changes in the comcode file 'start.txt' which contains all the blocks which show up on the front page,
'start.txt' file is located in 'pages' -> 'comcode_custom' -> 'EN' , the same rule as templates applies here as well, the customized comcode files should go in to comcode_custom folder.
Edit 'start.txt' file using your text editor, and add this in the last line,

[box="first block"][block]main_first_block[/block][/box]

This line adds the block to our front page, the box defines the outer section of the block and string parameter passed to it(“first block”) will be placed in the title bar of our div box.
Next comes the block tag which defines a new block and within the block tags we have provided the name of our new block main_first_block

If you go to your front page now you should see that a new block has been added with the title 'first block' on the top(as seen in the image: poweroftemp1.png), it's empty right now as we are yet to add any content to the template file,

Now that we have a block set up on the front page, we can test the tempcode examples here by simply adding the code to template file(BLOCK_MAIN_FIRST_BLOCK.tpl)

Lets start with some examples to test here,

Go ahead and paste the following example codes in to our template file BLOCK_MAIN_FIRST_BLOCK.tpl and reload the front page to see the results,

This example demonstrates how built-in language constructs like SET_RAND can be used to randomly make a selection from given options, paste this code in to the template file and reload the front page to see the results(as seen in the image: poweroftemp2.png)

<p style="color: {$SET_RAND,red,green,blue,#EE1167};">
    I think you are a {$SET_RAND,lovely,beautiful,groovy} person.

    We randomly selected a word, and randomly picked a text colour.

This would resolve to something like this,

eg:
<p style="color: green">
    I think you are a groovy person.

    We randomly selected a word, and randomly picked a text colour.

In this example we use the construct RAND which picks a random number between 0 and 32000 and the number is then passed to a IF conditional which checks if the number is less than 8000 using the LT construct, go ahead and try this in the template file to see the results

eg:
{+START,IF,{$LT,{$RAND},8000}}
    

This shows 1/4 of the time. How does it work? RAND picks a random number between 0 and 32000, so the number will be less than 8000 1/4 of the time.

{+END}

image:poweroftemp6.png

Tempcode is also equipped with security aspects such as obfuscating a mail, get an obfuscated "mailto: " string which makes it hard for e-mail scavengers to read it and hence preventing spam,

eg:

    I want to let people {$OBFUSCATE,mailto:[email protected]}, but I don't want spam so I will confuse spam-bots.

TRUNCATE_LEFT can be used to trim data from the left, you can use TRUNCATE_RIGHT to do the same from right, and TRUNCATE_SPREAD to keep an equal left/right portion, all the three functions have the same parameter order, parameter order is as follows,
{$TRUNCATE_LEFT, data, truncation length, optional binary value to show a tool tip, optional binary value for whether the input text is already in HTML format}

eg:

    {$TRUNCATE_LEFT,Sometimes you get data that is too long for your layout.,10,1,1}

The menu system can use match-keys for matching against the URL the menu is being viewed from, and we can use that to show a specific message only if a condition is satisfied, you can test the code below in the block,

eg:
{+START,IF,{$MATCH_KEY_MATCH,site:start}}

I want this displayed only for the start page

(the page-link means "'site' zone, 'start' page)

{+END}

image:poweroftemp7.png

you can test the following example in a downloads template file DOWNLOAD_CATEGORY_SCREEN.tpl which performs some additional checks,

{+START,IF,{$MATCH_KEY_MATCH,site:downloads:browse:3}}
    

        Maybe I want to add this message to DOWNLOAD_CATEGORY_SCREEN.tpl but to only display if viewing download category 3.

        (the page-link means "'site' zone, 'downloads' page, 'browse' screen type, '3' ID)
    

{+END}

This is an alternative way of achieving the same result as above, we perform a string equality here(EQ) on the ID parameter, if it is equal then the message will be displayed.

{+START,IF,{$EQ,{$_GET,id},3}}
    

        Or we could do it this way, given DOWNLOAD_CATEGORY_SCREEN.tpl is always under site:downloads:browse anyway, and the 'id' parameter is the only thing altering.
    

{+END}


It's useful to know which browser is being used by the user to view the web page. We might have to make some tweaks specifically for browsers like Internet Explorer to ensure cross-browser compatibility,

eg:
{+START,IF,{$BROWSER_MATCHES,ie}}
    

        You're an Internet Explorer user.
    

{+END}


This functionality can be used to display messages or alerts specifically for admins,

eg:
{+START,IF,{$IS_ADMIN}}
    

        Only admin's see this.
    

{+END}

image:poweroftemp3.png

This functionality is similar to IS_ADMIN it checks if the member belongs to 1, 3,4 or 5 if yes , then the message will be displayed,

eg:
{+START,IF,{$IS_IN_GROUP,1,3-5}}
    

        Only members in groups 1/3/4/5 see this.
    

{+END}

image:poweroftemp4.png

Dynamically change the image resolution of your avatar to make it a thumbnail using the THUMBNAIL language construct, current avatar can be fetched using AVATAR and the second parameter defines the resolution,

eg:
<img alt="Your avatar made into a really tiny thumbnail" title="Your avatar made into a really tiny thumbnail" src="{$THUMBNAIL*,{$AVATAR},20x20}" />


This will work within Tempcode only (i.e. a template), we can use loops within tempcode using the LOOP language construct, and the loop variable can be fetched within the loop using the _loop_var variable,
In this example, it loops from A to I and in the loop it uses the language construct CYCLE to go through the parameters passed to it in a sequence, so the first in loop the background property will be set to the first value i.e #EEE and _loop_var will display the current loop value which should be A,

eg:
<div>
    Zebra-striping by setting up a named cycle (we use the loop to simulate an arbitrary repeating situation to use the cycle within):
    {+START,LOOP,A\,B\,C\,D\,E\,F\,G\,H\,I}
        <div style="background: {$CYCLE,bgcol,#EEE,#AAA}">
            {_loop_var}
        </div>
    {+END}
</div>

image:poweroftemp5.png

(Click to enlarge)

(Click to enlarge)

(Click to enlarge)

(Click to enlarge)

(Click to enlarge)

(Click to enlarge)

(Click to enlarge)