Contemplate™ Web Templating System  


Latest release

Contemplate 2.0.2
16 Nov 2011
download now!

Tips and tricks

Using server-side code

If you include PHP code in your templates or content files, it will execute after the page is assembled but before the page is sent to the browser. For example, if you include the code <?php $name="Joe"; ?> at the top of your template and the code <?php print $name; ?> in your embedded content, your assembled page will include the text "Joe." Scripts written in other languages may or may not execute, depending on the capabilities and configuration of your web server.

Merging variable values into your content

If you commonly display the values of PHP variables in your content, you can make your content easier to edit by placing variables like $name instead of <?php print $name; ?> and then converting those variables to their values before displaying the content.

As of version 2.0, Contemplate includes a function called merge_values($content, $values) that you can use in your scripts, in conjunction with the variable embed attribute. This function finds any PHP variables in $content, and sets them to the corresponding values in $values, which is an associative array. For example, if you put the tag <!--#embed main variable --> into your template, and the content displayed there contains the $current_rank variable, you can calculate a value for $current_rank in your script and then call $main = merge_values($main, array("current_rank"=>$current_rank)) to merge the value into your content. This gives the same result as including <?=$current_rank?> into your content, but the content will be easier to edit by non-programmers.

If you have several values to merge into your content, you can simplify the syntax of the merge_values command by first compacting them into one array:

$values = compact("value_1", "value_2", "value_3");
$main = merge_values($main, $values);

Alternatively, you can simply pass all current values into the merge_values command:

$main = merge_values($main, $GLOBALS);

Splitting your content to hide it or loop over it

As of version 2.0, Contemplate also supports a new kind of tag that you can place into your content. A "split" tag extracts a portion of your content, puts it into a variable that your code can access and manipulate, and replaces the content with a reference to the variable. For example, if your embedded content contains the tags <!--#split warning_message --> and <!--#end split -->, then Contemplate will set a variable $split_warning_message containing the content between the split tags. Your script can then alter that variable, or set it to an empty string, to change or hide that content. When you are finished manipulating the $split_warning_message content, you can merge it back into your main content with $main = merge_values($main, array("split_warning_message"=>$split_warning_message)).

A combination of the merge_values function and the split tags makes it easy to loop through a repeatable piece of content and merge data into it. For example, if you access a table row in your content via a $split_users variable, you can then iterate over a $users array, merging the $users data into each iteration of the row:

$user_data_display = array();
foreach ($user_data as $user) {
   $user_data_display[] = merge_values($split_users, $user);
$split_users = implode("\n", $user_data_display);
$main = merge_values($main, array("split_users"=>$split_users));

Remember that after manipulating any content that you capture with the variable attribute, you are responsible for displaying it with the echo or print functions.

Accessing content without a template

If you want to quickly display a piece of content in your content files without merging it into a template, or if you want to access individual pieces of content for display by a dynamic Flash file or other system, you can pass an args value to the Assembler script:


You can construct this args value just as you would construct a hard-coded embed tag in a template.

Managing page definitions

For web developers, editing the pages.txt file directly is usually the fastest way to add or reconfigure your pages. But for some users this can be inconvenient. As an alternative, you can install the Meditate(tm) Web Content Editor, and then use its page management feature to edit, copy, rename and delete your page definitions from a web interface.


Contemplate is developed by Arlo Leach.