This document will guide you through:
Throughout this document we will often relate to the shiva/ directory,
which is located in the /hsphere/local/home/cpanel/ cpanel user home
directory. Hereafter, we will refer to it as shiva.
WARNING:
1. Advanced customization
may produce unpredictable results after updating H-Sphere,
since updates affect the template structure and the page generation.
2. Advanced customization performed by H-Sphere customers is done at their own
risk and is not supported by the PSoft team.
3. You may order customization from the PSoft team. Such customization
is supported hereafter. Please contact
sales@psoft.net for pricing details.
Customizing Templates
Templates are HTML documents that contain instructions for
including dynamically-generated data. In other words, context
data is put into the templates to create relevant H-Sphere
pages. Templates are modified to change the web page layout,
e-mail notifications, and context help texts.
IMPORTANT:
Template customization affects ALL H-Sphere accounts, regardless of their plans!
In terms of H-Sphere customization, only two types of accounts are customized,
regardless of plans: admin accounts which are H-Sphere administrative accounts,
and user accounts - all other accounts. Reseller accounts are regarded as user accounts,
except for the reseller administrative account which relates to the admin account type.
Location of Templates
The default templates are located on the CP server in the
shiva/shiva-templates/ directory in the
/hsphere/local/home/cpanel/ cpanel user home directory.
Types of Customizable Templates
The following types of templates can be customized:
Web page layout: you may find the pairs of .html and .html.in
files - two types of templates that are responsible for displaying web pages.
*.html.in templates are templates
with client-side form validation. It is generally
preferrable to modify these templates, and you should do this
if you perform serious changes in template structure, for example,
when you change your default DocumentRoot from
the shiva/shiva-templates directory to your custom
directory, or when you change the default location of images.
However, *.html.in template customization is a sophisticated procedure,
as it requires re-compilation
before modifications would take effect.
Read more about compiling templates
with client-side form validation.
*.html templates are templates for
server-side form validation. It is easier to customize such templates,
as they don't require recompilation, and any modification takes effect immediately.
It is sufficient to customize *.html templates if you don't change default template settings.
E-mail notifications: system e-mails are also generated
from templates and must be changed according to the instructions
laid out in this document. E-mail templates are located in
the shiva/shiva-templates/common/mail directory and have
.txt extension.
See the
list of system e-mail templates.
Online help: special templates, each with
a topic header and a body. They can be modified according
to the procedure described in this section. Online help files
are located next to templates in the shiva/shiva-templates/common/online_help
directory. They have .oh extension and contain the text in HTML format.
See the instructions how to add context help pages to H-Sphere interface.
Also read about
providing context help in different languages.
How To Find Templates That Need To Be Modified
Depending on H-Sphere design, template file is located in these standard design
subdirectories of the shiva-templates directory:
- common - the so-called left-menu interface design;
- nomenu - the so-called no-menu interface design;
- text_based - the so-called text-based interface design: no-menu design without
icons.
Read more about H-Sphere designs in
Skin and Icon Set Customization Guide.
a) Header:
design/top.html
- template responsible for displaying the Control Panel header. Depending on design,
this template is located in the three above mentioned standard design directories.
b) Footer:
design/bottom.html
- template responsible for displaying the control panel footer. Depending on design,
this template is located in the three above mentioned standard design directories.
c) Other Templates:
To find out the name and location of the template that needs to be modified,
do the following:
- View the source of the web page to be modified.
- At the beginning of the page, find the tag that would have the following format:
<!-- BEGIN ./path_to_template/template_file.html -->
- Depending on design, this file is located in the following subdirectories
of the shiva-templates directory:
• common/path_to_template/template_file.html
• nomenu/path_to_template/template_file.html
• text_based/path_to_template/template_file.html
Example: The page displaying the list of plans in the
INFO->Plan Creation Wizards menu has the following tag with template name:
<!-- BEGIN ./admin/plan_wizards.html -->
Thus, depending on the design, the template is located in the following directories:
• /hsphere/local/home/cpanel/shiva/shiva-templates/common/admin/plan_wizards.html
• /hsphere/local/home/cpanel/shiva/shiva-templates/nomenu/admin/plan_wizards.html
• /hsphere/local/home/cpanel/shiva/shiva-templates/text_based/admin/plan_wizards.html
Template Customization Pre-Requisites
Before you do any customization, log in as the cpanel user, e.g., under root:
# su - cpanel
To implement customization correctly, all template files and directories should have
cpanel:cpanel ownership, and the make directive which is performed
to rebuild *.htmltemplates should be run ONLY under the cpanel user.
Do not use whitespaces in the template filenames!
DO NOT MAKE ANY CHANGES TO THE DEFAULT TEMPLATES,
because
1) You may need them to restore the original setup;
2) You will lose all your changes with the next upgrade.
Instead, follow the step-by-step instructions specified below.
Step-By-Step Template Customization Procedure
Step 1. On the CP server, login as the cpanel user under root:
# su - cpanel
Step 2. In shiva/, create directory custom/templates/.
Step 3. Copy the templates you would like to substitute
into shiva/custom/templates/ preserving their file
paths relative to this directory. E.g. If you are going to
substitute the
shiva/shiva-templates/not_recomended/to_change/FILE,
copy it to
shiva/custom/templates/not_recomended/to_change/FILE.
In case of mail templates, copy
shiva/shiva-templates/common/mail/mail_template
to
shiva/custom/templates/common/mail/mail_template.
The original configuration can be restored without server
restart by simply deleting your custom files from the shiva/custom/templates
directory.
WARNING:
Don't copy the whole directory content! Your custom
templates will override the default templates and you won't
see the new features and bugfixes that come with new versions!
Step 4. Make sure the file is owned by cpanel:cpanel.
Step 5. Modify the templates you have
copied to the shiva/custom/templates/ directory. Please
carefully follow the instructions on
Interface Controls and Colors and
Skin and Icon Set Customization.
To edit interface texts, please refer to the section below.
Step 6. Now that you have had the templates edited,
get them used instead of the defaults. In the file
shiva/psoft_config/hsphere.properties
find the USER_TEMPLATE_PATH line. Here, enter the
full name of the directory with your custom templates, e.g.
/hsphere/local/home/shiva/custom/templates/.
Important: The directory name must end with a slash!
Don't do anything if the directory name is already there.
WARNING:
Don't change the TEMPLATE_PATH variable in hsphere.properties!
TEMPLATE_PATH points to the default template directory.
If you change it, you won't see any updates in the default templates.
Step 7. Log in as root and restart H-Sphere. You don't
need to restart H-Sphere if you did nothing on step 4.
If you don't know how to restart your H-Sphere, click here.
Editing Interface Texts
(version 2.07 and higher)
This section explains how to override original menu items
and labels for the admin and user control panels with custom
texts. E-mail notifications and context help texts are changed
according to the procedure described in the
Customizing Templates paragraph.
Interface texts are stored in the form of
key=value sets called resource bundles, or bundles, where key
is the text mnemonic identifier,
and value is the text itself that may vary depending on language.
Templates include mnemonic identifiers and thus
generate language-independent dynamic content.
Default menu items and labels are set in the following files of the
shiva/psoft/hsphere/lang/ directory:
- hsphere_lang.properties - template and tooltip texts;
- menu.properties - the navigation menu texts;
- messages.properties - H-Sphere system messages.
Interface texts in other languages are stored in the same directory
in the corresponding files:
- hsphere_lang_LANG.properties
- menu_LANG.properties
- messages_LANG.properties
where LANG is a language identifier.
For more details, please refer to the
Providing Multilingual Support
documentation.
WARNING:
Do not make any changes to these default lang files!
You may need them to restore the original setup, and
you will lose all your changes with the next upgrade.
To alter original menu items and labels, do the following:
Step 1: Log in as cpanel user:
su - cpanel
All modified files should have the cpanel:cpanel ownership.
Step 2: Create the custom bundle directory shiva/custom/bundles/.
If this directory already exists, skip this step.
Step 3: In the listed files, find the string you want
to modify. Next, in the newly created directory, create a
new empty file with exactly the same name as the one with the
original string. For example, you are going to change
the label Shell Access to SSH Access. It is stored in the
shiva/psoft/hsphere/lang/hsphere_lang.properties
file. Create the file shiva/custom/bundles/hsphere_lang.properties.
Step 4: Copy the line with the identifier and the
value you want to change into the new file and change its
value the way you want. You should use two single quotes
(apostrophes) instead of one in labels containing curly
brackets, such as {0}. For example:
search.view_invoice = View Client's Invoice
but billing.del_no = No, I don''t want to delete {0}
WARNING:
Don't copy the texts you are not changing! This will override the default settings,
and you will not see the changes that come with new versions!
Step 5: Make sure the file is owned by cpanel:cpanel.
Step 6: Now you need to declare the custom bundles.
In the hsphere.properties file, uncomment the line
that corresponds to the file you have created:
CUSTOM_TEMPLATE_BUNDLE = custom.bundles.hsphere_lang
CUSTOM_MENU_BUNDLE = custom.bundles.menu
CUSTOM_USER_BUNDLE = custom.bundles.messages
Step 7: Create two symlinks in your document root:
hsphere_lang_en.properties to hsphere_lang.properties and
menu_en.properties to menu.properties
Step 8: Log in as root and
restart H-Sphere.
You don't need to restart H-Sphere if you did nothing on step 4.
|