Templates

This is a developer guide towards using Templates in phpMyAdmin. As a whole, it is applicable on master branch towards version 4.6 or later and not for QA_4_5 or earlier.

Instantiating, passing data and rendering a template

A Template can be instantiated either using new or the static method get(), by providing template's pathname(at least) as argument, as shown below:-

use PMA\libraries\Template; $template = new Template($pathname [, $data [, $helperFunctions ] ] ); // or $template = Template::get($pathname [, $data [, $helperFunctions ] ] );

The string $pathname contains template's path (relative to the base path templates/) plus file name (without the extension .phtml).

The optional arrays $data and $helperFunctions contain the associated data variables and functions to be passed for use in the template scope.

Setting data for a template

A single data entry or an array of data can be set for a template, as shown below:-

$template->set("variableName", $variableValue); // setting a single key/value pair or $template->set( // setting whole array of data array( "variableName" => $variableValue ) );

Rendering

After instantiating and passing data, the template can be rendered to yield HTML:-

$html = $template->render();

Or in most cases, you will need to pass the generated html to the response object and all above steps are generally performed collectively as:-

$response->addHTML( Template::get("relative/path/to/template_name_without_phtml") ->render( array( "variableName" => $variableValue ) [, $trim //optional false, default true [, $helperFunctions ] ] //optional, if you want to pass functions here itself ) );

$trim if passed as false would not trim the returned html of whitespaces between tags and innerHTML.

Further, a template can be easily nested inside another using the same rendering mechanism as above.

Using data inside a template

We use PHP's inbuilt template parsing mechanism and no new syntax is to be learnt, i.e. HTML and PHP can be used as usual, subject to our coding conventions discussed in a sub-section of this page. Within the template scope, only those data variables will be available that are passed to it from the controllers. The passed variables can then be used just like variables in local scope. For ex:-

// Note the use of htmspecialchars to escape the user input `

About the use of $GLOBALS variables in templates, one could use them directly but should prefer passing them explicitly for use as a local variable. An example of direct use is:-

<?php if ($GLOBALS['cfg']['ShowColumnComments']): ?>

` = $comments ?>` ` ` Using helper functions in templates -----------------------------------

Ideally, after we have passed data variables to the template, it should not need many functions except PHP supplied functions like htmlspecialchars. But we might still need few functions to perform operations/transformations on data in templates. And although by using proper namespaces, functions can directly be referenced from within the templates; it is not desirable as it will offset the gains of decoupling achieved by using templates. So we must explicitly pass the functions which we intend to use in a template.

Passing anonymous function:-

$template->setHelper('functionAlias', function ($arg1 [, $arg2 [,...] ]) { // do something with arguments return $result; });

Passing a static function of some class:-

$template->setHelper("functionAlias", array(__NAMESPACE__ .'\ClassName', "functionName")); // an example of much used Util class $template->setHelper("getHtmlTab", array("\PMA\libraries\Util", "getHtmlTab"));

Passing a member function of an object of a class:-

$object = new SomeClass(); $template->setHelper("functionAlias", array($object, "functionName"));

Next we pass some relevant data, to be used as arguments when calling 'functionAlias' from within the template

$template->set( array( 'arg1' => 'value1' 'arg2' => 'value2' ) );

Thereafter, the function can be used in the template via $this, as follows:

<?php $this->functionAlias($arg1 [, $arg2 [,...] ]) ?>

Conventions for templates

Coding standards

• Use 'short echo' tag <?= $var ?>, in place of ''

  ''. Further, the short tag <? ?> should not be used at all.

• When using control structures like if, while, for, foreach, and switch, the 'alternative syntax' must be used, see: https://www.php.net/manual/en/control-structures.alternative-syntax.php

• For better readability, prefer to use Inline PHP, instead of blocks of PHP, i.e. <?php //single_statement_per_block_without_semi_colon ?>

• When using a function, it must be explicitly passed to the template from the controller and must not be referenced directly in the template, except in case of PHP's natively supplied functions.

Naming files and folders

• In 'templates/' folder, the template files are to be organized in folders named after respective controllers in which they are used. For ex:- the phtmls corresponding to 'TableSearchController' should lie in 'templates/table/table_search' folder.
• Further, the template files should be named after particular actions in a controller. For example: the template used by 'indexAction' of 'TableSearchController' should be 'templates/table/table_search/index.phtml'. Surely, there will be many other helper templates as well (common or specific to a controller) and they can be named/arranged suitably.

Category:Devel