====== Back Office Display Using Templates ======

This page expects knowledge of the basic [[back office display engine]]. Also note page [[Back Office Display Decoration]], which describes the widgets not in, but around main content.

Following [[Back office menu entries]], one can add back office menu items (Tabs) and launch their controller. This page elaborates on how to add actual content to such a controller class, using Smarty templates.

===== Alternatives =====

Using Smarty templates is the most flexible of the recommended display technologies for back office. **Use them only when in need of this flexibility.** For lists or editing interfaces of plain database stored objects, look into

  * [[Using Helper for ObjectModel lists]]
  * [[Using Helper for ObjectModel editing interfaces]]
  * [[Using Helper for Options]]

All of these bring, unlike custom templates, GUI standards compliance for free.

===== Location of the Template =====

Templates get looked up in 5 default places. First two of them only in back office controllers coming in a module (using //ModuleAdminControllerCore// as parent:

  * ''themes/<theme name>/modules/<module name>/views/templates/admin/content.tpl''
  * ''modules/<module name>/views/templates/admin/<controller name>/content.tpl''

Then two places which get looked up for regular controllers:
  * ''override/controllers/admin/templates/<controller name>/content.tpl''
  * ''admin-dev/themes/default/template/controllers/<controller name>/content.tpl''

Last place is a fallback for templates not found, used for displaying the error message. One shouldn't change or use this.

== <controller name> ==
While the other names get picked unchanged, this one gets "translated" as following:

  * Assumption is, the controller's class is //AdminGitUpdaterController//.
  * Cutting off the //Controller// at the tail, this gives a controller name //AdminGitUpdater// (stored in ''$this->controller_name'').
  * For finding the template, the first five characters get cut off as well, making it //GitUpdater//.
  * To confuse developers even a bit more, that result gets converted to all lowercase with underscores, making it //git_updater//.
  * Resulting path: ''views/templates/admin/git_updater/content.tpl'' inside the module folder.

All the paths above are hardcoded in ''createTemplate()''. If one really needs to change the name of the template (//content.tpl// above), one can change this by setting ''$this->template'' in the controller.


===== The Custom Template =====

After placing a file in the place described above, the remaining part is straightforward. Best of this: one can combine it with the Helper engine.

A simple template looks like this:
<code html>
<div class="row">
    <div class="col-lg-12">
        {if isset($content)}
            {$content}
        {/if}
    </div>
</div>
</code>
Actually, that's pretty much the default template in ''admin-dev/themes/default/template/content.tpl''. Variable ''$content'' is all the content generated by the Helper engine, so these two strategies are easy to combine.

Everything else, before and after Helper engine content, or the entire content when ignoring the engine, is entirely up to the developer.