Bitrix Site Manager

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:

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:

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);
}