Array
(
    [0] => menu item 1
        Array
            (
                [0] => menu item title
                [1] => menu item link
                [2] => array of additional links to highlight the menu item:
                    Array
                        (
                            [0] => link 1
                            [1] => link 2
                            ...
                         )
                [3] => array of additional variables passed to the menu template:
                    Array
                        (
                            [variable name 1] => variable value 1
                            [variable name 2] => variable value 2
                            ...
                         )
                [4] => condition which stipulates the menu item display
                       (the PHP expression returning "true")
            )
    [1] => menu item 2
    [2] => menu item 3
    ...
)

You can visually manage menu items using the Site Explorer module functionality. To do so, select Site Explorer -> Manage, then select the desired folder, click the link Add menu and select the required menu type. The system provides for two menu editing modes: Simple and Advanced.

You can make the process of menu management more simple by using the control toolbar in the public section. Click the button Show include areas to highlight areas editable through the user interface. Then click the button Edit menu items beside the desired menu.

Sometimes a task may arise when you need to define menu items programmatically. For example, you may want to display sections of the Information Blocks module catalog in a menu. To do so, you need to use service files .menu type.menu_ext.php. These files are to be stored in the required site section. The main purpose of these files is managing the array $aMenuLinks. Such files cannot be edited visually using the Site Explorer means, so they remain untouched when editing the menu in the visual editor.

Note
If you want to use files .menu type.menu_ext.php, you should pay attention to the second parameter of the functions CMain::GetMenuHtml and CMain::GetMenuHtmlEx when displaying the menu. This parameter should be set to true (false by default).

Note

If no menu is assigned to the current section explicitly (that is, no menu file exists in the folder), a menu of the first parent section that contains the menu file is used. It follows that a menu is hierarchically inheritable.

For example, a user is currently in the section /en/company/about/. The system uses the following sequence to search for the left type menu file:

1. /en/company/about/.left.menu.php
2. /en/company/.left.menu.php
3. /.left.menu.php

If the system succeeds to find the menu in one of the folders, the search is stopped and the system uses the found file.

Examples of menu files

<?
// file .left.menu.php

$aMenuLinks = Array(
    Array(
        "Phones", 
        "/catalog/phone/", 
        Array("/catalog/phone/index.php", "/catalog/phone/compare.php"), 
        Array(), 
        "" 
    ),
    Array(
        "Accessories", 
        "/catalog/accessory/", 
        Array("/catalog/accessory/index.php"), 
        Array(), 
        "" 
    ),
    Array(
        "Admin section", 
        "/catalog/admin/", 
        Array("/catalog/admin/index.php", "/catalog/admin/edit.php"), 
        Array("PARAM_1" => "Y"), 
        "\$GLOBALS["USER"]->IsAdmin()" 
    )
);
?>

<?
// file .left.menu_ext.php

if (CModule::IncludeModule("iblock")):

    $CACHE_TIME = "0";
    $IBLOCK_TYPE = "catalog";   // information block type
    $IBLOCK_ID = 22;            // information block ID
    $CACHE_TIME = 86400;        // cache time

    $aMenuLinksNew = array();
    $ROOT_SECTION_ID = 0;
    $CACHE_ID = __FILE__.$IBLOCK_ID;
    $obMenuCache = new CPHPCache;
    if($_GET["SECTION_ID"]>0)
        $CACHE_ADD .= "|SECTION_ID=".$_GET["SECTION_ID"];
    elseif($_GET["ID"]>0)
        $CACHE_ADD .= "|ELEMENT_ID=".$_GET["ID"];
    else
        $CACHE_ADD = "";

    // if the array is cached...
    if($obMenuCache->InitCache($CACHE_TIME, $CACHE_ID.$CACHE_ADD, "/"))
    {
        // use cached data
        $arVars = $obMenuCache->GetVars();
        $aMenuLinksNew = $arVars["aMenuLinksNew"];
    }
    else
    {
        $CACHE_ADD = "";
        if($_GET["SECTION_ID"]>0)
        {
            $res = CIBlockSection::GetNavChain($IBLOCK_ID, $_GET["SECTION_ID"]);
            if($ar_res = $res->Fetch())
            {
                $ROOT_SECTION_ID = $ar_res["ID"];
                $CACHE_ADD = "|SECTION_ID=".$_GET["SECTION_ID"];
            }
        }
        elseif($_GET["ID"]>0)
        {
            $res = CIBlockElement::GetElementGroups($_GET["ID"]);
            if($ar_res = $res->Fetch())
            {
                $CACHE_ADD = "|ELEMENT_ID=".$_GET["ID"];
                $res = CIBlockSection::GetNavChain(
                    $IBLOCK_ID, 
                    $ar_res["IBLOCK_SECTION_ID"]
                    );
                $ar_res = $res->Fetch();
                $ROOT_SECTION_ID = $ar_res["ID"];
            }
        }

        // otherwise, collect sections
        $rsSections = GetIBlockSectionList(
            $IBLOCK_ID, 
            0, 
            array("SORT" => "ASC", "ID" => "ASC"), 
            false, 
            array("ACTIVE"=>"Y")
            );
        while ($arSection = $rsSections->Fetch())
        {
            $aMenuLinksNew[] = array(
                $arSection["NAME"],
                SITE_DIR."catalog/accessory/section.php?SECTION_ID=".$arSection["ID"],
                ($ROOT_SECTION_ID==$arSection["ID"] ? Array("/") : Array())
            );
        }
    }
    // cache the data
    if($obMenuCache->StartDataCache($CACHE_TIME, $CACHE_ID.$CACHE_ADD, "/"))
    {
        $obMenuCache->EndDataCache(Array("aMenuLinksNew" => $aMenuLinksNew));
    }

    $aMenuLinks = array_merge($aMenuLinksNew, $aMenuLinks);
endif;
?>

Menu display

Menu is displayed in the visual section of either prologue or epilogue. The following two fundamentally different methods of menu display can be used.

Method 1. The menu template is included only once for all menu items. Menu is displayed using the following functions:
- CMain::GetMenuHtmlEx
- CMenu::GetMenuHtmlEx (an instance of the CMenu class must be initialised prior to calling this function)
Method 2. The menu template is included for each menu item. Menu is displayed using the following functions:
- CMain::GetMenuHtml
- CMenu::GetMenuHtml (an instance of the CMenu class must be initialised prior to calling this function)

Examples of menu display

<?
// display a menu of the type "top"
echo $APPLICATION->GetMenuHtmlEx("top");
?>

<?
// display a menu of the type "left" 
// with support for files .menu type.menu_ext.php
echo $APPLICATION->GetMenuHtml("left", true);
?>

<?
// display a menu of the type "left"
// with support for files .menu type.menu_ext.php
// specifying the template and
// a folder for which the menu is to be built

$obMenu = $APPLICATION->GetMenu(
    "left",
    true,
    "/bitrix/php_interface/".SITE_ID."/left.menu_template.php", 
    SITE_DIR
    );
echo $obMenu->GetMenuHtml();
?>

A menu template

A menu design is prescribed by a template, which is a PHP file itself. You can specify path to this file explicitly at the time of menu display. If you do not provide the template file path, the following algorithm is used to search for this file.

As stated above, menu is hierarchically inherited. That is, if no menu is assigned to the current section explicitly (that is, no menu file exists in the folder), a menu of the first parent section that contains the menu file is used.

For example, a user is currently in the section /en/company/about/. The system uses the following sequence to search for the left type menu file:

1. /en/company/about/.left.menu.php
2. /en/company/.left.menu.php
3. /.left.menu.php

If the system succeeds to find the menu in one of the folders, the search is stopped and the system uses the found file.

Each of these files may have the $sMenuTemplate variable defined containing the menu template path. If the file exists, it will be used as the menu template.
If the system is unable to find the menu template file, the following file is checked for existence:

/bitrix/templates/current site template ID/.menu type.menu.php

If the file exists, its path is used as the menu template path. Otherwise, the default file path is used:

/bitrix/templates/.default/.menu type.menu.php

Different sets of variables are available in templates depending on the preferred menu display method.

For the method 1, the following variables are available in a menu template:
- $sMenu - HTML code which defines the menu design;
- $arMENU_LINK - link to the source array of menu items (synonym: $MENU_ITEMS);
- $arMENU - copy of menu item array. Each menu item, in its turn, is an array with the following keys:
  - TEXT - menu item title;
  - LINK - menu item link;
  - SELECTED - defines whether the menu item is currently active; the following values are possible:
    - true - menu item is selected;
    - false - menu item is not selected.
  - PERMISSION - current user access permissions for the page to which the LINK points; the following values are possible:
    - D - access denied;
    - R - read (view the file contents);
    - U - workflow (file editing in the workflow mode);
    - W - write (direct file editing);
    - X - full access (direct file editing and access permission modification).
  - ADDITIONAL_LINKS - array of additional links which cause the menu item highlighting;
  - ITEM_TYPE - flag defining the LINK type; the following values are possible:
    - D - directory (LINK ends with "/");
    - P - page;
    - L - page with parameters.
  - ITEM_INDEX - menu item ordinal;
  - PARAMS - associated array containing the menu item parameters.
For the method 2, the following variables are available in a menu template:
- $sMenuProlog - HTML code to be added before the menu;
- $sMenuEpilog - HTML code to be added after the menu;
- $sMenuBody - HTML code which defines the menu item design;
- $arMENU_LINK - link to the source array of menu items (synonym: $MENU_ITEMS);
- $arMENU - copy of menu item array (structure of this array is described above);
- $TEXT - menu item title;
- $LINK - menu item link;
- $SELECTED - defines whether the menu item is currently active; the following values are possible:
  - true - menu item is selected;
  - false - menu item is not selected.
- $PERMISSION - current user access permissions for the page to which the LINK points; the following values are possible:
  - D - access denied;
  - R - read (view the file contents);
  - U - workflow (file editing in the workflow mode);
  - W - write (direct file editing);
  - X - full access (direct file editing and access permission modification).
- $ADDITIONAL_LINKS - array of additional links which cause the menu item highlighting;
- $ITEM_TYPE - flag defining the $LINK type; the following values are possible:
  - D - directory (LINK ends with "/");
  - P - page;
  - L - page with parameters.
- ITEM_INDEX - menu item ordinal;
- PARAMS - associated array containing the menu item parameters.

Menu item active state

The menu item link ($LINK) and the array of additional links ($ADDITIONAL_LINKS) define the active menu item (selected, highlighted). If the menu item is active, the variable $SELECTED=true is available in the menu template.

In respect to the active state, menu item links can be classified in the following types.

Link to folder ($ITEM_TYPE=D). Such links always end with "/". Links of this type are always highlighted if a user views a page within the folder, regardless of the page parameters.
Link to page ($ITEM_TYPE=P). Such links always end with the page file name. Links of this type are highlighted if a user views the page, regardless of the page parameters.
Link to page with parameters ($ITEM_TYPE=L). Such links end with the page file name, symbol "?" and pairs in the format parameter=value separated with ampersand &. Links of this type are only highlighted if a user views the page and the variables listed have the specified values (regardless of the order of parameters).

The below is the example of the menu item active state (symbol "X") at different combinations of the current page and the menu link.

Current page	Menu item link
Current page	/dir/	/dir/index.php	/dir/index.php?par1=val1
/dir/page.php	X
/dir/index.php	X	X
/dir/index.php?par1=val1	X	X	X
/dir/index.php?par1=val2	X	X

The menu item link may be absolute or relative. If the link is relative, it is always evaluated relative to the directory containing the menu file.

Consider the following conditions:

a menu file resides in /dir/ and one of the menu items contains a relative link index.php;
a user views the page /dir/subdir/index.php;
the subfolder /dir/subdir/ does not have its own menu file to use for display (see Menu files).

These conditions stipulates that the current menu item is not highlighted as it is previously converted to the absolute format /dir/index.php relative to the folder containing the menu file. The menu link points to that absolute file, correspondingly.

Examples of menu templates

The following is the menu template file .left.menu_template.php used to display a menu using the method 1 using CMain::GetMenuHtmlEx:

<?
if (is_array($arMENU) && count($arMENU)>0)
{
    $sMenu = "<table border='0' cellpadding='0' cellspacing='0' width='100%'>";

    foreach($arMENU as $arMENU_ITEM)
    {
        extract($arMENU_ITEM);

        // if link points to a folder...
        if ($ITEM_TYPE=="D")
        {
            // if item is active...
            if ($SELECTED)
                $strDir = "<td width='0%' bgcolor='#A0C4E0' valign='middle' align='center'>".
                          "<img height='13' src='../../../../../bitrix/templates/demo/images/left_folder_open.gif' ".
                          "width='17' border='0'></td>";
            else // otherwise...
                $strDir = "<td width='0%' bgcolor='#CCDFEE' valign='middle' align='center'>".
                          "<img height='13' src='../../../../../bitrix/templates/demo/images/left_folder.gif' ".
                          "width='17' border='0'></td>";
        }
        else // otherwise...
        {
            // if item is active...
            if ($SELECTED)
            {
                $strDir = "<td width='0%' bgcolor='#A0C4E0' valign='middle' align='center'>".
                          "<img height='13' src='../../../../../bitrix/templates/demo/images/left_bullet.gif' ".
                          "width='17' border='0'></td>";
                $strDir_d = "<td width='0%' bgcolor='#A0C4E0' valign='middle' align='center'>".
                            "<img height='13' src='../../../../../bitrix/templates/demo/images/left_bullet_d.gif' ".
                            "width='17' border='0'></td>";
            }
            else // otherwise...
            {
                $strDir = "<td width='0%' bgcolor='#CCDFEE' valign='middle' align='center'>".
                          "<img height='13' src='../../../../../bitrix/templates/demo/images/left_bullet.gif' ".
                          "width='17' border='0'></td>";
                $strDir_d = "<td width='0%' bgcolor='#CCDFEE' valign='middle' align='center'>".
                            "<img height='13' src='../../../../../bitrix/templates/demo/images/left_bullet_d.gif' ".
                            "width='17' border='0'></td>";
            }
        }

        // if item is active...
        if ($SELECTED)
            $strtext = "leftmenuact";
        else
            $strtext = "leftmenu";
            
        // if SEPARATOR=Y... 
        if ($PARAMS["SEPARATOR"]=="Y")
        {
            // show menu item differently
            $strstyle = " style='background-color: #D5ECE6; border-top: 1px solid #A6D0D7; ".
                        "border-bottom: 1px solid #A6D0D7; padding:8;'";
            $strDir = "<img height='13' src='../../../../../bitrix/templates/demo/images/1.gif' width='17' border='0'>";
            $strtext = "leftmenu";
        }
        else
            $strstyle = " style='padding:8;'";

        // if a user may access the page to which the item points...
        if ($PERMISSION > "D")
        {
            $sMenu .= '<tr><td colspan=2 background="/bitrix/templates/demo/images/l_menu_border.gif">'.
                      '<img src="/bitrix/templates/demo/images/1.gif" width="1" height="1"></td></tr>'.
                      '<tr>'.$strDir.'<td valign="top"'.$strstyle.' width="100%"><a href="'.$link.
                      '" class="'.$strtext.'">'.$TEXT.'</a></td></tr>';
        }
        else // otherwise...
        {
            $sMenu .= '<td colspan=2 background="/bitrix/templates/demo/images/l_menu_border.gif">'.
                      '<img src="/bitrix/templates/demo/images/1.gif" width="1" height="1"></td></tr>'.
                      '<tr>'.$strDir_d.'</td><td valign="top"'.$strstyle.' width="100%">'.
                      '<a href="'.$link.'" class='.$strtext.'>'.$TEXT.'</a></td></tr>';

        }
    }

    $sMenu .= '<tr><td colspan=2 background="/bitrix/templates/demo/images/l_menu_border.gif">'.
              '<img src="/bitrix/templates/demo/images/1.gif" width="1" height="1"></td></tr></table>';
}
?>

Similar menu template .left.menu_template.php, using the method 2 with a call to CMain::GetMenuHtml:

<?
$sMenuProlog = "<table border='0' cellpadding='0' cellspacing='0' width='100%'>";

// if link points to a folder...
if ($ITEM_TYPE=="D")
{
    // if menu item is active...
    if ($SELECTED)
        $strDir = "<td width='0%' bgcolor='#A0C4E0' valign='middle' align='center'>".
                  "<img height='13' src='../../../../../bitrix/templates/demo/images/left_folder_open.gif' ".
                  "width='17' border='0'></td>";
    else // otherwise
        $strDir = "<td width='0%' bgcolor='#CCDFEE' valign='middle' align='center'>".
                  "<img height='13' src='../../../../../bitrix/templates/demo/images/left_folder.gif' ".
                  "width='17' border='0'></td>";
}
else // otherwise
{
    // if menu item is active...
    if ($SELECTED)
    {
        $strDir = "<td width='0%' bgcolor='#A0C4E0' valign='middle' align='center'>".
                  "<img height='13' src='../../../../../bitrix/templates/demo/images/left_bullet.gif' ".
                  "width='17' border='0'></td>";
        $strDir_d = "<td width='0%' bgcolor='#A0C4E0' valign='middle' align='center'>".
                    "<img height='13' src='../../../../../bitrix/templates/demo/images/left_bullet_d.gif' ".
                    "width='17' border='0'></td>";
    }
    else // otherwise
    {
        $strDir = "<td width='0%' bgcolor='#CCDFEE' valign='middle' align='center'>".
                  "<img height='13' src='../../../../../bitrix/templates/demo/images/left_bullet.gif' ".
                  "width='17' border='0'></td>";
        $strDir_d = "<td width='0%' bgcolor='#CCDFEE' valign='middle' align='center'>".
                    "<img height='13' src='../../../../../bitrix/templates/demo/images/left_bullet_d.gif' ".
                    "width='17' border='0'></td>";
    }
}

// if menu item is active...
if ($SELECTED)
    $strtext = "leftmenuact";
else
    $strtext = "leftmenu";
    
// if SEPARATOR=Y... 
if ($PARAMS["SEPARATOR"]=="Y")
{
    // show menu item differently
    $strstyle = " style='background-color: #D5ECE6; border-top: 1px solid #A6D0D7; ".
                "border-bottom: 1px solid #A6D0D7; padding:8;'";
    $strDir = "<img height='13' src='../../../../../bitrix/templates/demo/images/1.gif' width='17' border='0'>";
    $strtext = "leftmenu";
}
else
    $strstyle = " style='padding:8;'";

// if a user may access the page to which the item points...
if ($PERMISSION > "D")
{
    $sMenuBody = '<tr><td colspan=2 background="/bitrix/templates/demo/images/l_menu_border.gif">'.
                 '<img src="/bitrix/templates/demo/images/1.gif" width="1" height="1"></td></tr>'.
                 '<tr>'.$strDir.'<td valign="top"'.$strstyle.' width="100%"><a href="'.$link.
                 '" class="'.$strtext.'">'.$TEXT.'</a></td></tr>';
}
else // otherwise
{
    $sMenuBody = '<td colspan=2 background="/bitrix/templates/demo/images/l_menu_border.gif">'.
                 '<img src="/bitrix/templates/demo/images/1.gif" width="1" height="1"></td></tr>'.
                 '<tr>'.$strDir_d.'</td><td valign="top"'.$strstyle.' width="100%"><a href="'.$link.
                 '" class='.$strtext.'>'.$TEXT.'</a></td></tr>';

}

$sMenuEpilog = '<tr><td colspan=2 background="/bitrix/templates/demo/images/l_menu_border.gif">'.
               '<img src="/bitrix/templates/demo/images/1.gif" width="1" height="1"></td></tr></table>';
?>

Both of the above examples will generate similar output:

Menu

In this topic

What is menu