Custom Templates for Forms

From Achievo/ATK Wiki

Intro

You can change the appearance of a form by using a custom template. The template language is Smarty. This howto explains how to create a custom template for edit forms, and how to use it in your application.

editform.tpl

By default all forms (both the edit and the add screen) use the template 'editform.tpl', which can be found in atk/themes/default/templates.

This template uses a loop to walk through all the fields of a node, and puts them neatly in a table, one field per row.

There is a possibility to use your own, custom, template, per node, per tab or even per record. Here's how:

1) Copy the standard editform.tpl to a custom directory. This can be any directory in your application, for example 'yourapp/templates/', but it's cleaner to create a 'templates/' subdir in the module the template belongs to.

2) You can keep 'editform.tpl' as a filename, but it's better to give it a custom name so you will remember what it's for. For example, if you create a custom template for the 'department' node, name your template 'department_edit.tpl'.

3) In the node where you want to use the custom template, you have to add the following method:

  function getTemplate($action, $record="", $tab="")
  {
    if ($tab=="test")
    {
      return moduleDir("yourmodule")."templates/department_testtab.tpl";
    }
    else
    {
      return parent::getTemplate($action, $record, $tab);
    }
  }

In this example, I told the framework that for the 'test' tab of the node, it should use a custom template. In all other cases (the else-statement), the standard behaviour is applied.

By using the 'moduleDir()' method, we tell the system to use the template from the module's 'templates/' subdirectory. By using moduleDir, we ensure that the template will continu to work if someone installs the module in a different place.

4) To see if this works, it's easy to just copy the standard template, but add some extra text like 'this is a custom template' to the template. If you see it on the 'test' tab, you know that your custom template is being applied.

5) Now, what we haven't covered is how to write the actual template. Suppose we want to position the fields at a certain location. If we have a look at the standard template, we'll see:

  {foreach from=$fields item=field}
    <tr>
      {if $field.line!=""}
        <td colspan="2" valign="top">{$field.line}</td>
      {else}
        <td valign="top" class="{if $field.error!=""}error{else}fieldlabel{/if}">
          {if $field.label!=""}{$field.label}: {/if}</td>
        <td valign="top" class="field">{$field.full}</td>
      {/if}
    </tr>
  {/foreach}

The foreach is a loop that iterates over all attributes ($fields) of the node, and for each attribute ($field) it handles the rendering. If you want to create a complete template yourself, you can write a piece of HTML where you don't use a loop, but place the attributes directly into the template. The basic principle is that wherever you put for example {$name.full}, the editbox of the 'name' attribute is rendered at that position. 'full' stands for the 'full' field's html representation, including the 'required' asterix and other stuff like the tooltip.

There are, next to '.full', some other template fields that you can use:

• {$attributename.label} - The label of the field (usually this is positioned to the left of the field).
• {$attributename.error} - If during add/update an error is encountered, the error message for the attribute is in this variable.
• {$attributename.widget} - Just the input field, with the 'required' indication.
• {$attributename.obligatory} - Empty if the field is not required, or the html code for the asterix if required.
• {$attributename.tooltip} - If a tooltip is available, this template variable contains the htmlcode for the tooltip icon.

You can experiment by copying the standard template and placing some attributes in it. This of course have to be attributes that are present on the screen that you are creating a template for.

Caution!

Watch out; if you created a custom template where the fields are positioned directly, instead of using a loop, you will have to adjust the template whenever you add a new attribute (unless ofcourse that new attribute is hidden, in which case it's automatically placed in the hidden attributes section of the form).