Page Template Requirements
Author: Glenn Henshaw (thraxisp)
Introduction
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.
Implementation Notes
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'.
Database Changes
Template Construction
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:
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.
File Structure
|- 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
Configuration
$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
Implementation Log
Other Changes
Feedback
Please add your comments and feedback in this section.
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)
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)
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)
What will be involved in defining a new theme? For example, just dropping an extra folder and adding it to available themes? (vboctor)
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)
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)