User Tools

  • Logged in as: anonymous (anonymous)
  • Log Out

Site Tools


mantisbt:page_template_requirements

This is an old revision of the document!


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.
  • 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.

Database Changes

  • none should be required

Template Construction

  • 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).

Other Changes

Feedback

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)
  • 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)
  • 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)
  • 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)
    • 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)
  • 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)
  • 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)
mantisbt/page_template_requirements.1159719253.txt.gz · Last modified: 2008/10/29 04:31 (external edit)

Driven by DokuWiki