|
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:
<menus>
<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"/>
</menu>
.
.
.
</menus>
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:
<interface>
<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"/>
</menudef>
.
.
.
</interface>
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">
...
</menudef>
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:
URL="misc/logout_redirect.html"
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:
<HTML>
<HEAD>
<meta HTTP-EQUIV="refresh" CONTENT="0; URL=http://external_link">
</HEAD>
<BODY>
</BODY>
</HTML>
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:
<TABLE WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0">.
(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")>
with:
<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.
|
