Changing Menu Structure

H-Sphere's control panel menu structure is defined in XML file, ~cpanel/shiva/psoft/hsphere/menu.xml by default.

This document explains how you can make changes into the XML structure in order to:

• modify menu items and groups
• configure individual menu layouts for different plans
• add external links to menu items

Location

The default location of menu.xml is set in ~cpanel/shiva/psoft_config/hsphere.properties:

MENU_CONFIG = /hsphere/local/home/cpanel/shiva/psoft/hsphere/menu.xml

Texts for menu elements are set in language bundles:

MENU_BUNDLE = psoft.hsphere.lang.menu

XML Structure

menu.xml consists of the following blocks going one after another:

1. DTD scheme;
2. definition of menu groups (tag <menus>)
3. definition of menu layouts for different hosting plans (tag <interface>)

Here is an example of the menu.xml file.

Modifying Menu Groups And Items

Groups of menu items are set within the menus tag. Each group is defined by a menu tag and comprises definitions of items in this group (menuitem tags), as well as inclusions of submenus (initmenu tags).

<menus>

<menu name="SomeMenu" label="somemenu.label" defaultitem="SomeMenu-Item1" tip="somemenu.tip">
    <menuitem name="SomeMenu-Item1" label="somemenu.edit.label"
            URL="template1.html" resource="" tip="somemenu.edit.tip"/>
    <menuitem name="SomeMenu-Item2" label="somemenu.add.label"
            URL="template2.html" resource="" tip="somemenu.add.tip"/>
    . . .
    <initmenu name="SomeSubmenu">
    . . .
</menu>
.
.
.
<menu name="SomeSubmenu" label="somesubmenu.label" defaultitem="SomeSubmenu-Item1" tip="somesubmenu.tip">
    <menuitem name="SomeSubmenu-Item1" label="somesubmenu.item1.label"
            URL="submenu_template1.html" resource="" tip="somesubmenu.item1.tip"/>
    . . .
</menu>
.
.
.
</menus>

These menu groups are grouped into different menu layouts defined below in menu.xml within the interface container.

Attributes of the menu tag:

• name - the name of the group.
• label - the mnemonic identifier of the text label for the menu group name displayed in CP. This label is set in the menu.properties bundle, for example:
  

  somemenu.label = Sample Menu Group

  See more about interface text bundles.
• defaultitem - the name of the menu item that becomes active by default when the menu group is opened; contains the menu item name (the name attribute of the menu tag).
• tip - the menu group tooltip label set in the menu.properties bundle.

Attributes of the menuitem tag:

• name - the name of the item.
• label - the menu item mnemonic identifier from the menu.properties bundle (see explanation above for the label attribute of the menu tag).
• URL - the template file the item refers to, the pathname is relative to each design directory in the template directory. Read more in Understanding Templates for template directory structure.
• resource - the resource name that must exist in the account for this item to be shown in the menu.
• tip - the menu item tooltip label set in menu.properties.

Attributes of the initmenu tag:

• name - name of the menu group referred to the name attribute of the menu tag described among other menus in the menus container.

According to menu.xml customization rules, you can do the following modifications in the structure of menu items and groups:

1. add/delete menu groups, items and submenus, and edit their attributes.
2. choose menu items to be activated by default when menu group is opened in CP.
3. restructure the order of menu items within a group.

Configuring Individual Menu Layouts For Different Hosting Plans

Each hosting plan in H-Sphere may have its own menu configuration set in menu.xml after the description of menu groups. Plan menu structure is set by the menudef tag within the interface container. For example:

<interface>
.
.
.
<menudef id="TestPlan">
        <initmenu name="acct-pref"/>
        <initmenu name="billing"/>
        <initmenu name=""/>
        <menuitem name="logout" label="logout.label"
         URL="design/logout.html&action=logout" resource="" tip="logout.tip"/>
</menudef>
.
.
.
</interface>

The menudef tags contain sets of menu groups and separate items in order of their appearance in H-Sphere interface. The name attribute of initmenu tags points to the name of the respective menu group defined above in menu.xml in the menus container.

The value for the id attribute of the menudef tag (TestPlan in the example above) must be the same as of the menuId parameter in the Plan Settings form (the Info->Plans menu, the Settings icon for the plan, in admin CP). Please refer to the Plan Settings document in Admin Guide.

These are default menu identifiers for the standard H-Sphere plan types:

unix - Unix plan;
admin - Admin plan;
ttadmin - Trouble Ticket Admin plan;
bill - Billing plan;
reseller - Reseller plan;
winduz - Windows plan;
real - Real Server plan;
mysql - MySQL Only plan;
email_only - E-Mail Only plan;
vps - VPS plan.

To add your custom menu and assign it to a specific plan, do the following:

1. According to menu.xml customization rules, add the new menudef structure for the plan and fill it with menu groups and items as shown in the above example:

   <menudef id="custom_menuId">
   ...
   </menudef>

2. In the admin panel, in the plan Settings form, set the menuId custom value to custom_menuId (read the Plan Settings document in Admin Guide for details.)

Assigning External Links to Menu Items

It is not possible to put a direct URL to the external page in the menu XML description. The path in the URL attribute of the menuitem element is relative to design subdirectories of the template directory (~cpanel/shiva/shiva-templates by default) and will be searched by H-Sphere according to its template lookup sequence.

A solution is in creating a template (specially-formatted HTML document) redirecting to an external URL.

Consider an example of menu customization where to a certain external page on logout from admin CP.

We assume that menu.xml and the template created are customized properly according to the respective customization rules.

Note: Alternatively, instead of creating a new logout_redirect.html template with an external link, you may customize the standard logout.html template without customizing menu.xml. The example below is given merely to illustrate menu.xml customization.

1) In menu.xml, find the element corresponding to the admin plan:

<menudef id="admin">

This would mean we are going to change CP menu only for the admin user and the change would not affect resellers and other plans.

2) Within this menudef element, find the line:

<menuitem name="logout" label="logout.label" URL="design/logout.html&action=logout" resource="" tip="logout.tip"/>

3) Change the URL attribute to the HTML file which would redirect to the URL you want. It is preferable to place this file to the ~cpanel/shiva/shiva-templates/common/misc directory. In this case, the URL attribute should be set as:

URL="misc/logout_redirect.html"

4) In the specified directory, create the redirecting HTML file. H-Sphere will search for it in ~cpanel/shiva/custom/templates/common/misc/logout_redirect.html.
See more about template lookup sequence.

The HTML redirecting document will be organized as follows:

<HTML>
  <HEAD>
    <meta HTTP-EQUIV="refresh" CONTENT="0; URL=http://external_link">
  </HEAD>
  <BODY>
  </BODY>
</HTML>

5) Restart H-Sphere after the customization is dome.

6) Refresh browser to see the changes. It is better to logout and login again.