Extending the Administration Area menu

Usually modules, which add new pages to the Administration Area, have corresponding items in the main Administration Area menu. The LemonStand API allows modules to register main menu items and tabs by overriding the listTabs() method of the module information class.

This method accepts a single parameter - a tab collection, which you should use for adding new items to the main menu. Definition of the listTabs() method:

public function listTabs($tabCollection)
{
}

The $tabCollection object has the tab() method, which adds an item to the LemonStand main menu. This method has 4 parameters - the item identifier, the item caption, the module-relative URL of a module page, which should be opened if a user selects the item in the main menu. The fourth parameter is a sort order integer value. The bigger value you specify, the lower place will have the item in the main LemonStand menu.

The tab() method returns another object, which you can use for adding tabs to the top Administration Area menu, by calling the addSecondLevel() method. This method accepts 3 parameters: the tab identifier, tab caption, and a module-relative page URL.

The menu item and tab identifiers are needed for marking a menu item and a tab as "current". We will demonstrate the concept in the next section.

Adding a main item and tabs to the blog module

In this section we will add a main menu item and two tabs to the blog module which we started in the Developing a simple module article. We are going to add the Blog menu item to the main menu, and two tabs for to the top Administration Area menu - the Posts and the Categories.

After adding the listTabs() method to the module information class, it has the following content:

<?php

  class AbcBlog_Module extends Core_ModuleBase
  {
    /**
     * Creates the module information object
     * @return Core_ModuleInfo
     */
    protected function createModuleInfo()
    {
      return new Core_ModuleInfo(
        "ABC Blog",
        "Adds blog features to a store",
        "ABC Company" );
    }
    
    public function listTabs($tabCollection)
    {
      $menu_item = $tabCollection->tab('abcblog', 'Blog', 'posts', 90);
      $menu_item->addSecondLevel('posts', 'Posts', 'posts');
      $menu_item->addSecondLevel('categories', 'Categories', 'categories');
    }
  }
?>

This code adds the Blog menu item to the main LemonStand Administration Area menu:

The menu item has the abcblog/posts URL, because LemonStand automatically adds a module-specific URL prefix to all module menu items. If you click on the Blog item, you will be redirected to the Posts page which we created earlier (in the Adding a back-end user interface article):

As you can see, the top menu does not look correctly - it displays the "Dashboard" word instead of the "Blog", and does not display tabs for the Posts and Categories pages. This is because we need to direct LemonStand to which main menu item a current page belongs. To do it we need to add a line to the index action code of the AbcBlog_Posts controller:

public function index()
{
  $this->app_module_name = 'Blog';
  $this->app_page_title = 'Posts';

  /*
   * We added this line to indicate a current main menu item
   */
  $this->app_tab = 'abcblog';
  
  $this->viewData['post_number'] = 10;
}

We specified the menu item identifier in the app_tab field of the controller object. Now LemonStand displays the menu item name correctly. But we also need to mark the Posts tab as current:

To do that we need to add another line to the action code.

public function index()
{
  $this->app_module_name = 'Blog';
  $this->app_page_title = 'Posts';
  
  $this->app_tab = 'abcblog';
  
  /*
   * This line has been added in order to mark the Posts tab as current
   */
  $this->app_page = 'posts';
  
  $this->viewData['post_number'] = 10;
}

The code assigns the 'posts' value to the controller's app_page field. The 'posts' value is an identifier of a top menu tab which we added previously using the addSecondLevel() method call in the module information class.

Now the navigation elements looks right - the page has the correct title, and corresponding main menu item and top menu tab are selected:

Usually all controller pages belong to the same main menu item and to the same top menu tab. For example our blog posts controller will have the following pages: post list, create post, edit post. All pages of the controller belong to the Blog main menu item and to the Posts top menu tab. It means that we can move the code which assigns values to the app_tab, app_page and app_module_name fields to the controller constructor. It will help to simplify actions code and to avoid repeating of the same code in all actions. Here is a final code of our blog posts controller. We also removed unnecessary test code:

<?
  class AbcBlog_Posts extends Backend_Controller
  {
    public function __construct()
    {
      parent::__construct();
      $this->app_module_name = 'Blog';
      $this->app_tab = 'abcblog';
      $this->app_page = 'posts';
    }

    public function index()
    {
      $this->app_page_title = 'Posts';
    }
  }
?>

Next: Using AJAX
Previous: Handling Errors and Displaying Status Messages
Return to Adding a Back-End User Interface