Bitrix Site Manager

CMain::IncludeFile

CMain::IncludeFile(
 string path,
 array params = array(),
 array function_params = array()
)

The method IncludeFile is the main function you use to include any files within the page body, prologue or epilogue. It is the only method to use to include component. The visual aspect of the included file represents the include area.

The following buttons and icons relate to this method.
Show Include Areas button on the control toolbar. If checked, the include files become framed in colour border.
The controls that may be displayed in the top right corner of the frame are described below.
Include area frame controls
  Means that the included file is a standard component shipped with the module; the component will be copied to the folder /bitrix/templates/current site template ID/ before editing.
Means that the include file is stored in either /bitrix/templates/.default/ or /bitrix/templates/current site template ID/ (the file may be a component).
Means that the Workflow module is installed and the include file can be edited using the workflow facilities.

Parameters

ParameterDescription
path Path to the included file.

If the parameter contains the path relative to the site root, the method includes this file unconditionally. If the file cannot be found and the button Show include areas is checked, the frame-placeholder contains the blue button linked to the page allowing to create a new file in the folder specified in the parameter path.

If the parameter specifies the path to the main file of the component, the method attempts to find and include the file using the following rules.
  1. In the folder
    /bitrix/templates/current site template ID/path
  2. If the file is not found, the method tries the folder 
    /bitrix/templates/.default/path
  3. If the file is still not found, the method attempts to locate it in the module installation location:
    /bitrix/modules/module ID/install/templates/path,
    where module ID is the first folder of the path.
params Array of parameters to be passed to the include file. Array has the following format:
array(
 "parameter name 1" => "parameter value 1", 
 "parameter name 2" => "parameter value 2", 
 ...)
The include file initialises variables with names taken from the array keys; the variables values are the corresponding values of the array. This operation is performed using the standard PHP function extract(params).
function_params Array with the parameters for the method. The following keys allowed.
  • SHOW_BORDER - specifies to show or hide the design frame and buttons:
    • true - show frame if the button Show include areas is checked (default);
    • false - hide frame.
  • NAME - the Edit button tooltip text;
  • LANG - two-character identifier of the language that should be used to edit the file in the administrative section (current site language by default);
  • BACK_URL - page to which the user should be returned after the editing completes. By default, the current page in the public section.
  • WORKFLOW - specifies the include file is a part of the workflow:
    • true - the Edit link points to the Workflow module;
    • false - the Edit link points to the Site Explorer module (default).
  • MODE - editing mode:
    • text - edit file as text (link to edit the file in plain text mode);
    • html - edit file as HTML (link to edit the file in the HTML mode);
    • php - edit file as PHP (link to edit the source code of the file) (default).
  • TEMPLATE - if the path parameters specifies the absolute path to a missing file, this entry of the array should contain the name of the template file which is used to create a new file (by default, the method takes the first template according to their sort weight specified in the file /bitrix/templates/current site template ID/page_templates/.content.php)

See Also

Example

The following example shows how to include a component in a page.


<?
// the component displaying the information block contents
$APPLICATION->IncludeFile("iblock/catalog/element.php", Array(
    // Type of information block
    "IBLOCK_TYPE"       => "catalog",
    // information block
    "IBLOCK_ID"         => "21",
    // element ID
    "ELEMENT_ID"        => $_REQUEST["ID"],
    // URL to the page with the section contents
    "SECTION_URL"       => "/catalog/phone/section.php?",
    // type of information block whose elements are linked to the current one
    "LINK_IBLOCK_TYPE"  => "catalog",
    // ID of information block whose elements are linked to the current one
    "LINK_IBLOCK_ID"    => "22",
    // property with link
    "LINK_PROPERTY_SID" => "PHONE_ID",
    // URL of the page displaying the link of linked elements
    "LINK_ELEMENTS_URL" => "/catalog/accessory/byphone.php?",
    // Fields
    "arrFIELD_CODE" => Array(                                  
         "DETAIL_TEXT",
         "DETAIL_PICTURE"),
     // properties
    "arrPROPERTY_CODE" => Array(                               
         "YEAR",
         "STANDBY_TIME",
         "TALKTIME",
         "WEIGHT",
         "STANDART",
         "SIZE",
         "BATTERY",
         "SCREEN",
         "WAP",
         "VIBRO",
         "VOICE",
         "PC",
         "MORE_PHOTO",
         "MANUAL"),
    // cache time (sec.)
    "CACHE_TIME"        => "3600",                              
    ));
?>

Example of including a file in the site epilogue.


<?
// include area
$APPLICATION->IncludeFile($APPLICATION->GetCurDir()."sect_inc.php", 
                          Array(), 
                          Array(
                          "MODE"      => "html",// use html editor
                          "NAME"      => "Edit include area", // tooltip text
                          // new file template:
                          "TEMPLATE"  => "section_include_template.php"
                          ));
?>
© 2001-2005 Bitrix Bitrix Site Manager - Content Management & Portal Solutions