Components 2.0

Redefining input variables

Each component has a set of variables to accept the input data. For example, the bitrix:catalog.section component has the variables IBLOCK_ID and SECTION_ID in which the catalog and product group ID's are passed.

All components of which a composite component consists should follow the uniform variable naming rules. For example: the bitrix:catalog component and all its subcomponents (bitrix:catalog.list, bitrix:catalog.section etc.) use variables IBLOCK_ID, SECTION_ID, ELEMENT_ID etc.

Use the parameter VARIABLE_ALIASES if you want to redefine the variables of a composite component you add to a page.

In SEF mode, this parameter must be in the following format:

"VARIABLE_ALIASES" => array( 
      "list" => array(),
      "section" => array(
                        "IBLOCK_ID" => "BID",
                        "SECTION_ID" => "ID"
                        ),
                        "element" => array(
                        "SECTION_ID" => "SID",
                        "ELEMENT_ID" => "ID"
                        ),
)

Here, the array keys mirror those existing in a path template array. Variables can be redefined for each path individually.

In non-SEF mode, this parameter has the following format:

"VARIABLE_ALIASES" => array(
                           "IBLOCK_ID" => "BID",
                           "SECTION_ID" => "GID",
                           "ELEMENT_ID" => "ID",
)

Example 1:

Assume that we want to have the bitrix:catalog component in /fld/cat.php handle the following paths:

/catalog/index.php – for catalog index;
/catalog/section/group_code.php?ID=catalog_code – for product groups;
/catalog/element/product_code.php?ID=group_code – for detailed information about a product.

Specify the following assignments in the component input parameters:

"SEF_MODE" => "Y",    
"SEF_FOLDER" => "/catalog/",
"SEF_URL_TEMPLATES" => array(
                    "list" => "index.php",
                    "section" => "section/#SECTION_ID#.php?ID=#IBLOCK_ID#",
                    "element" => "element/#ELEMENT_ID#.php?ID=#SECTION_ID#"    
                            ),
"VARIABLE_ALIASES" => array(
                     "list" => array(),
                     "section" => array(
                                   "IBLOCK_ID" => "ID"),
                     "element" => array(
                                   "SECTION_ID" => "ID",),

Example 2:

Now we want the bitrix:catalog component to handle the following paths:

/fld/cat.php – for catalog index;
/fld/cat.php?BID=catalog_code&SID=group_code – for product groups;
/fld/cat.php?ID=product_code&SID=group_code – for detailed information about a product.

Specify the following assignments in the component input parameters:

"SEF_MODE" => "N",
"VARIABLE_ALIASES" => array(
                           "IBLOCK_ID" => "BID",
                           "SECTION_ID" => "SID",
                           "ELEMENT_ID" => "ID",
                           ),

Using custom template engines

Components can use any template engine that can be plugged in to PHP.

To add a new template engine, edit the /bitrix/php_interface/init.php file as follows:

1. Add a global variable $arCustomTemplateEngines containing an associated arrays, each element of which having the following format:

"template_engine_id" => array( 
"templateExt" => array("ext1"[, "ext2"...]),
"function" => "engine_activator_function"     
)

here:
template_engine_id – an arbitrary unique identifier;
extentionN – the extension of files that will be handled by this template engine;
engine_activator_function – the name of a function that will be called whenever a component template has the specified extension.

2. Declare the engine activator functions:

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

here:
$templateFile – the path to a template file relative to the site root;
$arResult – an array of the component return values;
$arParams – an array of the component input parameters;
$arLangMessages – an array of the template language dependent messages;
$templateFolder – the path to the template folder relative to the site root (empty if a template is not in a folder);
$parentTemplateFolder – the path to a composite component template folder relative to the site root (empty if the component is orphan);
$template – the template instance.

Consider the following examples of adding the template engines.

Adding the Smarty template engine

Declare the Smarty engine in the $arCustomTemplateEngines array:

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

Now, declare the SmartyEngine function and initialize the engine parameters according to the Smarty requirements (see the Smarty help). Then, pass the component return variables, the input parameter variables, the language dependent message variables etc. to Smarty. Finally, the call the Smarty preprocessor/render method:

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

Adding the XML/XSLT engine

First, initialize the engine:

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

Declare the engine initializing function:

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

Activate the engine:

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