Managing module menus in Control Panel

This section describes how to manage the Control Panel menus.

Main structure

For each module, the menu parameters are specified in the file: /bitrix/module_catalogue/admin/menu.php. This file should create the module menu description array. API allows to create a tree menu of an arbitrary nesting level. The tree nodes and branches can be created dynamically.

The menu.php file returns an associated array of the following structure:

Key	Description
parent_menu	Menu section identifier. This key is meaningful only for the upper level of the module menu tree. Can be one of the following values. global_menu_content - the Content section; global_menu_services - the Services section; global_menu_store - the Store section; global_menu_statistics - the Web Analytics section; global_menu_settings - the Settings section.
sort	The relative weight of a menu item (for sorting).
url	A menu item link. When a visitor opens this URL, the corresponding menu item will be highlighted.
more_url	A list of additional URL that will cause the corresponding menu item to be highlighted.
text	A menu item link text.
title	A menu item tooltip text.
icon	The CSS class of the menu item icon.
page_icon	The CSS class of the menu item icon that is displayed on the index page (larger image).
module_id	The module identifier to which the menu belongs.
dynamic	Specifies whether the branch starting with the current item is to be created dynamically.
items_id	The menu node identifier. Used for dynamically created branches.
items	A list of child menu items in the form of an array. Each element is an associated array of similar structure.

Example

The menu.php file for the Web Form module (simple static menu).


<?
IncludeModuleLangFile(__FILE__); // in menu.php, language files can be used as well

if($APPLICATION->GetGroupRight("form")>"D") // check the Web Form module access level
{
  // build the upper menu item
  $aMenu = array(
    "parent_menu" => "global_menu_services", // put it into the Service section
    "sort"        => 100,                    // the menu item weight
    "url"         => "form_list.php?lang=".LANGUAGE_ID,  // the menu item link
    "text"        => GetMessage("FORM_MENU_MAIN"),       // the menu item text
    "title"       => GetMessage("FORM_MENU_MAIN_TITLE"), // the tooltip text
    "icon"        => "form_menu_icon", // the small icon
    "page_icon"   => "form_page_icon", // the large icon
    "items_id"    => "menu_webforms",  // the node identifier
    "items"       => array(),          // other menu levels will be built below.
  );

  // now obtain the list of web forms and 
  // add corresponding menu items for each of them
  require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/form/include.php");
  $z = CForm::GetMenuList(array("LID"=>LANGUAGE_ID));
  while ($zr=$z->GetNext())
  {
    if (strlen($zr["MENU"]) > 0)
    {
      // array of each item is built similarly
      $aMenu["items"][] =  array(
        "text" => $zr["MENU"],
        "url"  => "form_result_list.php?lang=".LANGUAGE_ID."&WEB_FORM_ID=".$zr["ID"],
        "icon" => "form_menu_icon",
        "page_icon" => "form_page_icon",
        "more_url"  => array(
            "form_view.php?WEB_FORM_ID=".$zr["ID"],
            "form_result_list.php?WEB_FORM_ID=".$zr["ID"],
            "form_result_edit.php?WEB_FORM_ID=".$zr["ID"],
            "form_result_print.php?WEB_FORM_ID=".$zr["ID"],
            "form_result_view.php?WEB_FORM_ID=".$zr["ID"]
            ),
        "title" => GetMessage("FORM_RESULTS_ALT")
       );
    }
  }

  // if more more items are required, 
  // add elements to $aMenu["items"]
  // ............

  // return the obtained list
  return $aMenu;
}
// return false if access is denied
return false;
?>

Dynamic creation of menu nodes and branches

As it has been already mentioned, th system allows to build menus with dynamically created nodes and branches. For this, the following steps are required:

set "dynamic" to true for nodes requiring dynamic items;
specify the "items_id" parameter and the module ID for nodes requiring dynamic items;
check the "expanded" state when creating child items of a dynamic node.

The last step implies calling CAdminMenu::IsSectionActive(). Since the menu building script runs in the context of the CAdminMenu class instance, it is sufficient to assert $this->IsSectionActive() specifying the value of the "items_id" parameter of a required branch.

The below is an example of the same Web Form module menu whose list of forms is created dynamically.


<?
// in menu.php, language files can be used as well
IncludeModuleLangFile(__FILE__);


// check the Web Form module access level
if($APPLICATION->GetGroupRight("form")>"D")
{
  // leave the upper menu item untouched
  $aMenu = array(
    "parent_menu" => "global_menu_services", // put it into the Service section
    "sort"        => 100,                    // the menu item weight
    "url"         => "form_list.php?lang=".LANGUAGE_ID,  // the menu item link
    "text"        => GetMessage("FORM_MENU_MAIN"),       // the menu item text
    "title"       => GetMessage("FORM_MENU_MAIN_TITLE"), // the tooltip text
    "icon"        => "form_menu_icon", // the small icon
    "page_icon"   => "form_page_icon", // the large icon
    "items_id"    => "menu_webforms",  // the node identifier
    "items"       => array(),          // build the other menu levels below.
  );

  // build the menu items that will be loaded dynamically
  $arFormsList = array();
  if (
    // compatibility check
    method_exists($this, "IsSectionActive") 
    && 
    // if a menu section "menu_webforms_list" is active
    $this->IsSectionActive("menu_webforms_list")
    ||
    // you can also add your own conditions. 
    // For example, display this node on all pages
    // where the FORM_MENU_OPEN constant is set to 1
    defined('FORM_MENU_OPEN') && FORM_MENU_OPEN == 1) 
  {
  
    // now perform the same operation but store elements in a separate array
    require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/form/include.php");
    $z = CForm::GetMenuList(array("LID"=>LANGUAGE_ID));
    while ($zr=$z->GetNext())
    {
      if (strlen($zr["MENU"]) > 0)
      {
        // array of each item is built similarly
        $arFormsList[] =  array(
          "text" => $zr["MENU"],
          "url"  => "form_result_list.php?lang=".LANGUAGE_ID."&WEB_FORM_ID=".$zr["ID"],
          "icon" => "form_menu_icon",
          "page_icon" => "form_page_icon",
          "more_url"  => array(
              "form_view.php?WEB_FORM_ID=".$zr["ID"],
              "form_result_list.php?WEB_FORM_ID=".$zr["ID"],
              "form_result_edit.php?WEB_FORM_ID=".$zr["ID"],
              "form_result_print.php?WEB_FORM_ID=".$zr["ID"],
              "form_result_view.php?WEB_FORM_ID=".$zr["ID"]
              ),
          "title" => GetMessage("FORM_RESULTS_ALT")
         );
      }
    }
  }
  
  // now build the root of the dynamic menu branch.
  // pay attention to the highlighted parameters.
  
  $aMenu["items"][] = array(
    "text" => GetMessage("FORM_RESULTS_ALL"),
    "url" => "form_result_list.php?lang=".LANGUAGE_ID,
    "title" => GetMessage("FORM_RESULTS_ALL_ALT"),
	
    "dynamic" => true,                  // !!!!!!!!!!!!!!!!!!!!!!!!!
    "module_id" => "form",              // !!!!!!!!!!!!!!!!!!!!!!!!!
    "items_id" => "menu_webforms_list", // !!!!!!!!!!!!!!!!!!!!!!!!!
    "items" => $arFormsList,            // !!!!!!!!!!!!!!!!!!!!!!!!!
	
  );
  
  // if you want to add more items, 
  // add elements to $aMenu["items"]
  // ............

  // return the obtained list
  return $aMenu;
}
// return false if access is denied
return false;
?>