Custom template engines

Components can function with any template engine that can be plugged in PHP. To define a new template engine, create or edit the global variable $arCustomTemplateEngines in /bitrix/php_interface/init.php. This variable contains an associated array having the following format:

"template engine ID" => array(
    "templateExt" => array("ext1"[, "ext2"...]),
    "function" => "engine control function"
    )

Here:

"template engine ID" - an arbitrary unique name;
"extN" - file extension associated with the engine;
"engine control function" - the name of the function that will be called if a component template extension is extN. You can create the function in this file (/bitrix/php_interface/init.php).

For example, if you want to use Smarty on your site, add the following lines to /bitrix/php_interface/init.php:

global $arCustomTemplateEngines;
$arCustomTemplateEngines = array(
    "smarty" => array(
        "templateExt" => array("tpl"),
        "function" => "SmartyEngine"
    ),
);

This will cause templates with extension tpl to be run using the SmartyEngine function, which will run Smarty.

Template engine control function

function 
EngineControlFunction($templateFile, 
                      $arResult, 
                      $arParams, 
                      $arLangMessages, 
                      $templateFolder, 
                      $parentTemplateFolder, 
                      $template)

Here:

$templateFile – path to the template relative to the site root;
$arResult – a component result output array;
$arParams – a component input array;
$arLangMessages – language-dependent messages (array);
$templateFolder – path to the template folder relative to the site root (can be empty if the template does not occupy a separate folder);
$parentTemplateFolder - path to the template folder of a parent compound component, relative to the site root (can be empty if a simple component is plugged alone);
$template – template object.

The engine control function depends on the engine.

Example: adding Smarty engine

Add the following lines to /bitrix/php_interface/init.php:

global $arCustomTemplateEngines;
$arCustomTemplateEngines = array(
    "smarty" => array(
        "templateExt" => array("tpl"),
        "function" => "SmartyEngine"
    )
);

function SmartyEngine($templateFile, 
                      $arResult, 
                      $arParams, 
                      $arLangMessages, 
                      $templateFolder, 
                      $parentTemplateFolder, 
                      $template)
{
    if (!defined("SMARTY_DIR"))
        define("SMARTY_DIR", "<absolute path to Smarty>/libs/");

    require_once('<absolute path to Smarty>/libs/Smarty.class.php');

    $smarty = new Smarty;

    $smarty->compile_dir = "<absolute path to Smarty>/templates_c/";
    $smarty->config_dir = "<absolute path to Smarty>/configs/";
    $smarty->template_dir = "<absolute path to Smarty>/templates/";
    $smarty->cache_dir = "<absolute path to Smarty>/cache/";

    $smarty->compile_check = true;
    $smarty->debugging = false;

    $smarty->assign("arResult", $arResult);
    $smarty->assign("arParams", $arParams);
    $smarty->assign("MESS", $arLangMessages);
    $smarty->assign("templateFolder", $templateFolder);
    $smarty->assign("parentTemplateFolder", $parentTemplateFolder);

    $smarty->display($_SERVER["DOCUMENT_ROOT"].$templateFile);
}

Replace "<absolute path to Smarty>" with the absolute path to the Smarty installation folder. You will find more information on installation and using Smarty in its help section.

The array $arCustomTemplateEngines registers Smarty. The function SmartyEngine initializes its parameters according to Smarty requirements. Then, variables with component's output, input parameters, language messages etc. are passed to Smarty. Finally, Smarty is run and the output is displayed.

This simple example emphasizes on template engine connection. For real site, it can be modified according to requirements, you can use Smarty's filters etc. For example, to avoid creating Smarty instance every time a template is activated, you can use the following code:

global $smarty;
$smarty = null;

function SmartyEngine($templateFile, 
                      $arResult, 
                      $arParams, 
                      $arLangMessages, 
                      $templateFolder, 
                      $parentTemplateFolder, 
                      $template)
{
    if (!defined("SMARTY_DIR"))
        define("SMARTY_DIR", "<absolute path to Smarty>/libs/");

    global $smarty;
    if (!isset($smarty) || !is_object($smarty))
    {
        require_once('<absolute path to Smarty>/libs/Smarty.class.php');

        $smarty = new Smarty;

        $smarty->compile_dir = "<absolute path to Smarty>/templates_c/";
        $smarty->config_dir = "<absolute path to Smarty>/configs/";
        $smarty->template_dir = "<absolute path to Smarty>/templates/";
        $smarty->cache_dir = "<absolute path to Smarty>/cache/";

        $smarty->compile_check = true;
        $smarty->debugging = false;
    }
    else
    {
        $smarty->clear_all_assign();
    }

    $smarty->assign("arResult", $arResult);
    $smarty->assign("arParams", $arParams);
    $smarty->assign("MESS", $arLangMessages);
    $smarty->assign("templateFolder", $templateFolder);
    $smarty->assign("parentTemplateFolder", $parentTemplateFolder);

    $smarty->display($_SERVER["DOCUMENT_ROOT"].$templateFile);
}

Example: plugging in a XML/XSLT engine

global $arCustomTemplateEngines;
$arCustomTemplateEngines = array(
    "xslt" => array(
        "templateExt" => array("xsl"),
        "function" => "XSLTEngine"
    ),
);

function CreateXMLFromArray($xDoc, $xNode, $ar)
{
    foreach($ar as $key=>$val)
    {
        if(!is_string($key) || strlen($key)<=0)
            $key = "value";

        $xElement = $xDoc->createElement($key);
        if(is_array($val))
        {
            CreateXMLFromArray($xDoc, $xElement, $val);
        }
        else
        {
            $xElement->appendChild($xDoc->createTextNode(iconv(SITE_CHARSET, "utf-8", $val)));
        }
        $xNode->appendChild($xElement);
    }
    return $xNode;
}

function XSLTEngine($templateFile, 
                    $arResult,
                    $arParams,
                    $arLangMessages,
                    $templateFolder,
                    $parentTemplateFolder,
                    $template)
{
    $arResult["PARAMS"] = array(
        "templateFolder" => $templateFolder,
        "parentTemplateFolder" => $parentTemplateFolder,
        "arParams" => $arParams,
        "arLangMessages" => $arLangMessages
    );

    $xDoc = new DOMDocument("1.0", SITE_CHARSET);
    $xRoot = $xDoc->createElement('result');
    CreateXMLFromArray($xDoc, $xRoot, $arResult);
    $xDoc->appendChild($xRoot);

    $xXsl = new DOMDocument();
    $xXsl->load($_SERVER["DOCUMENT_ROOT"].$templateFile);

    $xProc = new XSLTProcessor;
    $xProc->importStyleSheet($xXsl);

    echo $xProc->transformToXML($xDoc);
}