Smarty Templates for Piwik

The Smarty 2.6.x Template Engine is used extensively throughout Piwik. This is a guide to writing and using Smarty templates for Piwik.

Instantiating Views

Controllers (subclasses of Piwik_Controller) can instantiate views (subclasses of Piwik_View) in two ways.

Here, the path to the Smarty template, "viewName.tpl", is implied by the controller invoking the factory() method: 

    $view = Piwik_View::factory('viewName');

Alternately, views can be instantiated using the constructor explicitly with the full path to the template (relative to the Piwik document root): 

    $view = new Piwik_View("pluginName/templates/viewName.tpl");

Rules/Conventions/Guidelines

Templates:

  • must be located in the plugin's "templates" sub-folder
  • must have the file extension, '.tpl'
  • should validate against XHTML 1.0 Transitional; @see #124
    • for greater cross-browser compatibility, use only these self-closing tags: <br />, <hr />, <input />, and <img />
    • the id attribute of an element must be unique for the document
  • order of external stylesheets (*):
    1. themes/default/common.css (must be first because it contains our css reset)
    2. libs/*.css
    3. plugins/*.css
    4. template_css_import hook
    5. inline styles
  • order of external scripts (*):
    1. libs/*.js
    2. themes/default/common.js (has dependencies on third-party libraries)
    3. plugins/*.js
    4. template_js_import hook
    5. inline scripts

(*) : Deprecated, kept for reference. Smarty templates should not include .css nor .js files. Please refer to  AssetManager.getJsFiles and AssetManager.getCssFiles hooks.

An "HTML fragment" is markup that is either loaded via AJAX or a subtemplate that is included by other templates:

  • may contain <link> and <style> elements
    • although not valid XHTML this appears to work with AJAX loaded content added to the DOM
    • @todo: #660 for subtemplates, the output filter moves it into the <head>
  • should avoid "Flash of unstyled content"
    • recommend inline <style> ???
  • should use inline JavaScript and jQuery's ready() handler for initialization: 
    <script type="text/javascript">
    $(function () {
        // initialization code here
    });
</script>
  • may depend on external JavaScript files
    • @todo: #660 for subtemplates, the output filter moves it into the <head>

Smarty Flags

The following Smarty flags (variables) are defined for use by templates:

@todo See ticket #115.

Smarty Functions

@see core/PluginsFunctions @see libs/Smarty/plugins

jQuery / jQuery-UI Tips

  • Do not use jQuery.load('url #hash) unless you expect/want <script> elements to be removed.

Technical Issues

Smarty 3.0

Currently, there are no plans to migrate to Smarty 3.0 due to risk and performance tradeoffs. We will periodically re-assess the situation WRT ongoing maintenance effort.

  • currently in beta
  • exhibits longer compile times
  • Piwik does not use Smarty's output cache