Page Template Requirements

Author: Glenn Henshaw (thraxisp)

Mantis pages are currently hard coded as php files with embedded HTML and a smattering of CSS. In many cases, the page itself determines the presentation based on the current user's access level and system parameters. There are also several pages that are graphically close to each other or related. This construction makes it difficult to modify the overall look and feel of a site, or to add or delete fields.

The construction of the code will be reviewed to separate the business logic (feature interactions and user capabilities), and presentation.

The general implementation will have the following attributes:

• use a generally accepted Template engine - Smarty seems to be a logical choice because of it's widespread adoption and simple implementation. Other engines are probably also viable.
• have different selectable views for the same site - different themes should be available. When a specific template is missing, the display should fall back to a default template. Users should be able to select a template for their viewing. Administrators should also be able to restrict the templates that are available to users. It should also be possible to select different default templates for each project.
• Within a theme, it should be trivial to remove a field from the display. In this case, the display should leave a hole / space where the original field was.
• an individual user should be able to select their theme for the site, or an specific project
• the existing multi-lingual interface is required. Retaining the existing language files is desired.

The implementation consists primarily of removing display statements from the existing code. This work is significant as much of the code embeds the display function at lower levels.

Development of this feature will be done on a branch from the 1.1 stream. This will allow normal development to proceed while the core is reworked. The code will eventually be folded back into the main stream. The branch is labelled 'EXP_TEMPLATE'.

• none should be required

• templates will be created to split up the functionality on the pages to reasonable size parts. In general, common sections will be placed into separate files. For example, the template for the bug page will be split up as follows:
  • page header
  • login information and project selector
  • top menu
  • bug description
  • action menu
  • …
  • bug notes
  • page footer
• Template will be passed an array to determine what should be displayed (show). This will be prebuilt to enable features based on access level and features and fields that are enabled.
• bugs and other information will be passed through an instance of the “Bug” object. This allows some processing or formatting of the data before it is displayed (or controls are generated).
• Details of template form and construction can be found here.

|- mantis
    + core
    |   +- smarty (smarty dir, changeable)
    + languages
    |      +- eng
    |      +- etc....
    + themes
    |      +- theme1
    |          +- header.tpl
    |          +- footer.tpl
    |          +- page.tpl
    |          +- images
    |              +- image.png
    |          +- css
    |              +- mantis.css
    |      +- theme2
    |          +- page.tpl
    + themes_c    (compiled templates)
    |      +- theme1
    |          +- header.php
    |          +- footer.php
    |          +- page.php
    |      +- theme2
    |          +- page.php

• $g_c_template_path - path to writable compiled templates directory

• $g_theme_default - default theme to use
• $g_theme_override - override theme to use (usually set in a project or user)
• $g_hide_fields = ''; fields to hide in any view

• To Do List / Log

• The installer needs to be updated to create and check that the appropriate directories have been created. Note that the compiled templates need to be erased if the source files change.

Please add your comments and feedback in this section.

• How about introducing a standard where all parameters prepared and sent to the templates are prefixed with “tpl_”? (vboctor)
  • That would be a good idea. Note that for various reasons it is most efficient to pass variables to templates in arrays (or objects). So you would have a template to display bugs in a table. The code calling this template would assemble the data for the bugs into the array $tpl_bugs and then do $smarty→assign('bugs', $tpl_bugs) (djnz)
  • Agreed. Most bug related data should pass through objects. This allows some database lookups to be deferred when displaying the bug. (thraxisp)

• When a template is found, do we only default to one templates? What about the case where there is a theme the default theme, then another theme that is distributed with Mantis that overrides some of the templates, then the user introduced a new theme which only overrides a couple of templates. In this case we may need to fallback two levels. I believe that it should be part of the theme definition to specify which template it is based on (vboctor)
  • This functionality (theme overloading) is built into Smarty - just set $smarty→template_dir to an array and it will look for the template in each directory recursively. Note that it only does this at compile time for speed, so it is necessary to think about how you use Smarty's $compile_id, separate compile directories or some other way to separate themes. (djnz)
  • I will use the facilities in Smarty for this (thraxisp)

• We need to specify the configuration variables that will be added. We should probably consider the following: (vboctor)
  • Default theme (string)
  • Available themes (array)
  • Allow users to select theme (boolean).
  • Is there an advantage in making the path to the themes and themes_c folders configurable? Or should we just calculate them? (vboctor)
    • themes_c (if you want to call it that) should be configurable to allow users to move it outside the web root. (djnz)

• Specify the structure of the themes folder. For example, themes\theme1\ and themes\theme2. Then within each theme are we going to have all files in one level or are we going to separate images? (vboctor)
  • I would recommend that each theme has all its templates in a \templates directory, with a separate directory for \images (djnz)
  • notes added (thraxisp)

• It is probably worth clarifying the impact of using templates on the current code base. Other than the PHP web pages, this will also have a major impact on our print_* and html_* APIs. We need to separate the data preparation from the outputing of html. Most of the functionality in print_api.php should be refactored and moved into prepare_api.php or other APIs. (vboctor)
  • notes added (thraxisp)

• Are we going to make use of Smarty functions and modifiers? For example, a modifier that formats an issue id, rather than using the bug_format_id() API which is not really part of the business logic. (vboctor)
  • This would be a very good use for a Smarty modifier. It could also be made themeable. (djnz)

• It is probably worth specifying that we will distribute Smarty with Mantis and that it will be located under core/smarty. How big is the size of Smarty? What are the number of files? Are we going to trim it in any way? i.e. remove documentation or unit tests or whatever parts that we don't need? We didn't do any trimming for ADODB. (vboctor).
  • Smarty is smaller than ADODB. Having said that, we probably don't want the demo applications. (djnz)
  • SMARTY is about 1Mb, trimming it seems to be a good idea. (thraxisp)

• How is this going to affect our installation script? For example, are we going to check that themes_c (the folder that will contain the compiled templates) is writable by the webserver? (vboctor).
  • You need to check that themes_c is writeable, that is all. (djnz)
  • I would suggest emptying the themes_c directory during install. Smarty has some problems with recognizing changed templates. Emptying the compile directory removes this problem (jotango)
  • notes added (thraxisp)

• What will be involved in defining a new theme? For example, just dropping an extra folder and adding it to available themes? (vboctor)
  • The admin page that allows you to select themes should traverse the \themes directory so adding a new theme just means putting it in there! (djnz)
• Are we going to do any sort of theme versioning? What will happen when the code is updated but the theme doesn't support the new features? It may be worth documentation somewhere the kind of changes that need to be implemented by themes to support the new version but still work with the old theme if we can. (vboctor)
• Something that I don't like about applications that use Smarty is that if the web server doesn't have write access on the themes_c folder, the user gets an error if they visit a page. Is there a way where we can replace such errors with friendly errors that are easy to understand and fix by administrators? (vboctor)
  • Yes, this can easily be fixed by checking that the directory is writeable and displaying a friendly non-smarty page if it isn't. (djnz)
• Does Smarty support a mode where the compiled templates can be saved to the database rather than as files? (vboctor).
  • This would be a bad idea. Smarty compiles templates into PHP so that they run quickly, getting the benefit of any PHP accelerator you are running, or at least PHP's tokenizer. If you retrieved the compiled PHP from the database how would you execute it? (djnz)
  • I agree with djnz. Why would this be useful? (thraxisp)
• Having a theme per project is useful so that administrators can hide fields for different projects. However, these introduces complexity for the All Projects mode. Users will be switching from All Projects to a Specific Project causing the theme to change on them. There will also be the case where the current project is All Projects, but the issue the user is currently viewing belongs to Xyz Project. I wonder how are we going to handle this complexity. Are the templates the right approach to show/hide fields per project? Or should they only be used to do uniform behavior across projects and have some other configuration mechanism to show/hide fields based on the project. I think if we keep themes and projects independent, then we will have a more flexible and de-coupled approach. We probably need to include some details about this in the templates design (vboctor).
  • As currently implemented, show/hide of any field is included in the template. That is, you can hide fields per project (as it's read from a config) independently from the template. This feature should be in all templates. (thraxisp)
    • Having a theme per project may be used for branding. We have the handle the case where the selected project is All Projects and a bug from a specific project is viewed or being updated (vboctor).
      • The configuration system may handle this by finding the theme associates with 'ALL_PROJECTS' rather than a specific project on the view_all_bugs page.