Templating

From KnowledgeTree Community

A full tutorial and guide with working with the smarty templating engine is a little out of scope for this site, but this should give you a general overview of how its used within KnowledgeTree. See "References" below for more information.

Contents 1 Hello World 2 Basic Templating Features 3 Custom functions and variables 3.1 addQS 3.2 i18n 4 References

Hello World

The easiest way to get an idea of how to make use smarty is to break a few rules. So for now, put the following into a file called test.php in the base directory of your KT install (e.g. next to view.php and browse.php). Also note that this code, in and of itself, does not give you a working page to look at, it creates a class ('hello') with a function of do_main but nowhere does the code call this function. Following these instructions will simply, and correctly, give a blank page.

<?php
require_once('config/dmsDefaults.php');
require_once(KT_LIB_DIR . '/dispatcher.inc.php');
class hello extends KTStandardDispatcher {
    function do_main() {
         $oTemplate =& $this->oValidator->validateTemplate("ktcore/test");
         return $oTemplate->render();
    }
}
?>

and then create a file called templates/ktcore/test.smarty containing

 <h2>Hello World</h2>
 <p>This is a hello world script.</p>

Easy, eh? Notice that

1. you don't have to include the ".smarty" in the name of the template - KT works that out automatically.
2. you return the value from the dispatcher - this lets it be wrapped in a normal KT page.

Basic Templating Features

Templating is incredibly useful since it lets you separate out how things look from how they work. There are a few things you need to be able to do:

1. pass information into a template
2. loop over a list of things
3. display variables
4. use "if ... else" type statements to include different items.

To give an idea of how to do all that, here's a slightly more detailed "hello world." it uses two files again, just as before. The first is a PHP file:

<?php
require_once('config/dmsDefaults.php');
require_once(KT_LIB_DIR . '/dispatcher.inc.php');
class hello extends KTStandardDispatcher {
    function do_main() {
        
         $my_string = 'i am a string.  how cool is that.';
         $my_boolean = true;

         $oTemplate =& $this->oValidator->validateTemplate("ktcore/test");
         $oTemplate->setData(array(
              'my_string' => $my_string,
              'my_bool' => $my_boolean,
              'context' => $this,
         ));
         return $oTemplate->render();
    }

    function say_hello($name) {
         return sprintf("Hello, %s.  I am a method call.", $name);
    }
}
?>

The context variable is a little trick that's enormously useful - it lets you pass in the current dispatcher, so you can call methods on it. Next, we need the template:

<h2>Hello World!</h2>

{if ($my_bool)} 
  <p>OK, that worked.  The string we were given was "{$my_string}"</p>
{else}
  <strong>AIEEE!  Not True!</strong>
{/if}

<p>Its also handy to be able to call methods on objects which are passed in.  
That's perfectly OK in SMARTY - e.g. {$context->say_hello('Bob')}.</p>

Custom functions and variables

These are defined in lib/templating/smartytemplate.inc.php so that they appear in the Smarty templates. If another templating system is used, they would need to be implemented for that other templating system.

addQS

When you need to create a URL that references the current location, but with a different query string, use an addQS block. It preserves PATH_INFO (usually in kt_path_info). See also Links within KnowledgeTree.

   <td><a href="{addQS}action=delete&fSavedSearchId={$oSearch->getId()}{/addQS}" class="ktAction ktDelete">{i18n}Delete{/i18n}</a></td>

This creates the URL for the current location, with the delete action, with the fSavedSearchId query parameter set.

i18n

Use this block function when a string that needs to be translated to other languages appears. See also Developing i18n support.

   {i18n}Delete{/i18n}

This shows "Delete" if the user uses English, but would use another language if another language pack is selected by the user.

References

1. Smarty's site, crash course (note that the usage info from above should be used ... don't use smarty directly).