H-Sphere Documentation Customization Guide

For more information contact us at info@psoft.net

Left Menu Customization


Related Docs:  

Template Customization Skin And Icon Set Customization Interface Controls And Colors Providing Multilingual Support

You can customize the Control Panel menu by:

Before you start customizing the CP menu, it is highly advisable that you become familiar with customizing H-Sphere templates (see the Template Customization chapter of this manual).

Throughout this document we will refer to the shiva/ directory, which is located in /hsphere/local/home/cpanel/. Hereafter, we will refer to it as shiva.


Restructuring the Menu

This section explains how to change the menu structure for existing plans or create new menus for new plans. You are expected to be familiar with XML technology.

The structure of the control panel navigation menu is defined in the file shiva/psoft/hsphere/menu.xml. It is a simple XML document consisting of 3 main parts:
1. DTD scheme description;
2. Definition of menu items and groups (tag <menus>);
3. Definition of menus for different hosting plans (tag <interface>).


Menu Item And Group Definition

Here is a fragment from the second part of menu.xml:


<menu name="SiteStudio" label="sitestudio.label" defaultitem="SiteStudio-edit" tip="sitestudio.tip">
    <menuitem name="SiteStudio-edit" label="sitestudio.edit.label"
            URL="list.html" resource="" tip="sitestudio.edit.tip"/>
    <menuitem name="SiteStudio-add" label="sitestudio.add.label"
            URL="add.html" resource="" tip="sitestudio.add.tip"/>

As you can see, the <menus> part includes groups of menu items where each of group is defined by the tags <menu ...>...</menu> and comprises definitions of items in this group (the <menuitems .../> tags).

Attributes in the <menu> tag have the following meaning:
- name - the name of the group;
- label - the mnemonical identifier defined in the menu.properties file to show the item text;
- defaultitem - the name of the default active item in the group;
- tip - the identifier to define the alternative text.

Attributes in the <menuitem > tag have the following meaning:
- name - the name of the item
- label - the mnemonical identifier (see above) ;
- URL - the template file the item refers to;
- resource - the resource name that must exist in the account for this item to be shown in the menu;
- tip - the definition of the alternative text.


Menu Definition For Different Plans

The third part of menu.xml includes <menudef ...></menudef> structures for all hosting plans in your system:

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

In H-Sphere, each plan type has its own corresponding menu configuration. These menu types are set by the menudef structures in menu.xml. These are the standard menu types for the corresponding 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) In menu.xml, add the new menudef structure and fill it with menu groups and items as shown in the above example:

<menudef id="custom_menuId">

2) Login as root and restart H-Sphere.

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

Every menudef structure lists the menu groups to show in this specific plan:

<initmenu /> tag defines which item group will be added to the menu.
<menuitem .../> adds menu items that don't belong to any group.

To restructure the menu, do the following:

1) Regroup items in the <menus> part of the menu.xml file.

2) Select groups of menu items for each hosting plan in the <interface> part of the menu.xml file.

3) Edit menu labels as described below in the Editing Menu Texts chapter.

4) Login as root and restart H-Sphere.


Assigning External Links to Menu Items

H-Sphere is designed in such a way that 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 the shiva-templates directory and would be searched by H-Sphere in one of the design subdirectories (common, replacements, and the like).

A solution may be in creating in one of the design directories a specially-formatted HTML document which would serve as a redirect to the external URL. So, the URL attribute should be set to this newly created document and thus any clicking on the menu item would redirect a user to the external link.

Let us consider the example of the menu customization where the admin user on logout would go directly to a certain page, let say, to his/her corporate site:

1) In ~cpanel/shiva/psoft/hsphere/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 preferrable to place this file to the ~cpanel/shiva/shiva-templates/common/misc directory.se. In this case, the URL attribute should be set as:


Note: Before making any change to the menu.xml file, either backup it to, for example, menu.xml.old, and/or copy and comment the line you would like to change, like this:

<!-- comment the old line: -->
<!-- <menuitem name="logout" label="logout.label" URL="design/logout.html&action=logout" resource="" tip="logout.tip"/> -->
<!-- the changed line: -->
<menuitem name="logout" label="logout.label" URL="misc/logout_redirect.html" resource="" tip="logout.tip"/>

4) In the specified directory, create the redirecting HTML file. In the example above, it would be ~cpanel/shiva/shiva-templates/common/misc/logout_redirect.html. The HTML redirecting document should be of the following format:

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

5) Restart H-Sphere.

6) Refresh browser to see the changes. It would be better to log on again.


Editing Menu Texts

The default menu texts are stored in the shiva/psoft/hsphere/lang/ directory in the menu.properties file. (H-Sphere may have several files similar to menu.properties, each of them comprising menu labels for different languages - menu_de.properties for German, menu_ru.properties for Russian,etc.).

To replace them with those of your own, do the following:

Step 1: Create the directory shiva/custom/bundles/. If this directory already exists, skip this step.

Step 2: In this directory, create an empty file named menu.properties. If you wish to customize any of the language properties files, you should also create the corresponding empty menu_<lang>.properties files. Even if you don't intend to change the English version, you should anyway create the empty menu.properties file.

Step 3. Open the file with default labels and copy the lines you want to modify into the new file making necessary changes to their content.

Important! Don't copy those default definitions you don't want to change, because your custom definitions would override any H-Sphere changes that come with the consequent updates!

Step 4: Open the ~cpanel/shiva/psoft_config/hsphere.properties file and uncomment the line corresponding to the file you have created:

 CUSTOM_MENU_BUNDLE = custom.bundles.menu

Step 5: Due to the peculiar mechanism of language bundle processing, it is essential that you create the following symlink into your custom bundle location (shiva/custom/bundles/): menu_en.properties to menu.properties.


Customizing menu design

This section explains how to change the appearance of the navigation menu in the H-Sphere control panel. You are expected to be familiar with the FreeMarker technology.

I. First of all, you need to go to shiva and create custom/ directory. You may already have such directory.

II. Inside custom/ directory, create the following directories:

  • templates/
  • images/
  • bundles/

You may already have them.

* Note: If images directory is created, there should be a symlink to this directory from the Apache document root (usually ~cpanel/shiva/shiva-templates); if not, users should place their images into the IMAGES directory.

III. Put your images into the images/ directory and your lang/text bundles into the bundles/ directory.

IV. In the templates/ directory, create the common/ directory and copy the menu.fn file from the shiva-templates/common/ directory into it.

The following Freemarker functions are used in menu.fn to draw the navigation menu:

- <function draw_menu(activeItem)>;
- <function draw_sub(item, level)>;
- <function draw_item(item, level)>;
- <function draw_blank_menu()>.

These functions draw different elements of the control panel menu. If you change them please note that the HTML tags you add must be well ordered and valid. For example, you have to make sure that the number of columns in the menu table, which is set in draw_menu, is the same in all these functions.

(a) The draw_menu function calls the other mentioned functions to draw the menu and also defines the menu table as follows:


(b) The draw_sub function draws the menu item which is the node for the submenu (group name):

The menu_was_drawn variable is used to figure out how to show the next item.

(c) The draw_item function draws the menu item which does not have a submenu. It may be a second-level item:

Or, it could be even a first-level item that does not fall into any menu group:

(d) The draw_sub_items function checks the type of the menu item and calls functions (b) or (c):

If you don't want to use a standard H-Sphere image, change the following calls:

<call draw_image("standard-image-mnemonic-id")>


<IMG SRC="path_to_your_image/replacing_image" WIDTH="xx" HEIGHT="yy"></TD>

where path_to_your_image could be set either as the /IMAGES URL relative to the Apache document root, or as any absolute URL to your image, like http://www.yourdomain.com/replacing/image/dir/.

VI. Open the shiva/psoft_config/hsphere.properties file, uncomment and correct (if necessary) the following lines:

USER_TEMPLATE_PATH = <full_path_to_shiva>/custom/templates/
CUSTOM_MENU_BUNDLE = custom.bundles.menu

where <full_path_to_shiva> is the physical path to the shiva directory (e.g. /hsphere/local/home/cpanel/shiva).

Note: Don't initialize the variables you are not using!

VII. Login as root and restart H-Sphere.

Related Docs:  

Template Customization Skin And Icon Set Customization Interface Controls And Colors Providing Multilingual Support

Home   Products   Services   Partners   Support   News   Contact   Forum
© Copyright 1998-2003. Positive Software Corporation.
All rights reserved.