Developer Area/Smarty&Dwoo

Mahara uses the Dwoo templating engine to display all page content. Dwoo is a fork of the more well-known Smarty template system (and Mahara previously used Smarty) so some of the code and documentation refers to Smarty as well.

Basically the way it works is that every time you want to print HTML to the screen, you instead load up a Dwoo *.tpl template file, pass some variables to it, and then Dwoo renders it into final HTML.

The advantages of this approach are that it separates the front-end of Mahara from the back-end, it centralizes all front-end code in one place (in the template files), and it allows custom themes to override the template.

The basic use-case

Here's how it gets used in a normal use-case. See also BasicPHPFileTemplates

The PHP file

The PHP file should have a call to the smarty() method. This will return a Dwoo object, but by tradition we tend to store this in a variable called $smarty. You can then call the $smarty->assign() method to load variables that can be accessed in the template. Lastly, you call $smarty->display($templatename) to render and print the template.

<?php
// ... page init stuff goes here

$smarty = smarty();

// Set some variables that can be accessed in the template.
$smarty->assign('firstname', $firstname);
$smarty->assign('lastname', $lastname);
$smarty->assign('sharelastname', (boolean) $sharelastname);

// Render the template and print the results.
$smarty->display('user/sayhello.tpl');

Fetching without printing

If you just want to fetch the HTML but not print it to the screen yet, use $smarty->fetch();. This can be useful for embedding snippets of code into another page.

<?php

$snippetsmarty = smarty();
$snippet = $snippetsmarty->fetch('path/to/snippet.tpl');

$pagesmarty = smarty();
$pagesmarty->assign('snippet', $snippet);
$pagesmarty->print('path/to/page.tpl');

The template file

The trickiest part about the template file is its location. Each template file (except for plugin template files) should have a copy under htdocs/theme/raw/templates.

In our example, we passed in "user/sayhello.tpl" in the PHP file, so the full path to the template file will be "htdocs/theme/raw/templates/user/sayhello.tpl".

{include file="header.tpl"}

<!-- Adding "|safe" tells it not to escape html characters from the variable. Don't do this unless you've pre-scrubbed the variable in PHP, and it contains HTML that should be rendered as HTML. -->
Your first name is {$firstname|safe}.

{if $lastname}Your last name is {$lastname}.{/if}

{include file="footer.tpl"}

Custom themes

Mahara themes are hierarchical. Each theme has a parent theme, and each parent can have a parent and so on, with the special "raw" theme being the root of the hierarchy. That's why the basic version of each template should live under the "htdocs/theme/raw/templates" directory.

If a theme developer wants to change the content of a template for one of their themes, they can simply place an altered copy under "htdocs/theme/{themename}/templates".

Plugin templates

Plugin templates are slightly different. They live under the plugin's directory. So for instance, the Creative Commons blocktype has a template file called "statement.tpl".

• These should be stored under a "theme" directory under the plugin, e.g. blocktype/creativecommons/theme/raw/statement.tpl
• They are referenced in the smarty() method with a string that has the plugin type, a colon, the plugin name, another colon, and then the relative path to the template. e.g.: smarty('blocktype:creativecommons:statement.tpl');
• For plugins that live under another plugin (i.e. blocks that live under artefacts)...
  • The files go under the subplugin's directory: artefact/file/blocktype/folder/theme/raw/page.tpl
  • But it's referenced from smarty listing only the subplugin: smarty('blocktype:folder:page.tpl')

TODO

• Commonly used tags
• How to embed PHP
• Custom tags
  • Which ones we have
  • Where their code lives
  • How to write one
  • Maharas' standard-defined smarty variables