Bitrix Site Manager

Menu

In this topic

What is menu

A menu is the design element which serves as the main navigation facility. Menu can be of two different types; each displayed in its proper place of the site design:

Menu files

Menu is attached to a site section using a service PHP file with the name .menu type.menu.php. This file resides in the corresponding section of the site. The following standard variables can be used in this file:

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.

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.

  1. 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.

  2. 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.

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.

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
/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:

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:

Additional information