This product is protected by United States and international copyright laws. The product’s
underlying technology, patents, and trademarks are listed at
http://www.parallels.com/trademarks.
Microsoft, Windows, Windows Server, Windows NT, Windows Vista, and MS-DOS are
registered trademarks of Microsoft Corporation.
Linux is a registered trademark of Linus Torvalds.
Mac is a registered trademark of Apple, Inc.
All other marks and names mentioned herein may be trademarks of their respective owners.
Items you must select,
such as menu options,
command buttons, or
items in a list.
Go to the System tab.
Titles of chapters,
sections, and
subsections.
Read the Basic Administration chapter.
Italics
Used to emphasize the
importance of a point, to
introduce a term or to
designate a command
line placeholder, which is
to be replaced with a real
name or value.
The system supports the
so called wildcard character search.
Monospace
The names of
commands, files,
directories, and domain
names.
The license file is located
in the
http://docs/common/
licenses directory.
C H A P T E R 1
Preface
Typographical Conventions
Before you start using this guide, it is important to understand the documentation
conventions used in it.
The following kinds of formatting in the text identify special information.
Preface 7
Preformatted
On-screen computer
output in your commandline sessions; source
code in XML, C++, or
other programming
languages.
# ls –al /files
total 14470
Preformatted
Bold
What you type,
contrasted with on-screen
computer output.
# cd /root/rpms/php
CAPITALS
Names of keys on the
keyboard.
SHIFT, CTRL, ALT
KEY+KEY
Key combinations for
which the user must
press and hold down one
key and then press
another.
CTRL+P, ALT+F4
Feedback
If you have found a mistake in this guide, or if you have suggestions or ideas on how to
improve this guide, please send your feedback using the online form at
http://www.parallels.com/en/support/usersdoc/. Please include in your report the
guide's title, chapter and section titles, and the fragment of text in which you have found
an error.
There are the following tiers of Parallels H-Sphere control panel customization:
Customizable
Elements
Description
Templates
Design and control patterns for dynamic HTML
generation. They are to be modified if you need to
restructure the layout of certain pages of the Control
Panel interface, or to change the look of the Control
Panel header and footer.
System E-Mail
Notifications
A special type of templates used to generate standard
email notifications sent by Parallels H-Sphere.
Context Help
A special type of templates to generate context help
for certain elements of the Control Panel interface.
GUI Texts
Standard messages and labels that appear on the
interface pages are placed in the special configuration
files and may be set for different languages.
Localization
Adding new languages to the interface and modifying
language files with interface texts in different
languages.
CP Menu
Generating and modifying control panel menus and
submenus and adding external links to the menu.
GUI Design
Parallels H-Sphere interface design has a broader
C H A P T E R 2
Introduction To Parallels H-Sphere
Customization
Basic interface settings can be configured through the control panel. The Look and Feel
menu allows to set skins and colors, images and icons, and some interface texts.
Advanced interface customization is what goes beyond the scope of the Control Panel
settings. It is performed on the Parallels H-Sphere CP server by designers and
programmers with administrative rights, in order to create or modify Parallels HSphere interface elements.
Parallels H-Sphere Packages (.hsp) are installable addons that extend H-Sphere
functionality. This is a way to share custom elements between Parallels H-Sphere
installations. Third parties can use it to develop and distribute packages that add
new or extend/override standard Parallels H-Sphere functionality. Documentation
on building packages is introduced in Parallels H-Sphere Developer Guide.
This Customization Guide explains how to customize the following Parallels H-Sphere
elements:
Introduction To Parallels H-Sphere Customization 9
(Skins And
Icon Sets)
meaning than just configuration of certain color
schemes and the corresponding icon sets, what is
called the skin. It also determines the set of skins
available for this design, specifies the sets of icons in
the Quick Access page and enables to override the
standard settings with the custom ones.
CP Crons
Parallels H-Sphere utilities regularily executed on the
Control Panel server.
Plan Wizards
Custom plan wizards defined and configured in XML
documents.
Merchant
Gateways
The media for making real-time payments with online
credit card processing centers automatically from the
CP.
Web Payment
Systems
The media for making payments manually from the
web interface of the payment systems.
Signup Forms
Generating custom signup forms to sign up users
aside from the standard signup procedure provided in
Parallels H-Sphere, as well as modifying the standard
signup pages.
Warning:
1. Advanced customization may produce unpredictable results after updating Parallels
H-Sphere, since updates affect the template structure and the page generation.
2. Advanced customization performed by Parallels H-Sphere customers is done at their
own risk and is not supported by the Parallels.
This section explains how to customize Parallels H-Sphere templates.
Adding Context Help Pages .............................................................................. 20
System E-Mail Templates .................................................................................. 22
Customizing User Signup .................................................................................. 25
C H A P T E R 3
Template Customization
Template Customization 11
Understanding Parallels H-Sphere
Templates
What Are Templates
Parallels H-Sphere templates lay behind the Parallels H-Sphere Control Panel Web
interface. For the most part, templates are written using Freemarker Java processing
language for dynamic content generation.
Location of Templates
Template root directory
Parallels H-Sphere template root directory is by default ~cpanel/shiva/shiva-
templates. It is set by the TEMPLATE_PATH parameter in the
~cpanel/shiva/psoft_config/hsphere.properties file:
Default (common) design directory
Design, or skin, is the Control Panel GUI representation. Each design is defined by its
own sets of templates, images, CSS styles, JavaScripts, etc. The most important part
of GUI, templates, are placed in separate subdirectories of the template root directory
in accordance with a design they belong to. The special common subdirectory is used
to store templates that are the same for different designs. Also, this directory contains
templates for the Left Menu design which is the default Parallels H-Sphere design. The
path to this directory, relative to TEMPLATE_PATH, is set in hsphere.properties:
DEFAULT_TEMPLATES = common/
Important: Common template directory must always exist!
Custom template directory
Custom template directory is usually ~cpanel/shiva/custom/templates. Its
location is set in hsphere.properties:
Custom templates directory structure should correspond with the default template root
directory (shiva-templates) tree. However, you should be aware that templates in
the custom template directory override the corresponding templates in the default
template directory, thus all modifications and new features in existing default templates
coming with new Parallels H-Sphere releases would be also overriden by custom
templates. Therefore, only customized templates should be placed to your custom
template directory.
System E-Mail Notification Templates
System email notifications templates are used to generate standard Parallels H-Sphere
e-mail messages sent to customers or to admins on certain events related to account
management, billing, and the like. It is made possible to edit these messages directly
from Control Panel, in plain text or HTML and for each of the available languages,
without the need of customizing the default templates.
E-mail templates are located in the ~cpanel/shiva/shiva-templates/common/mail directory and have .txt extension. See the list of the
system e-mail templates (on page 22).
Skeletons
Skeleton templates, or skeletons, are special templates designed to generate user
default sites for newly created domains in corresponding domain subdirectories of user
home directories. Skeleton templates are written in HTML (without Freemarker
instructions) and located in the /hsphere/shared/skel directory. See how to modify
default skeletons (on page 20).
Web Interface Templates
Templates for generating Control Panel interface pages are of the following types:
main templates
control templates
submit templates
function templates
special purpose templates
context help page templates
Main Templates
Main, or basic, templates are templates for generating the entire Web page in CP. The
code of a main template represents a framework that contains calls of functions (on
page 22) for generation of the page header, menu and footer, and includes control
templates for processing forms.
Template Customization 13
Main templates are .html files located in the ~cpanel/shiva/shivatemplates/<design>/ directories for each design (on page 22).
Control Templates
Contol templates, or controls, are responsible for generation and management of forms
in the working area of Parallels H-Sphere interface. They represent the part of HTML
code included in the main templates.
Control templates are with or without form field validation mechanism implemented:
Client-side form validation: .html.in templates provide client-side form validation.
They need to be compiled to apply changes made in them. The corresponding .html
templates are generated as the result of compilation of .html.in templates of the
same name. Thus, if there is a pair of .html and .html.in templates with the
same name, it is recommended to modify the .html.in template and then to
recompile it. Read more about compiling templates with client-side validation (on
page 19).
No field validation mechanism is implemented in .html templates that do not have the
initial .html.in templates of the same name. Changes in .html templates take
effect immediately.
Control templates are located in the ~cpanel/shiva/shiva-templates/<design>/control directories for each group of main templates.
Control templates assign submit templates that do not have visual HTML
representation and serve solely to process form submits.
Submit Templates
Submit templates do not have visual representation. They contain instructions to be
performed upon the form submit. These templates provide server-side validation of
submitted data and scenarios of subsequent actions if submit is successful or if an error
occurs. Submit template files have .sbm extension.
Function Templates
These templates contain collections of functions (or macros) used in other templates,
for example, for drawing menu, footer and header.
~cpanel/shiva/shiva-templates/<design>/menu.fn - functions for drawing
menu for a particular design.
~cpanel/shiva/shiva-templates/<design>/design.fn - functions for
drawing interface elements for a particular design (implemented for common and
XPressia/XPressia Lite designs)
~cpanel/shiva/shiva-templates/<design>/extra.fn - extra functions.
14 Template Customization
~cpanel/shiva/shiva-
templates/common/control/signup_function.html - functions for signup
templates.
Templates For Special Purposes
There are some Web interface templates that do not fall into any of the above
mentioned categories. They are designed for special tasks such as to draw a menu on
the left, or the page header or footer, or login page, etc. Some special purpose
templates are located in the ~cpanel/shiva/shiva-
templates/<design>/design/ directory, some like signup_top.html.in or
signup_bottom.html in the ~cpanel/shiva/shivatemplates/<design>/signup directory. There is no general classification for such
templates.
Context Help Templates
Context help templates are special templates for generating online help message in
popup windows. Each context help template has its topic header and body. They can
be modified as usual Parallels H-Sphere templates.
Online help files are located in the ~cpanel/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
Parallels H-Sphere interface (on page 20). Also read about context help in different
languages (on page 68).
Designs
Design, or skin, is the Control Panel GUI representation. It provides a different look of
menu (left menu or dropdown menu on the top, or no menu present at all), CSS styles,
colors and images, and the Quick Access page with icon links to different CP pages.
These are basic Parallels H-Sphere designs whose templates are located in the
corresponding design template directories of ~cpanel/shiva/shiva-templates
(referred to as <design> in the document):
common - the left-menu design (Left Menu in CP). All core templates are made for this
design scheme. Other templates that do not depend on design, inlcuding online
help templates (on page 11) and system e-mail notification templates (on page 11),
are also located there.
nomenu - the design with no left menu (No Menu in CP). It is turned on as the default
user design after the Parallels H-Sphere installation.
text_based is the alternative look of the No Menu design (Text-Based in CP) where only
captions with no icons are provided in the Quick Access menu page.
xcp - the XPressia design with dropdown menus, extensive use of CSS styles and
other advancements.
xcpl - the XPressia Lite design, a simpler and faster implementation of XPressia.
reloaded - the XP Reloaded design introduced in H-Sphere 3.0.
Template Customization 15
If a certain template is not found for a particular design, Parallels H-Sphere gets that
template in the common directory.
The default design configuration file design_config.xml is located in the
~cpanel/shiva/psoft/hsphere/ directory.
Replacements
Replacements are templates that override basic templates for particular plans.
Replacements' root directory for each design is the ~cpanel/shiva/shiva- templates/<design>/replacements directory. Replacements are located in
separate subdirectories specified in plan settings as the Template Directory parameter,
relative to the replacement directory.
Parallels H-Sphere first searches for a template in the
<design>/replacements/<plan> directory which has the same structure as the
<design> directory. If the template is not found, it starts to look for it in the <design>
directory. Read more about template lookup sequence (on page 11).
Template Directory Structure
~cpanel/shiva/shiva-templates/<design> - template directory for one of the
1. Parallels H-Sphere searches for a template of a particular design first in
the custom template directory in replacements, then, if the template is
not found there, it proceeds to the corresponding default template
directory:
2. If the template is not found in replacements, Parallels H-Sphere
searches in the design directory, first in among the custom templates,
then amonng the corresponding default templates:
This document will guide you through the generic step-by-step instruction on
customizing templates. This implies you are already familiar with the concept of
templates (on page 11) in Parallels H-Sphere.
It is possible to create and install packages of templates. Read more about template
packages in Developer Guide.
Pre-Cautions
1. Advanced customization may produce unpredictable results after
updating Parallels H-Sphere, since updates affect the template structure
and the page generation.
2. Advanced customization performed by Parallels H-Sphere customers is
done at their own risk and is not supported by the PSoft team.
3. Template customization affects ALL Parallels H-Sphere accounts, regardless of their
plans!
In terms of Parallels H-Sphere customization, only two types of accounts are
customized, regardless of plans: admin accounts which are Parallels 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.
Pre-Requisites
Before you do any customization, log into CP server under root as the cpanel (on
page 136) user.
Make sure templates have the cpanel:cpanel ownership. Mind, however, that
images, CSS and JavaScript files and directories have cpanel:httpdcp
ownership and you must not change their ownership to cpanel:cpanel. Parallels
H-Sphere updater checks and automatically sets correct ownership and
permissions on respective default and custom files and directories (this does not
refer to Parallels H-Sphere packages).
Note: We don't recommend changing manually the ownership and permissions of
default templates!
The make directive which is performed to rebuild *.html templates should be run
ONLY under cpanel.
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.
18 Template Customization
Step-By-Step Template Customization Procedure
1. On the CP server, log in as the cpanel (on page 136) user.
2. In the ~cpanel/shiva/ directory, create the custom template
directory custom/templates/ if it doesn't exist.
3. In the ~cpanel/shiva/psoft_config/hsphere.properties file,
find the USER_TEMPLATE_PATH parameter. Here, the full to your
custom template directory must be specified:
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.
4. Copy the templates you would like to customize into
shiva/custom/templates/, preserving their file paths relative to this
directory.
For instance, if you are going to customize the ~cpanel/shiva/shiva-templates/path_to_template/FILE,
copy it to ~cpanel/shiva/custom/templates/path_to_template/FILE.
The original configuration can be restored without server restart by simply deleting
your custom files from the custom template 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!
5. Modify the templates you have copied to the
~cpanel/shiva/custom/templates/ directory.
The following documents will be helpful:
Interface Controls and Colors (on page 41)
Skin and Icon Set Customization (on page 32)
Edit Interface Texts (on page 60)
Important:
1. We don't recommend inserting the interface text directly into the templates. Use
text labels defined in language bundles (on page 58) to ensure multilingual
support.
2. Parallels H-Sphere uses the Unicode (UTF-8) charset for all languages.
Therefore, text directly inserted into templates (i.e., not by means of text labels
defined in language bundles) must be in the UTF-8 encoding.
6. Restart Parallels H-Sphere (on page 136).
Template Customization 19
Compiling Templates With Client-Side
Form Validation
There are two types of templates that are responsible for generating Control Panel web
content:
*.html.in templates with client-side form validation that require compilation
before modifications in them would take effect, and
*.html templates that provide server-side form validation and don't need to be
recompiled after their modification.
This document provides step-by-step instructions on how to compile control panel
templates with the client-side validation of HTML form input fields.
To compile templates with client-side form validation:
1. Log into the control panel server as the cpanel (on page 136)
user.
To implement customization correctly, all template files and directories should have
the cpanel:cpanel ownership.
2. Check settings in
~cpanel/shiva/psoft_config/hsphere.properties:
1. Check the TEMPLATE_PATH parameter. It should point to the default template
directory. Default setting is:
3. Check the JS (JavaScripts) and IMAGES parameters:
JS =
IMAGES =
By default, JS and IMAGES are left blank. It means that javascripts and images are
placed inside each design directory (on page 11). You don't need to change these
parameters if you have default system settings.
3. Go to the default templates directory (DocumentRoot,
~cpanel/shiva/shiva-templates by default). Check parameters in
the configure file:
SHIVA_ROOT - Parallels H-Sphere Control Panel's root directory
(~cpanel/shiva by default)
HSPHERE_PROPERTIES - path to the hsphere.properties file.
20 Template Customization
4. Run ./configure in the templates directory. This will create
Makefile'sfor all of designs.
Warning: Running ./configure clean would remove ALL the compiled
templates in the nested directories and delete ALLMakefile's created by the
previous configure execution! After that, your control panel interface would not show
up correctly!
5. To compile all modified templates, run make or make all in your
default templates directory (gmake for FreeBSD). If you need just to
modify one template, run make from the directory where this template is
located.
Warning: Running the make clean command from a certain template directory
would clear all the compiled template files (*.html) in the nested directories! After
that, your control panel interface would not show up correctly!
Customizing Skeleton Templates
When an end-user adds a new domain, the system generates initial web site based on
skeleton templates. Skeleton templates are written in HTML. Unlike FreeMarker
templates (on page 10), Skeleton templates are customized right in the directory they
are located.
To modify Skeleton templates:
1. Log in as the cpanel (on page 136) user.
2. Enter the Skeleton template directory:
cd /hsphere/shared/skel
3. Customize the template files directly according to your needs.
Please only pay attention that with each automatic upgrade of web boxes, all the
customizations get lost. So, after performing the customization, backup the templates
into a safe location to get them back working after performing box upgrades.
Adding Context Help Pages
Context help (or online help) is implemented through special templates, each with a
topic header and a body. Context help files are located in the
/hsphere/local/home/cpanel/shiva/shiva-
templates/common/online_help directory. They have .oh extension and contain
text in HTML format. Context help may be implemented in different languages (on page
68).
To add a new context help page to Parallels H-Sphere interface:
Template Customization 21
1. Log into the CP server as the cpanel (on page 136) user.
2. Create an online help file and put it anywhere inside
~cpanel/shiva/shiva-templates/common/online_help/. You
can create new subdirectories for your files where necessary.
3. In ~cpanel/shiva/psoft/hsphere/online_help.xml, add an id/file correspondence, where file is the path and filename of the context
help file, and id is the string that will be used in the template.
4. Find the template where the context help icon will be added. The
easiest way to find the name of the template is to view html page source
code. The templates you need are located in ~cpanel/shiva/shiva-
templates/common/control/. More about templates (on page 11)
5. Add context help function call to the template. The function call has the
following syntax:
<call draw_help("HELP_ID","LABEL")>
where HELP_ID is the id of the file specified in
~cpanel/shiva/psoft/hsphere/online_help.xml, and LABEL is the
description used as the title in the html link.
If the second parameter is left empty, the default text ("Click to get help") is
used. For example:
7. If the edited template is in *.html.in format, run make in this
template's directory.
8. Restart Parallels H-Sphere (on page 136).
22 Template Customization
System E-Mail Templates
Template
Filename
Notification Sent
Welcome
Letter
new_account.txt
to customer on
account activation
Welcome
Letter for
Moderated
Accounts
new_account_moderated.tx
t
to customer on
moderated check
account registration
(accounts waiting
activation)
Welcome
Letter For
Moderated
Account
with CC
new_account_moderated_cc
.txt
to customer on
moderated credit card
registration
Welcome
Letter For
Moderated
Trial
Account
trial_moderated.txt
to customer on
moderated trial
account registration
System e-mail notifications are messages Parallels H-Sphere automatically sends to
customers.
It is possible to edit system emails in the admin CP interface, in the
Settings/Notifications/E-Mail Notifications menu (see Parallels H-Sphere Administrator
Guide for details). Both default messages and messages in each interface language
can be customized there. Custom modifications are stored in the Parallels H-Sphere
database and do not affect the system email templates. On the contrary, default
settings can be restored from the templates.
This document explains where to find the default system email templates and how to
customize them.
Note: Support info and checks info is modified in the Settings -> Look and Feel -> Misc.Text
menu by filling in the Customer Support Info and Checks Info forms.
Important: It is strongly recommended not to touch the default system email templates;
instead, you should edit notifications in the administrator's Control Panel to be able to
restore default texts from the templates.
Here is the list of default templates for system email messages (located in the
~cpanel/shiva/shiva-templates/common/mail/ directory) that can be
customized via CP interface:
Template Customization 23
Trial
Registratio
n
trial_account.txt
to customer on
account trial period
expiration
Invoice
invoice.txt
to customer: - on each
paid operation
- at the beginning of
the next billing period
- on switching to
another billing period
Money
Back
money_back.txt
to admin when a user
chooses to cancel
hosting and wants
his/her money back
Overlimit
Notification
overlimit.txt
to customers when
they reach traffic or
disk usage limit
Account
Suspended
Notification
suspended_account.txt
to customers when
their accounts get
suspended
Account
Resumed
Notification
resumed_account.txt
to customers when
their accounts get
suspended
Accounting
Error letter
accounting_error.txt
to admin on
accounting error
Lost
Password
forgot_passwd.txt
to customers after
they enter their email
address on the "forgot
your password" page
Failed
Signup
Notification
you_have_files_signups.t
xt
to admin when
customer signup fails
Domain
Transfer
Message
tranfer_domain.txt
to customers
explaining how to
transfer an external
domain
Internal
Ticket
ticket_internal.txt
to admin in case of
internal problems
Shell
Access
Notificaton
ssh_notification.txt
to the customer when
Shell Access is
granted or refused
(disabled)
24 Template Customization
Welcome
Letter (Tax
Exemption)
new_account_tax_exemptio
n.txt
to new customers
awaiting approval of
their Tax Exemption
Codes
to customers on failing
to verify tax exemption
data
Below is the list of templates for standard texts sent as mass mail. Messages in these
Template
Filename
Notification Sent
Welcome Letter
welcome.txt
optionally from mass
mail
User login and
password
login_psw.txt
optionally from mass
mail
User balance
balance.txt
optionally from mass
mail
templates cannot be customized via Parallels H-Sphere interface:
Template Customization 25
Customizing User Signup
This document explains how to modify standard user signup (order) forms or replace
them with custom forms.
Before you begin signup customization, please note the following:
The default signup forms contain validation scripts. It is recommended that your
custom signup forms also provide a client side validation mechanism (on page 19).
When Parallels H-Sphere server-side validation rejects user data, the user is
redirected to the error page generated based on the template
~cpanel/shiva/shiva-templates/common/signup/end.html, which has
the look and feel of the standard Parallels H-Sphere interface and links to the
STANDARD Parallels H-Sphere signup forms. Normally, you would want to
customize this template to ensure that:
it has the look and feel of your custom signup forms,
it gives a way to go back to the signup forms, then modify and re-submit the
signup data.
The template has been written in FreeMarker, and in order to make changes to its
code, please become familiar with the FreeMarker technology, the documentation
available at http://freemarker.org. The way you customize the page will totally
depend on how you organize your signup forms.
Custom signup fields must match those in the default signup. If more fields are
added in newer versions, you will need to update your custom forms.
Your signup script has to put the collected data into the html fields below and submit
them to the following URL:
Some signup texts can be customized through the control panel from Look And Feel -> Signup Texts. If you have customized texts through the control panel, they will override
the texts in your custom signup forms, so you may need to remove them.
Signup fields:
Basic (service fields required for signup)
26 Template Customization
User Contact Info
Field name
Possible Values
Explanation
_eul_accept
"1"
Accept terms of End User License
Agreement
_mod
"signup" - transfer domain,
"opensrs" - domain
registration,
"nodomain" - stopgap
domain,
"3ldomain" - third level
domain,
"service" - service domain,
"empty" - signup without
domain
Signup mode
action
"signup"
Service parameter
plan_id
numeric
Number of the plan for signup
signup
"yes"
Service parameter
login
alphanumeric
user login
password
alphanumeric
user password
password2
alphanumeric
Confirm user password
template_name
"submit/signup/end.sbm"
("submit/signup/end_osrs.sbm" for Domain
registration)
The so-called submit template
located in the
~cpanel/shiva/shiva-
templates/common directory
and used to perform server-side
form validation.
admin_signup
"yes" - if we sign user up from
the admin panel
Service parameter
Field name
Possible Values
Explanation
_ci_first_name
alphanumeric
User's first name
_ci_last_name
alphanumeric
User's last name
_ci_address1
alphanumeric
User's address 1
_ci_address2
alphanumeric
User's address 2
Billing Info (not used for trial registration)
Credit Cards
Billing Period
Domains
Domain Registration
Domain Regisration Contact Info
Basic (service fields required for signup)
User Contact Info
Template Customization 27
_ci_city
alphanumeric
User's city of residence
_ci_company
alphanumeric
User's company name
_ci_country
alphanumeric
User's country code
_ci_email
alphanumeric
User's contact e-mail address
_ci_phone
numeric
User's phone number
_ci_postal_code
numeric
User's zip code
_ci_state
e.g.: "NY"; "NA"
for non US or
Canada
residents.
User's state code. In the custom form for
non US or Canada residents, you should
add this field as hidden.
_ci_state2
alphanumeric
User's state or province for non US and
Canada residents. Should be present in the
custom form only in case
_ci_state='NA'.
_promo_code
alphanumeric
PROMO code for subsidized plan. Contains
2-20 chars and starts from the letter.
Billing Info (not used for trial registration)
Field name
Possible Values
Explanation
_bi_first_nam
e
alphanumeric
User's first name
_bi_last_name
alphanumeric
User's last name
_bi_address1
alphanumeric
User's address 1
_bi_address2
alphanumeric
User's address 2
_bi_city
alphanumeric
User's city of residence
_bi_company
alphanumeric
User's company name
_bi_country
alphanumeric
User's country code
_bi_email
alphanumeric
User's contact e-mail address
_bi_phone
numeric
User's phone number
_bi_postal_co
de
numeric
User's zip code
_bi_state
e.g.: "NY"; "NA" for non
US or Canada residents.
User's state code. In the custom form
for non US or Canada residents, you
should add this field as hidden.
_bi_state2
alphanumeric
User's state or province for non US or
Canada residents. Should be present
in the custom form only in case
_bi_state='NA'.
28 Template Customization
_bi_type
"CC" - credit card,
"Check" - check or
bank transfer,
"PayPal" - PayPal,
"2CheckOut" -
2CheckOut,
"TRIAL"
Payment type
Credit Cards
Field name
Possible Values
Explanation
_bi_cc_name
alphanumeric
Credit card name
_bi_cc_number
numeric
Credit Card number
_bi_cc_type
strings available
in the Merchant
Gateway
Manager: "VISA",
"MC", etc.
Credit Card type
_bi_cc_exp_mont
h
two digits
the month of Credit Card expiry date
_bi_cc_exp_year
four digits
the year of Credit Card expiry date
Field name
Possible Values
Explanation
_bi_cc_issues_n
o
alphanumeric
Issue number
_bi_cc_start_mo
nth
two digits
Card Start Month
_bi_cc_start_ye
ar
four digits
Card Start Year
Below are the fields for Solo/Switch debit cards used in some countries:
Template Customization 29
Billing Period
Field name
Possible Values
Explanation
_bp
0 or a positive
integer
Sequence number of the billing period in the
list of billing periods for the selected plan.
To see the list of the billing periods, go to
your control panel, click the Settings link for
this plan and scroll down to the Billing
configuration section.
Field name
Possible Values
Explanation
type_domai
n
"transfer_new_misc_domain" - transfer
domain without registrar changes
"domain_transfer" - transfer domain with
registrar changes
"without_domain" - stopgap domain
"3ldomain" - third level domain
"service_domain" - service domain
"empty_domain" - signup without domain
"new_opensrs_domain" - register new
domain
Type of new domain
_mod
"signup" - transfer domain without registrar
changes
"dtransfer" - transfer domain with registrar
changes. It accepts the same fields as
OpenSRS registration except the period
field and extra contact/billing info for
domain registration.
"nodomain" - stopgap domain
"3ldomain" - third level domain
"service" - service domain
"empty" - signup without domain
"opensrs" - register new domain
Domain registration
mode.
domain_nam
e
alphanumeric
Domain name; may be
omitted if
type_domain="emp
ty_domain"
Field name
Possible Values
Explanation
period
numeric
Registrar's periods (years)
_srs_owner_first_na
me
alphanumeric
User's first name
_srs_owner_last_nam
e
alphanumeric
User's last name
_srs_owner_address1
alphanumeric
User's address 1
Domains
Domain Registration
30 Template Customization
_srs_owner_address2
alphanumeric
User's address 2
_srs_owner_city
alphanumeric
User's city of residence
_srs_owner_org_name
alphanumeric
User's company name
_srs_owner_country
alphanumeric
User's country code
_srs_owner_email
alphanumeric
User's contact e-mail address
_srs_owner_phone
numeric
User's phone number
_srs_owner_postal_c
ode
numeric
User's zip code
_srs_owner_state
e.g.: "NY"; "NA" for
non US or Canada
residents.
User's state code. In the custom
form for non US or Canada
residents, you should add this field
as hidden.
_srs_owner_state2
alphanumeric
User's state or province for non US
or Canada residents. Should be
present in the custom form only in
case _srs_owner_state='NA'.
Domain Registration Contact Info
Field name
Possible Values
Explanation
_srs_billing_first_name
alphanumeric
User's first name
_srs_billing_last_name
alphanumeric
User's last name
_srs_billing_address1
alphanumeric
User's address 1
_srs_billing_address2
alphanumeric
User's address 2
_srs_billing_city
alphanumeric
User's city of residence
_srs_billing_org_name
alphanumeric
User's company name
_srs_billing_country
alphanumeric
User's country code
_srs_billing_email
alphanumeric
User's contact e-mail
address
_srs_billing_phone
numeric
User's phone number
_srs_billing_postal_code
numeric
User's zip code
_srs_billing_state
e.g.: "NY"; "NA" for
non US or Canada
residents.
User's state code. In the
custom form for non US or
Canada residents, you
should add this field as
hidden.
_srs_billing_state2
alphanumeric
User's state or province for
non US or Canada
residents. Should be present
in the custom form only in
case
_srs_billing_state='N
A'.
This chapter explains how to customize graphic elements of the Parallels H-Sphere
In this chapter:
Skin And Icon Set Customization ...................................................................... 32
Design XML Configuration ................................................................................. 35
Interface Controls And Colors in Templates ...................................................... 41
Parallels H-Sphere interface design has a broader meaning than just configuration of
certain color schemes and the corresponding icon sets, what is called the skin. It also
determines the set of skins available for this design, specifies the sets of icons in the
Quick Access page and enables to override the standard settings with the custom ones.
To provide multiple design support, Parallels H-Sphere uses the
design_config.xml file, which can be found in the
/hsphere/local/home/cpanel/shiva/psoft/hsphere/ directory. Its structure
is explained in the Design XML Configuration (on page 35) guide.
The current document shows you how to customize this file to add your own designs,
color schemes, colors and images. For this, you need to:
1. customize design_config.xml
2. implement custom design templates
Design XML Customization
A designer should have access to the Parallels H-Sphere server as the cpanel user.
To implement customization correctly, all template files and directories should have
cpanel:cpanel ownership. In version 2.5 and up templates, images, CSS and
JavaScript files and directories must have cpanel:httpdcp ownership.
Important: We don't recommend you to modify the default
~cpanel/shiva/psoft/hsphere/design_config.xml file. These modifications
will be lost with the next Parallels H-Sphere updates.
There are the following ways of customizing design XML configuration:
With packages
You can customize design_config.xml by means of packages. In this case, within
a package you create custom XML file that will be merged with default XML
configuration (on page 71).
Merging custom XML configuration
Instead of creating a package, create a custom XML configuration file to be merged
with the default XML configuration (on page 71 ) and a custom package XML if installed.
Overrriding default XML configuration with custom XML configuration
1. You create the custom design configuration file and perform
modifications there:
Design Customization 33
2. Login to the CP server as the cpanel (on page 136) user under root.
3. Copy the standard design_config.xml file to a certain custom
Custom design templates are created in the ~cpanel/shiva/custom/templates
custom template directory. In order to implement these custom designs, the symlinks to
them should be put into the Apache DocumentRoot directory which is set by default to
the ~cpanel/shiva/shiva-templates standard templates directory.
However, on the subsequent Parallels H-Sphere update all symlinks in
~cpanel/shiva/shiva-templates would be lost, and custom designs would not
be displayed correctly.
To avoid this, we suggest to use another directory as DocumentRoot and to create
there the symlinks to ALL design directories, for both custom designs and the Parallels
H-Sphere built-in designs.
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.
1. Log into the CP server as the cpanel (on page 136) user.
2. Create the ~cpanel/shiva/web directory.
3. Create the symlinks to the design directories using the ln -s
Here, the counter, guestbook, masonry, and poll directories are Parallels
SiteStudio-related directories; YourDesign1 and YourDesign2 are custom
design directories.
4. Make the ~cpanel/shiva/web directory in the DocumentRoot
directory. To do this, in the ~cpanel/apache/etc/httpd.conf
Apache configuration file change the DocumentRoot global definition
line:
Then, delete all other instances of the DocumentRoot definition (for virtual hosts) in this
file. Also, delete all DocumentRoot definitions in all configuration files located in the
~cpanel/apache/etc/sites directory.
4. Logout from cpanel back to root and restart Parallels H-Sphere (on page 136).
Design Customization 35
Design XML Configuration
Parallels H-Sphere design configuration is represented in the design_config.xml
file, which can be found by default in the
/hsphere/local/home/cpanel/shiva/psoft/hsphere/ directory. You can
customize (on page 32) this XML configuration to add your own designs, color
schemes, colors and images.
This document explains all important parts of the design configuration file, including:
Icons
Skill Icon Groups
Icon Image Sets
Common Images
Color Types
Designs (Skins)
Important:
1) Do not make changes into the default XML configuration file! Instead, follow
instructions on design.xml customization (on page 32).
2) Changing design XML configuration implies proper knowledge of XML. Errors in XML
structure may badly damage your Control Panel interface.
Icons
By icon we mean an Parallels H-Sphere control that provides quick access to a certain
functional page of the control panel. All Parallels H-Sphere icons are displayed only on
the Quick Access page, which is based on the quick/quick_view.html template.
icon
An icon description includes the following:
id - the mnemonic system name of the icon
url_param - typically, the name of the base template for the functional page this icon
links to. Multiple url parameters are separated with the & delimiter
rtype - the list of Parallels H-Sphere resource types whose availability determines
whether the icon will be drawn. It may include simple resource types separated by
semicolons and commas in the following way:
res1 - simple resource type, icon will appear if the resource is available;
res1, res2, res3 - group of resources where all of them must be available
to show an icon (operation 'AND');
res1; res2; res3 - icon will be shown if any of the resources is available
res1,res2; res3,res4; res5,res6 - combination of groups where an
icon will be shown if any of the groups: res1,res2 or res3,res4 or res5,res6 includes both available resources. If translated to C or Java, this
would mean (res1 & res2) || (res3 & res4) || (res5 & res6)
platform - operating system (unix|win2k) on which plans using this icon are
based. If platform=unix or platform=win2k, this means that the icon is
displayed for Unix-based or Windows-based plans, respectively. If the platform
attribute is left empty, the icon is available for all plans.
label - mnemonic id of the caption under the icon image. It must be defined in the
hsphere_lang.properties file
tip - mnemonic id of the HTML tooltip of the icon. It must be defined in the
hsphere_lang.properties file
help - reserved for future use.
One icon can have many visual representations. This means that it will have a different
look depending on which icon image set was selected by the user. You can specify
which icon image sets will be available for each individual design, for example:
admin for admin accounts
user for user accounts.
Skill set ids are of the following types:
standard for the common (left menu) interface.
advanced for the 'no menu' interface.
simplified skill set may be chosen for any of the two types of accounts.
Icon groups are defined within the skill_set element structure. The icon group id
attribute corresponds to menu groups, such as Info, FTP, mail, etc., and is a mnemonic
identifier of the icon group (mail, admin_mail, and the like).
icon_group construction enlists the set of icons which are displayed in this icon
group. Each icon is defined in the icons construction described above in the previous
section.
Icon Image Sets
By icon image set we mean the set of icons corresponding to a certain Parallels HSphere color scheme:
base_dir attribute defines the directory where the Parallels H-Sphere images, both
standard and custom, are to be stored. Typically, it is the IMAGES directory in the
Apache document root directory (usually, ~cpanel/shiva/shiva-templates).
38 Design Customization
Note: The base image directory is actually relative to the alternative directory for
images which is located in the document root. This directory is set in the IMAGES
variable in the hsphere.properties file. If it is not set there, base_dir
contains the path relative to the document root.
icon_image_set
The icon_image_set element sets the list of images corresponding to a color
scheme.
Attributes:
id attribute refers to mnemonic name of the color scheme. It is default for the default
color scheme; cocoa, bubble and some other schemes go with Parallels H-Sphere
installation, while others may be created manually.
dir is the path relative to the base_dir directory. If it is empty, images are located in
the base images directory.
preview_image
The preview_image tag refers to the preview image appeared in the Parallels HSphere Look and Feel interface when choosing the available design. The following
attributes are determined for the preview image:
file - filename and path to the preview image relative to the document root directory.
width, height - image width and height.
image - image description tag.
Please keep in mind that the image should be set for EACH color scheme. In order to
add a new image, first, add the image definition to the icons tag, and then add image
elements with the same id attribute to EACH icon_image_set element.
The following attributes should be set:
id attribute value refers to the icon described in the icons section.
file is the image filename with the path relative to the icon image set subdirectory of
the image set basic directory.
For example, if base_dir="/IMAGES" and dir="wooden", then images for
wooden scheme will be located in /IMAGES/wooden directory. However, if
dir="", then, to do so that Parallels H-Sphere would find, let say, a GIF image,
you should set the file attribute as file="wooden/name_of_the_file.gif".
width, height - image width and height. Unless these parameters are not changed,
the user custom image would be displayed by Parallels H-Sphere with this width
and height, regardless of the image size parameters.
Common Images
Common images are the set of images that have the same look in all designs, such as,
arrows, bullets, home icon, etc.
The common_images element structure is as follows:
The base_dir attribute is defined in the same way as for the icon image sets.
The image id attribute is an image mnemonic name used in templates.
Color Types
Color types comprise all possible interface entities for which colors are set: basic text,
background, header, menu, error messages, etc.
The following attributes are present in the color_type tag:
id is a mnemonic color type identifier later used in designs description;
label is a mnemonic id to the caption under which this color type is configured in the
CP interface.
Designs
Design, or skin, is a GUI representation including certain icon image sets and color
schemes. The following designs are included into the default Parallels H-Sphere
installation:
common is the Left Menu design. All basic templates are made for this design
scheme.
nomenu (No Menu) is the design with no left menu. It is turned on as the default user
design after the Parallels H-Sphere installation.
text-based (Text-Based) is the alternative look of the nomenu design where only
captions with no icons are provided in the Quick Access menu page.
xcp, xcpl - XPressia and XPressia Lite are designs with dropdown menus.
reloaded (XP Reloaded) is a left-menu design, default in Parallels H-Sphere 3.1 and
up.
design
Attributes of the design element:
id is a design mnemonic identifier: nomenu, common, text-based, xcp, xcpl,
reloaded.
label is a mnemonic id to the design name in the CP interface.
template_dir is a directory relative to the document root directory where where
template files for this design are located.
default_color_scheme is the default color scheme identifier (see below, the
color_scheme tag description).
preview_image
The preview_image tag defines the design preview image settings. The structure is
the same as for the icon image sets.
40 Design Customization
colors
The colors element defines all available colors for this design. They are taken by
default for every color scheme. Individual color settings for each color scheme could be
defined in the corresponding color_scheme constructions (see description below).
Color id attribute refers to the color type identifier (see Color types).
base_imagesbase_images is the set of images that look the same for all color schemes in this
design. The base_images tag structure is the same as for the common images.
image_sets
The image_sets element contains the settings for each image set enabled for this
design. base_dir attribute points to the images directory (usually, IMAGES). The
element includes the following tags:
the set_images element contains the list of images in a standard image
description which are taken by default for this design.
the image_set tag contains image definitions for a color scheme to override the
set_images default definitions. Here you may set an alternative directory where
images for this color scheme will be searched, or modify settings so that an image
will be taken from a file different from the default image file. image_set may contain
image tags for images with alternative settings (for example, if the image file name
is different from the default one).
Attributes:
id - identifier for a color scheme (for example, default or cocoa);
label - color scheme label;
dir - alternative image directory relative to the base_dir directory; if it is empty the
image search would be performed in the base_dir directory (usually, IMAGES).
For example, if we need to change the banner.jpg image to banner1.jpg in
the default color scheme so that this image would be searched in the base
directory, the image tag should be inserted into the image_set construction in the
allowed_skill_icon_sets
The allowed_skill_icon_sets tags are used to determine a skill icon set for user
and admin accounts (see Skill icon groups):
<allowed_skill_icon_sets account_type="user">
<set id="standard"/>
</allowed_skill_icon_sets>
allowed_icon_image_sets
Design Customization 41
The allowed_icon_image_sets tags determine icon image sets that would be
available for each account type (see Icon sets):
<allowed_icon_image_sets account_type="admin">
<set id="default"/>
</allowed_icon_image_sets>
color_scheme
color_scheme sets page colors, image sets and icon image sets in this design.
Attributes:
id - color scheme identifier (for example, blue_haze or default);
label - color scheme label defined in hsphere.properties;
image_set - image set identifier (for example, blue_haze or default);
icon_image_set - icon image set identifier (for example, blue_haze or default).
The color_scheme element may include the color tags to set colors for this color
scheme. If these colors are not set here, default colors would be taken from the
colors tag definition for this design.
Example:
<color_scheme id="marsh" image_set="marsh"
icon_image_set="marsh" label="imagesets.marsh">
<color id="logo_bgcolor" value="#C9D1CA"/>
. . .
</color_scheme>
Interface Controls And Colors in
Templates
This document introduces basic Freemarker functions related to interface controls
(images, buttons, interface texts, etc.) and interface colors in Parallels H-Sphere
templates.
To generate HTML representation of Parallels H-Sphere control panel, we use Java
and Java-based FreeMarker package. Parallels H-Sphere templates contain calls to
FreeMarker functions, variables, and substitutions. Due to the added support of multiple
designs in user's control panel, some of the functions needed to be changed. If you are
using templates that have been developed for Parallels H-Sphere earlier than 2.1, you
need to bring parameters in all FreeMarker function calls in line with the following list:
Designs in Parallels H-Sphere have customizable color schemes. To display interface
elements, we use colors, each having its own id_handle. For example, bgcolor is the
id for the background of the HTML page other than the menu and the header. Its color
can be set in the Look And Feel menu.
To get the RGB value of the color by color_id, the following syntax is used:
${design.color("color_id")}
Note: the color_id value must be replaced with an approprate handle and must be
enclosed in double quotation marks.
To provide multiple design support, Parallels H-Sphere uses the
design_config.xml file, which can be found in the
/hsphere/local/home/cpanel/shiva/psoft/hsphere/ directory. Its structure
is explained in the Design XML Configuration (on page 35) guide.
The current document provides an example of how to customize this file to add your
own custom icons. For this, you need to:
1. Create custom design_config file in custom location that will be merged
with the default XML configuration file (on page 71). Your
design_config.xml should include only differences in relation to the
original Parallels H-Sphere one.
44 Design Customization
2. As Parallels H-Sphere supports several icon sets, create an icon for
each icon set and include information about this icon location into your
custom design_config.xml. To do this:
1. Declare the url and the image id that will be used for your icon:
<design_config>
<icons>
<icon id="custom_mail_icon"
url_param="template_name=email/custom_email.html"
rtype="" platform=""
label="quick.your_custom_mail_web_app"
tip="quick.your_custom_mail_web_app" help=""/>
</icons>
</design_config>
Where:
The email/custom_email.html is a custom template from which a
customer will be redirected to your url.
The quick.your_custom_mail_web_app label should be described in the
customized hsphere_lang.properties file.
2. Specify the place where the icon will be displayed. It can be included into the
Quick Access page for the Admin Account or end user Quick Access page:
3. Create images for each icon set and place them into the corresponding
directories. The base directory for your images is
/hsphere/local/home/cpanel/shiva/custom/images.
46 Design Customization
Control Panel menu customization affects the following elements:
In this chapter:
Menu XML Customization ................................................................................. 48
Changing Menu Structure ................................................................................. 48
Menu Design Customization ............................................................................. 54
C H A P T E R 5
Menu Customization
menu structure (on page 48): by customizing the menu XML configuration file, you can
restructure menu, add/delete menu groups and items, configure menu layouts for
individual plans, add external links to menu.
menu texts (on page 60): texts for menu item labels are stored in menu language
bundles.
menu design (on page 54): you can change the menu appearance: color, bullets, etc.
48 Menu Customization
Menu XML Customization
The Control Panel menu structure (on page 48) is represented in an XML file. Its
default location is set in ~cpanel/shiva/psoft_config/hsphere.properties
by the MENU_CONFIG parameter:
You should not make changes in the default menu.xml file, because these changes
will be lost with the next Parallels H-Sphere upgrade. Instead, you create custom XML
files that either override or merge changes with default configuration.
Below are the alternative ways to customize menu.xml.
With Packages
You create a custom menu.xml file within an Parallels H-Sphere package (on page
112). After the package is installed, this custom XML configuration will be merged
with default XML configuration.
Merging custom XML configuration
If you need minor modifications in menu configuration, you don't need to rebuild a
package. Instead, you create a custom XML configuration (on page 48) file to be
merged with the default XML configuration and a custom package XML if installed.
In this case, you avoid changing the default MENU_CONFIG property in
hsphere.properties and use the CUSTOM_MENU_CONFIG parameter to specify
your custom menu.xml location.
Changing Menu Structure
Parallels 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:
Texts for menu elements are set in language bundles:
Menu Customization 49
MENU_BUNDLE = psoft.hsphere.lang.menu
You should not make changes into the default
~cpanel/shiva/psoft/hsphere/menu.xml file! There are several ways how to
customize menu XML data correctly, and they are explained in a separate Menu XML
Customization (on page 48) document.
Here in the text we refer to menu.xml assuming it is correctly customized according to
menu.xml customization rules.
XML Structure
menu.xml consists of the following blocks going one after another:
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).
The menudef tags contain sets of menu groups (on page 48) and separate items in
order of their appearance in Parallels 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 Plans menu, the
Settings icon for the plan, in admin CP). Please refer to the Plan Settings document in
the Parallels H-Sphere Administrator Guide.
These are default menu identifiers for the standard Parallels 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 - Mail Only plan;
vps - VPS plan.
To add your custom menu and assign it to a specific plan:
1. According to menu.xml customization rules (on page 48), add the new
menudef structure for the plan and fill it with menu groups and items
as shown in the above example:
52 Menu Customization
<menudef id="custom_menuId">
...
</menudef>
2. In the admin control panel, in the plan's Settings form, set the menuId
custom value to custom_menuId (read the Plan Settings document in the
Parallels H-Sphere Administrator 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 Parallels H-Sphere according to its template lookup
sequence (on page 11).
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 (on page 48) and the template (on page 10) 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.
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. Parallels HSphere will search for it in
6. Refresh browser to see the changes. It is better to log out and in again.
54 Menu Customization
Menu Design Customization
This document explains how to change the appearance of the navigation menu in the
Parallels H-Sphere control panel. You are expected to be familiar with the FreeMarker
technology and with Parallels H-Sphere templates (on page 11).
The template to be customized is ~cpanel/shiva/shiva-templates/common/menu.fn. The instruction below is the regular way of template
customization. This customization can be also performed by means of Parallels HSphere packages (on page 112).
1. Login as the cpanel (on page 136) user from root.
2. Create the ~cpanel/shiva/custom directory if it doesn't exist yet.
3. Inside the custom/ directory, create the following directories if they
aren't there:
templates/
images/
bundles/
Note: If the images/ directory is created, there must be a symlink to this directory
from the Apache document root (which is the default template directory
~cpanel/shiva/shiva-templates); if not, users should place their images into
the IMAGES directory.
4. Put your images into the images/ directory and your interface text files
(on page 60) (bundles) into the bundles/ directory.
5. In the templates/ directory, create the common/ directory if it doesn't
exist and copy the menu.fn file from the shiva-templates/common/
directory into that directory.
6. Make changes in the custom menu.fn. The following Freemarker
functions are used in menu.fn to draw the navigation 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.
1. The draw_menu function calls the other mentioned functions to draw the menu
and also defines the menu table as follows:
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/.
7. Open the ~cpanel/shiva/psoft_config/hsphere.properties
file, uncomment and correct (if necessary) the following lines:
See more about template customization (on page 10) and menu.xml customization
(on page 48).
Note: Don't initialize the variables you are not using!
8. Login as root and restart Parallels H-Sphere (on page 136).
This chapter explains how to add and modify texts in the Parallels H-Sphere Control
In this chapter:
Understanding Interface Text (Language) Bundles ............................................ 58
Interface Text Customization ............................................................................. 60
Language Bundle Compiler ............................................................................... 62
C H A P T E R 6
Interface Text Customization (Language
Bundles)
Panel interface.
58 Interface Text Customization (Language Bundles)
Understanding Interface Text (Language)
Bundles
Interface texts are defined in key=value sets collected in separate files for each language
and encoding, where key is a mnemonic identifier for the text, and value is the text itself
that is different for each language and encoding. Such files are called resource
bundles, or language bundles, or simply bundles. Parallels H-Sphere templates (on
page 11) include mnemonic identifiers and thus generate language-independent
dynamic content.
We distinguish the following types of language bundles:
Default bundles - bundles installed with Parallels H-Sphere and containing default
interface text values.
Custom bundles - bundles created by H-Sphere customers that adding new interface
texts or overriding the default ones.
Internal bundles - resulting bundles whereto default and custom bundles are merged
after language bundle compilation.
Default bundles
Default bundle location is set in
~cpanel/shiva/psoft_config/hsphere.properties:
TEMPLATE_BUNDLE=psoft.hsphere.lang.hsphere_lang
It means that default bundles are set in the following files of the
~cpanel/shiva/psoft/hsphere/lang/ directory.
hsphere_lang.properties - default English bundle.
Important: Starting with Parallels H-Sphere 3.0 RC 1, menu.properties and
messages.properties with navigation menu and system email notification texts
become deprecated, and all labels are collected in a single
hsphere_lang.properties for each language!
hsphere_lang_<language>_<COUNTRY>_<ENCODING>.properties - default language
bundles in other languages.
Please refer to the tables of canonical identifiers:
All source bundles, in whatever encoding they were created, are compiled into Unicode
(UTF-8). Therefore, in most cases <ENCODING> and <COUNTRY> identifiers may be
omitted in bundle names according to the following rules:
Interface Text Customization (Language Bundles) 59
Some languages have different character sets, e.g., standard Chinese and
simplified Chinese. In such case you cannot omit the encoding in bundle names.
Standard Chinese (Big5 encoding) bundle will look like:
hsphere_lang_zh_CN_Big5.properties
Simplified Chinese (EUC_CN encoding) bundle will be:
hsphere_lang_zh_CN_EUC_CN.properties
Some languages have variations in different countries, e.g., Portuguese (Portugal) and
Portuguese (Brazil). Then, you specify language and country for each case:
Portuguese (Portugal) bundle will be: hsphere_lang_pt_PT.properties
Portuguese (Brazil) bundle will be: hsphere_lang_pt_BR.properties
If you know for sure the language won't be used for other countries, you may omit
the country identifier.
For example, for Russian: hsphere_lang_ru.properties
Important: In any case, you must fully specify the correct language, country and
encoding identifiers in the LANG_LIST parameter in hsphere.properties or in
package properties file for Parallels H-Sphere packages (on page 112). In particular,
Parallels H-Sphere should know in what encoding the bundles were created to be able
to convert them to Unicode.
LANG_LIST contains definitions for the languages, delimited with whitespace, each
including the following components:
It means that custom bundles will be searched by Parallels H-Sphere in the
~cpanel/shiva/custom/bundles/ custom bundle directory.
60 Interface Text Customization (Language Bundles)
Custom bundle files are of the same filename format as in the default bundle directory.
To customize texts in the default bundles, files with the same names are created in the
custom bundle directory; they contain only labels to be added or to override the default
texts. New language bundles are also created in the custom bundle directory, and you
don't worry they'll be lost with the next updates.
See the following documents for customization instructions:
Interface Text Customization (on page 60)
Adding New Language To Parallels H-Sphere (on page 65)
It is also possible to build installable packages with custom bundles.
Internal Bundles
Default and custom bundles, along with bundles coming with Parallels H-Sphere
packages (on page 112), are compiled and merged into the so-called internal bundles
located in the ~cpanel/shiva/languages directory. It is there that Parallels HSphere takes bundles from.
Internal bundles location can be changed. You either set
INT_LANGBUNDLE_DIRECTORY to override the whole internal bundles directory
(~cpanel/languages/), or set INT_TEMPLATE_BUNDLE to override the respective
internal bundle.
Please refer to Compiling Language Bundles (on page 62) for details.
Bundle Lookup Sequence
Parallels H-Sphere searches for text labels in language bundles in the following order:
The search is made in the internal bundle directory (~cpanel/shiva/languages by
If no appropriate labels are found, the user will get a corresponding notification and a
possibility to send a trouble ticket.
Note: No different encodings for languages are present in internal bundles. Language
bundle compiler (on page 62) converts all regional data in default and custom language
bundles into UTF-8 format.
Interface Text Customization
Interface Text Customization (Language Bundles) 61
This document dwells on interface text customization methods. It implies you are
familiar with the concept of language bundles (on page 58).
These are the following alternative ways to customize texts:
With packages
Packages are helpful when you want to add a new language (on page 119) to Parallels
H-Sphere. In this case, you build new language bundles into a portable package easily
installed on other Parallels H- Sphere clusters (on page 132).
Compiling bundles
This scheme of customizing bundles enables you to apply modifications by merging
custom bundles with default bundles without building and installing packages. Read
more about compiling bundles (on page 62).
1. Log into CP server as cpanel (on page 136) user.
2. All affected files must have cpanel:cpanel ownership.
3. Create custom bundle directory, e.g.,
~cpanel/shiva/custom/bundles if it is not created yet.
5. Find the string you want to modify among default or custom bundles.
Create the corresponding custom bundle file if it doesn't exist to place
modified string there.
6. For example, you are going to change the label Shell Access to SSH
Access. It is set in the
es file. Create the file
~cpanel/shiva/custom/bundles/hsphere_lang.properties if
it isn't there already.
7. Copy the line with the identifier and the value you want to change into
the custom bundle and change its value the way you want. You should
use two single quotes (apostrophes) instead of one in labels containing
Freemarker variables in 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}
8. Run language bundle compiler (on page 62) to implement
customization:
java psoft.hsphere.LangBundlesCompiler
62 Interface Text Customization (Language Bundles)
Language Bundle Compiler
Language bundles (on page 58) - default, custom, and those installed with Parallels HSphere packages (on page 132) - are compiled and merged into the resulting internal bundles located in the internal bundle directory, ~cpanel/shiva/languages by
default. Instead of parsing default and custom bundles, Parallels H-Sphere takes
interface texts directly from this directory.
Merging language bundles is performed by a Java tool called language bundle compiler:
java psoft.hsphere.LangBundlesCompiler
Language bundle compiler works in the following way:
1. Bundle compiler parses the LANG_LIST parameters set in:
package properties files for all packages installed in Parallels H-Sphere: usually,
~cpanel/shiva/packages/PackageName/default.properties, where
PackageName is the name of the package without its version and build number;
the default ~cpanel/shiva/psoft_config/hsphere.properties file;
LANG_LIST contains definitions for the languages, delimited with whitespace,
each including the following components:
<language>_<COUNTRY>_<ENCODING>|<HTML_ENCODING>:misc.langs.<LABEL>la
ng
Here:
<language>, <COUNTRY>, and <ENCODING> are Java locale identifiers. For detailed
description and the tables of canonical identifiers, please refer to Understanding
Language Bundles) (on page 58). <ENCODING> is an encoding in which bundles
were created and saved,
<HTML_ENCODING> is the HTML-compliant encoding (this parameter is
deprecated since 2.4 and is not really used but must still be specified for the
sake of compatibility);
misc.langs.<LABEL>lang is a label for language name set in language bundles.
1. According to Java locale identifiers set in the LANG_LIST parameters,
bundle compiler looks for the bundles:
Default bundle location is set in hsphere.properties:
TEMPLATE_BUNDLE=psoft.hsphere.lang.hsphere_lang
See Introduction To Bundles (on page 58) for details.
2. Bundle compiler merges default, custom and package bundles with the
same filenames and save the resulting bundles in UTF-8 format into the
internal bundle directory~cpanel/shiva/languages/.
See Bundle Lookup Sequence (on page 58).
Notes:
If the ~cpanel/shiva/languages directory is not found, language bundle
compiler will be launched automatically and will create this directory with the
resulting bundles.
To override the default internal bundle directory, set the
INT_LANGBUNDLE_DIRECTORY parameter in hsphere.properties. Or, set
INT_TEMPLATE_BUNDLE to override the location of the respective internal bundles.
When a text label is set several times, e.g., in a package bundle and in a
custom/default bundle, package bundle takes precedence and override labels set in
custom or default bundles. The order of priority is: package bundles, custom
bundles, default bundles.
Depending on bundle encodings specified in the LANG_LIST parameters, bundle
compiler converts all regional language bundles into UTF-8. This is done due to the
Java restrictions in relation to regional encodings: Java can work only with ISO-
8859-1 and Unicode symbols.
Encoding conversion hints:
To convert regional symbols into Unicode, you can use the native2ascii JDK tool:
To convert a language bundle file into Unicode, you can also run make in the
~cpanel/shiva/psoft/hsphere/lang directory.
This chapter dwells on adding new Parallels H-Sphere localization.
In this chapter:
Adding New Languages To Parallels H-Sphere ................................................. 65
Changing Language of Context Help ................................................................. 68
Updating Translation of Parallels H-Sphere Interface ........................................ 69
C H A P T E R 7
Localization
Localization 65
Adding New Languages To Parallels HSphere
This document introduces methods of adding languages to Parallels H-Sphere
interface. We presume you are familiar with the concept of language bundles (on page
58).
Translating Language Bundles
Note: Parallels H-Sphere developers are not responsible for adding languages to
Parallels H-Sphere interface and updating translation (on page 69) of the default
English bundles. It is entirely up to Parallels H-Sphere owners. All language bundle
translations included into Parallels H-Sphere interface or localization packages are
kindly provided by our customers.
Default Parallels H-Sphere interface language is English. The default English interface
labels are located in the ~cpanel/shiva/psoft/hsphere/lang directory in the
hsphere_lang.properties file.
Note: Since H-Sphere 3.0, menu.properties and messages.properties with
menu labels and system e-mail notification texts are collected in a single
hsphere_lang.properties file.
You can also download default (English) language bundles from our site:
here, <language>, <COUNTRY>, and <ENCODING> are Java locale identifiers. For detailed
description and the tables of canonical identifiers, please refer to Understanding
Language Bundles (on page 58).
For example, for Portuguese (Brazil) it will be hsphere_lang_pt_BR.properties.
Please take into account the following considerations on translating the bundles:
Using quotes in the text: If a label or message has a Freemarker variable in curly
brackets, e.g. {0}, single quotes and apostrophes (') must be replaced with two
single quotes (''). For example, in English we write:
search.view_invoice = View Client's Invoice
but:
billing.del_no = No, I don''t want to delete {0}
Updating the translation: With upcoming versions of Parallels H-Sphere, default
English texts may be changed and new labels may be added, so you need to
update translation (on page 69) of your language bundles accordingly.
66 Localization
Encoding: Translation can be performed in any encoding. All language bundles are
converted into UTF-8 during their compilation (on page 65).
Right-to-left languages (Arabic, Hebrew, etc.): Parallels H-Sphere supports right to left
languages, such as Arabic or Hebrew. On this step, you need to specify whether the
target language is "left to right" or "right to left". In the file
hsphere_lang_<LANGUAGE_CODE>.properties, add the following lines:
# "text_direction" is a special label used to define
# which text direction is appropriate for the current
# language bundle.
# There are 2 possible values:
# - "ltr" means "Left to right";
# - "rtl" means "Right to left".
text_direction = ltr
Adding New Language Bundles Into Parallels H-Sphere
Parallels H-Sphere provides the following alternative ways of adding new languages:
With packages
Parallels H-Sphere provides an easy way to add languages by installing packages (on
page 132) (.hsp files) to the system. You may install ready-to-use and portable
packages to any of your Parallels H-Sphere control panels or build language packages
yourself (on page 119).
Compiling bundles
Instead of building a package, you create new language bundles in custom bundle
directory and run language bundle compiler (on page 62).
1. Login as the cpanel (on page 136) user. All affected files must have
cpanel:cpanel ownership.
2. Create custom bundle directory, e.g., ~/shiva/custom/bundles if it
is not created yet.
3. Set custom bundle location in
~cpanel/shiva/psoft_config/hsphere.properties (if it's not
set):
4. Create the files hsphere_lang.properties, menu.properties, and
messages.properties in the ~/shiva/custom/bundles directory if
they are not there. Even if you don't need to modify them, they are
important for correct bundle compilation:
cd ~cpanel/shiva/custom/bundles
touch hsphere_lang.properties
Localization 67
5. Copy the translated language bundles (on page 65) to
~cpanel/shiva/custom/bundles. For example, for Portuguese
(Brazil):
cd ~cpanel/shiva/custom/bundles
cp /some/location/hsphere_lang_pt_BR.properties .
6. To ensure that the new language is available to choose from the
interface, add a label for your language (ID and definition) into the
~cpanel/shiva/custom/bundles/hsphere_lang.properties
file, following the pattern:
misc.langs.<LABEL>lang = <LANGUAGE> (<COUNTRY>)
For example, for Portuguese (Brazil):
misc.langs.ptlang = Portugu\u00eas (Brasil)
Notes:
1. Default (English) language bundles are written in the ISO-8859-1 encoding.
Special Latin and non-Latin characters must be presented in Unicode. Use the
native2ascii JDK tool to convert these symbols into Unicode characters (\uxxxx
notations, like "\u00ea" instead of "e" in the example above).
2. If the original language name significantly differs from that in English, (especially
for non-Latin alphabets), we recommend adding its English transcription, e.g.:
misc.langs.de_atlang = Deutch (\u00d6sterreich) - German
(Austria)
7. Add new language to the list of languages available in Parallels HSphere. For this, add the language and encoding of the translated files
to the LANG_LIST parameter in
~cpanel/shiva/psoft_config/hsphere.properties. For
example:
This line contains definitions for the languages that come with Parallels H-Sphere,
delimited with whitespace, each including the following components:
<language>_<COUNTRY>_<ENCODING>|<HTML_ENCODING>:misc.langs.<LABEL>la
ng
Here, misc.langs.<LABEL>lang; is the label with the language name, which is set in
the previous step.
8. In hsphere.properties set system locale and encoding to custom
values. The locale should correspond to the Java ISO standards, the
encoding must correspond to the browser standards. For example,
settings for the Portuguese (Brazil) language will look as follows:
The LOCALE value will affect not only the interface language, but also the currency,
date, time, days of the week and other locale settings.
68 Localization
9. Run language bundle compiler (on page 62) to implement new bundles
into Parallels H-Sphere:
java psoft.hsphere.LangBundlesCompiler
10. Restart Parallels H-Sphere (on page 136).
Changing Language of Context Help
Online help texts are hard-coded in special Parallels H-Sphere templates (on page 11)
with .oh extension located in the ~cpanel/shiva/shiva-templates/common/online_help/ directory.
Carefully follow the procedure outlined in the Customizing Templates (on page 10)
document, with the following considerations specific to context help templates:
Copy the online help files from the ~cpanel/shiva/shiva-
templates/common/online_help/ folder to the custom template directory
~cpanel/shiva/custom/templates/common/online_help/, to files whose
names contain identifiers for target language, country and encoding, in the format
similar to that of language bundles (on page 58):
Important: Parallels H-Sphere uses the UTF-8 charset for all languages. Therefore,
text directly inserted into templates (i.e., not by means of text labels defined in
language bundles (on page 58)) must be in the UTF-8 encoding. Other regional
encodings (for example, Windows-1251 for Russian) must not be used anymore in
context help templates, and texts there must be converted into UTF-8.
Translate the heading and the body of each help file in the corresponding encoding.
Localization 69
Updating Translation of Parallels HSphere Interface
With every update of Parallels H-Sphere, your translation of the control panel interface
becomes outdated, and you need to update translation in language bundles (on page
58).
Note: Parallels H-Sphere developers are not responsible for adding languages to
Parallels H-Sphere interface and updating translation of the default English bundles. It
is entirely up to Parallels H-Sphere owners. All language bundle translations included
into Parallels H-Sphere interface are kindly provided by our customers.
Parallels H-Sphere comes with a script that finds differences between two files: the new
English file and its old translated version. This script, diff_labels.pl, is located in
the ~cpanel/shiva/psoft/hsphere/lang/ default bundle directory.
To compare these 2 files with a new English language bungle with outdat, do the
following:
1. Log into your CP server as the cpanel (on page 136) user.
Here, /path/to/ is a path to language bundles in another language (they may not be
located in the default bundle directory), <LOCALE> contains language, country and
encoding identifier in accordance with language bundle filename format (on page
58).
The tool will write all the differences between these updated default language
bundles and their previous translation into the corresponding .diff files.
4. Customize your language bundles (on page 60) by adding translated
labels from the resulting .diff files.
The following Parallels H-Sphere components are configured by means of XML files
Component
Property
Filename
CP Skins
(Designs)
DESIGN_SCHEME_CONFI
G
design_config.xml
CP Menu
MENU_CONFIG
menu.xml
CP Crons
CRON_CONFIG
cron_config.xml
Online (Context)
Help
HELP_CONFIG,
ONLINE_HELP_CONFIG
help.xml
help_url.xml
Promotion
Validators And
Calculators
PROMO_CONFIG
promotion/xml/promotions
.xml
Merchant
Gateways
MERCHANT_GATEWAYS_C
ONF
merchants.xml
Domain Registrars
REGISTRAR_CONF
registrar.xml
E-Mail
Notifications
USER_EMAILS
user_emails.xml
In this chapter:
Merging XML Configuration Files ...................................................................... 71
XML Manager .................................................................................................... 73
Creating Plan Wizards with XML ....................................................................... 77
Adding Custom CP Cron Jobs ........................................................................... 84
Adding Custom Promotion Validators and Calculators....................................... 88
Adding Custom MS Exchange Plans into Parallels H-Sphere ............................ 91
located in the ~cpanel/shiva/psoft/hsphere/ directory:
Custom XML files can be merged with default XML files by means of XML merger (on
page 73). Instead of moving and changing a default XML file, a small custom file is
created containing only the changes to be implemented, and its location is specified in
~cpanel/shiva/psoft_config/hsphere.properties in the parameter with the
"CUSTOM_" prefix added to the default parameter name. For example:
2. Create a directory for custom XML configuration files if it does not exist,
for example, ~cpanel/custom/xml.
3. In the custom directory, create a custom XML file if it hasn't been
created yet. Here, you add only those tags that need to be added or
modified with relation to the default XML file. Please follow the rules for
merging XMLs.
For example, if you need just to add a new item to the menu, the custom menu.xml
file will look like:
<?xml version="1.0"?>
<!DOCTYPE config [
<!ELEMENT config (menus,interface)>
<!ELEMENT menus (menu+)>
<!ELEMENT menu (menuitem*,initmenu*)>
<!ELEMENT menuitem (#PCDATA)>
<!ELEMENT initmenu (#PCDATA)>
<!ELEMENT interface (menudef+)>
<!ELEMENT menudef (initmenu*,menuitem*)>
<!ATTLIST menudef id CDATA #REQUIRED>
<!ATTLIST menu name CDATA #REQUIRED>
<!ATTLIST menu label CDATA #REQUIRED>
<!ATTLIST menu platform_type CDATA "">
<!ATTLIST menu resource CDATA "">
<!ATTLIST menu defaultitem CDATA #REQUIRED>
<!ATTLIST menu tip CDATA "">
<!ATTLIST menuitem name CDATA #REQUIRED>
<!ATTLIST menuitem label CDATA #REQUIRED>
<!ATTLIST menuitem URL CDATA #REQUIRED>
<!ATTLIST menuitem platform_type CDATA "">
<!ATTLIST menuitem resource CDATA "">
<!ATTLIST menuitem tip CDATA "">
<!ATTLIST menuitem check_type CDATA "1">
<!ATTLIST menuitem new_window CDATA "0">
<!ATTLIST initmenu name CDATA #REQUIRED>
]>
<config>
<menus>
<menu name="info" label="info.label" defaultitem="info-plans"
tip="info.tip">
<menuitem name="new_item" label="NEW PAGE"
URL="/newpage.html" resource="" tip="Positive Software
Corporation"/>
</menu>
</menus>
72 XML Customization
</config>
Important: In the custom XML file to be merged with the default one, you must
define the same DTD structure!
4. In ~cpanel/shiva/psoft_config/hsphere.properties, add the
location for the custom XML file, for instance:
5. Login as root (log off from cpanel) and restart Parallels H-Sphere (on
page 136).
XML Customization 73
XML Manager
XML Manager serves for loading custom XMLs into Parallels H-Sphere and merging
them with the standard, or default, Parallels H-Sphere XML configuration files. This
enables to extend Parallels H-Sphere by adding new elements, like custom menu
items, without changing the standard XML configuration files. This mechanism makes
customization more flexible to the Parallels H-Sphere updates. Now you don't need to
apply custom settings each time the standard configuration files are rewritten by new
releases.
XML Manager Implementation
XMLManager is the subclass of the psoft.hsphere.util class of Parallels H-Sphere
utilities. XMLManager returns either Document object or TemplateXML object.
XMLManager searches for custom XML configuration files, by the key, not by the
filename:
1. in hsphere.properties;
2. in the predefined values (see
psoft.hsphere.util.PackageConfigurator).
For example, the menu XML configuration file is set in hsphere.properties as follows:
XMLManager looks for the MENU_CONFIG key instead of the full pathname
(/hsphere/local/home/cpanel/shiva/psoft/hsphere/menu.xml).
XMLManager may also process the group of XML files. It is currently implemented for
XML plan wizards (on page 77), where the key is compounded from the corresponding
path + the name of XML file, like:
XMLManager.getXML(PLAN_WIZARDS_DIR, "unix.xml");
Example:
Consider an example of merging menu default and custom menu XMLs. For details,
please refer to Menu Customization in Customization Guide.
1. Log in as the cpanel user.
2. Create custom XML file and specify its location as
CUSTOM_XML_CONFIG in hsphere.properties (see XML Merge
Customization in Customization Guide for details):
~cpanel/shiva/custom/xml/test1_menu.xml should look like
this:
<?xml version="1.0"?>
<!DOCTYPE config [
<!ELEMENT config (menus,interface)>
<!ELEMENT menus (menu+)>
<!ELEMENT menu (menuitem*,initmenu*)>
<!ELEMENT menuitem (#PCDATA)>
<!ELEMENT initmenu (#PCDATA)>
<!ELEMENT interface (menudef+)>
<!ELEMENT menudef (initmenu*,menuitem*)>
<!ATTLIST menudef id CDATA #REQUIRED>
<!ATTLIST menu name CDATA #REQUIRED>
<!ATTLIST menu label CDATA #REQUIRED>
<!ATTLIST menu platform_type CDATA "">
<!ATTLIST menu resource CDATA "">
<!ATTLIST menu defaultitem CDATA #REQUIRED>
<!ATTLIST menu tip CDATA "">
<!ATTLIST menuitem name CDATA #REQUIRED>
<!ATTLIST menuitem label CDATA #REQUIRED>
<!ATTLIST menuitem URL CDATA #REQUIRED>
<!ATTLIST menuitem platform_type CDATA "">
<!ATTLIST menuitem resource CDATA "">
<!ATTLIST menuitem tip CDATA "">
<!ATTLIST menuitem check_type CDATA "1">
<!ATTLIST menuitem new_window CDATA "0">
<!ATTLIST initmenu name CDATA #REQUIRED>
]>
<config>
<menus>
<menu name="info" label="info.label" defaultitem="info-plans"
tip="info.tip">
<menuitem name="xyz-wow" label="NEW PAGE"
URL="/newpage.html" resource="" tip="Positive Software
Corporation"/>
</menu>
</menus>
</config>
Note: In the custom XML file to be merged with the default one, you must define the
same DTD structure!
Also note that we don't copy the whole structure of the standard menu.xml file. The
custom menu will be merged with the standard menu in the following way (the NEW
PAGE item in the INFO menu):
XML Customization 75
4. To check if the merge is performed correctly, run the DOMLoader utility
and check out.xml afterwards:
java psoft.util.xml.DOMLoader
/hsphere/local/home/cpanel/shiva/psoft/hsphere/menu.xml
/hsphere/local/home/cpanel/shiva/custom/xml/test1_menu.x
ml > out.xml
With DOMLoader, you may merge more than two XML files:
In your custom XML configuration files you should use the processing instructions to
change or remove certain fragments in the default configuration file, instead of merging
these fragments directly.
The merge instruction is used by default and can be omitted.
The <?changeattr?> instruction is added to customize tag attributes in XML
documents.
In order to change, remove, or merge an element, you need to create a well formed
XML document, which describes the location of this element relative to other elements.
Leave out the elements you don't want to change/remove/merge. Put the instruction
before the XML element that needs to be changed/removed/merged.
Examples:
1) To remove a certain (tt) item from the the default menu configuration:
<?xml version="1.0"?>
<!DOCTYPE config [
<!ELEMENT config (menus,interface)>
<!ELEMENT menus (menu+)>
<!ELEMENT menu (menuitem*,initmenu*)>
<!ELEMENT menuitem (#PCDATA)>
<!ELEMENT initmenu (#PCDATA)>
<!ELEMENT interface (menudef+)>
<!ELEMENT menudef (initmenu*,menuitem*)>
<!ATTLIST menudef id CDATA #REQUIRED>
<!ATTLIST menu name CDATA #REQUIRED>
<!ATTLIST menu label CDATA #REQUIRED>
<!ATTLIST menu platform_type CDATA "">
<!ATTLIST menu resource CDATA "">
This document explains how to customize plan wizards by modifying plan wizard XML
configuration files.
Introduction
Parallels H-Sphere supports XML-based plan wizards. Wizards are located in the
~cpanel/shiva/psoft/hsphere/plan/wizard/xml directory. Location can be
altered by setting PLAN_WIZARDS_DIR in
~cpanel/shiva/psoft_config/hsphere.properties to a target directory.
PLAN_WIZARDS_DIR =
/hsphere/local/home/cpanel/shiva/psoft/hsphere/plan/wizard/xm
l
The list of wizards is defined in the plan_wizards.xml file, which is by default
located in the plan wizards directory. The file's name and location is set in the
PLAN_WIZARDS parameter in hsphere.properties (the full path to the file is required):
Here, Unix plan XML definition file is
~cpanel/shiva/psoft/hsphere/xml/unix.xml, and the plan's description is set
in the lang.planeditor.res_unix label in
~cpanel/shiva/psoft/hsphere/lang/hsphere_lang.properties.
Defining Plan Wizard
Plan wizard definition starts with creating a new .xml file. See unix.xml
(http://hsphere.parallels.com/HSdocumentation/xmls/unix.xml) as an example of
planwizard definition.
<categories>
The categories tag defines plan resources. Resources are grouped into categories
and described within the <category> tags. Each category tag can have the
description attribute which is optional. Categories are used in plan wizard screens
to group resources into logical groups.
<resource>
The <resource> tag within the <category> construction defines the resource class,
name, description and includes the following attributes if necessary:
name - name of the resource, like account, mailbox;
class - name of the resource class;
help (optional) - description of the resource from the hsphere_lang.properties
file;
unit (optional) - units for the resource, MB or GB;
required (optional) - if it is set to 1, the resource is required in the plan and regarded
to be automatically included to the plan;
include(optional) - if it is set to 1, the resource will be marked as included by default
to the plan wizard;
active (optional) - if active parameter is not set, no active checkbox will be available
for the resource. Otherwise, if it is set to 1, resource will be marked as active by
default. Any other value - active checkbox will be present but not checked;
noprice (optional) - if 1, the wizard will not prompt to enter pricing for the resource;
ifresource (optional) - list of resources separated by the vertical bar '|' character. If
any of the resources are included to or required in the plan, this resource will also
be included.
<field>
Inside the <resource> construction, the <field> tag allows to get more info from the
user for a resource specified. The data will be returned as a part of HTTP request and
can be used later via the #name parameter.
80 XML Customization
Attributes:
name - name of the field, you can retrieve it later via the #name parameter;
label - label from hsphere_lang.properties, refers to a caption to be displayed in the
wizard;
type - type of the field to be displayed: textbox|checkbox.
If type = "textbox", the following attributes are set:
value - the default value;
planvalue - name of the resource plan value (value defined in the plan); While editing
the plan, the wizard will try to retrieve this value and show it as the textbox value;
size - size of the textbox;
check - yafv check (not implemented yet).
<ifresource>
The <ifresource> element allows to group resources/LogicalGroup and activate
them for the plan, only if the resource is enabled via global resources, or for the reseller
plan.
Attributes:
name - resource name. Will be checked by admin.isResourceDisabled;
description - description of the resource from hsphere_lang.propeperties.
<ifgroup>
The <ifgroup> element works in the same way as ifresource but checks if the
server group is available.
Attributes:
XML Customization 81
name - server group name;
else - resource name to show as unavailable.
<resources>
The <resources> element is used to define resources and their initialization
sequence.
Resources are defined in the resources element in the custom res_RESOURCE_NAME
child tag where RESOURCE_NAME is the resource mnemonic identifier.
For example, for the unixuser resource the tag would look like:
<res_unixuser> </res_unixuser>
<mod>
The <mod> tags determine what mods will be defined in the plan.
Attributes:
name - name of the mod; "" if missing;
ifresource - list of resources delimited with '|'. If any of those resources will be
available in plan, i.e., required, selected through the Web as included, or derived as
included, the mod will be defined in the plan, otherwise it won't be defined.
<initresource>
The <initresource> tags inside mod constructions define what child resources are
created with the creation of this resource.
Attributes:
name - name of the resource. The system automatically checks if the resource is
included in the plan before adding the initresource;
ifactive - list of resources delimited with '|'. If any of these resources are selected in
the plan wizard as activated, the initresource is created; otherwise, it won't be
created, but will be available for creation by account owners.
unique (optional) - a flag to mark the initresource whose mod will be changed in the
plan wizard. For example, you may set initresource for the IP resource to shared IP,
and then change shared IP to dedicated IP in the plan wizard in Control Panel. In
this case, if you don't set the unique attribute in the initresource tag, another
initresource record will be added to the system database and that will cause serious
malfunctions.
However, if unique="1" is set, no new initresouce record will be created when
another mod is selected; instead, the existing initresource record will be modified.
Example:
<initresource name="ip" mod="shared" unique="1"/>
<initvalue>
The <initvalue> tag defines initial plan values.
82 XML Customization
Initvalues are passed to the resource constructor as a Collection, and you need to be
very careful with their order. Initvalue names aren't used as keys. Typically, the
constructor would read initvalues like this:
type - one of the following types as defined in psoft.hsphere.plan.InitValue:
static - the value enclosed in the tag.
field - the value taken from the submitted form by the name enclosed in the tag.
relative - the value obtained with the TemplateModel get(String key)
method of the resource chain from the current resource up the resources tree. The
search stops upon finding the first not null value.
absolute - the value obtained with the TemplateModel get(String key)
method of the current resource. Unlike 'relative', it allows getting values of
TemplateHash returned by the TemplateModel get method.
Example: A resource returns a hash accessible from TemplateModel
get(String key) by the key a. This hash, in its turn, contains a value accessible by the key b. To access this value, you need to set initvalue to a.b.
relative_rec - implements embedding as in 'absolute' with support of ascending
recursion as in 'relative'.
absolute_rec - implements embedding, but calls TemplateModel get(String
key) of the top resource in the tree - the account.
hostgroup - is used to get a random HostEntry object within the given logical server
group. The value of the group is stored as a plan value with id '_HOST_' + value of
the current init value.
plan_free - returns free units for the current resource if applicable.
plan_value - returns plan value accessible by the current initvalue as key.
label - is not used anymore, can be considered a comment.
The initvalue tag content is a string. If it starts with #, the value will be used as a
name of the parameter which is passed via http request.
Here are several pre-defined variables that could serve as the initvalue tag
content:
Here, the value of the mixedip parameter that is passed via HTTP request is checked
for being equal to the value of the dedicated parameter.
<values>
The <values> element includes the <value> constructions inside.
<value>
The <value> tag defines the resource values in the plan.
Attributes:
name - mnemonic identifier. If the tag content string starts with #, the value will be
used as a name of the parameter that is passed via HTTP request.
Example:
<value name="SSI">1</value>
<special>
The <special> element is used to define some additional settings such as tld pricing.
It allows to add checkbox to any resource and, if checkbox is selected, to include
another template.
To define the special attribute for a resouce, create the <res_RESOURCE_NAME> tag
(like <res_opensrs>) inside the <special> element (you can have multiple tags
inside the special section).
<field>
Inside <res_RESOURCENAME> tag, the <field> tag is used to define the HTML field.
Attributes:
type - checkbox type;
name - name of the checkbox field;
label - label from hsphere_lang.properties referrring to the field caption;
value - value of the checkbox;
checked - equals 1 if checked.
<include>
Inside the <field> element, the <include> tag defines a template to be included.
Attributes:
84 XML Customization
ifvalue - a value to match against the field; if it matches, the template is included;
name - the name of the template to be included.
4. Add the custom cron job class to CLASSPATH set in the
.bash_profile file located in the ~panel home directory.
5. Create the custom cron XML configuration file if it is not created yet. We
recommend to add all custom cron jobs into the custom cron configuration file, not to the standard cron XML configuration file (on
page 86).
1. Create the custom cron configuration file, for example,
~cpanel/shiva/custom/xml/cron_config.xml
2. The XML structure of the custom cron config file should be the same as of the
standard cron configuration file.
6. Add the custom cron job to the custom cron configuration file.
Add a new group of jobs if required or add your custom cron job there, or, add your
custom job to an existing group. Group is set by the group tag. Jobs are set in the
cron tags within their groups. For example:
<config>
...
<group name="GroupN" maxpriority="10" defpriority="3">
<!-- priority of jobs within the group is ranked from 1 to
10;
if job priority is not specified, it is 3 by default -
Cron jobs are grouped according to their purpose. Default group is CRON. Cron groups
are set in the group constructions that contain the job tags describing jobs in these
groups:
<config>
<group name="CRON" maxpriority="10" defpriority="3">
<!-- priority of jobs within the group is ranked from 1 to
10;
if job priority is not specified, it is 3 by default -
->
...
<job name="CustomCron" class="custom.cron.CustomCron"
db_mark="C_CRON"
starttime="now+15m" period="15"/>
<!-- job starts in 15 minutes after CP start and runs every 15 minutes -->
...
</group>
...
</config>
Group attributes:
name - group name;
disabled - group jobs are all disabled if disabled="1". If not set, disabled is set to
0 (enabled);
maxpriority - sets the maximum number to which job priority within a group is scaled.
For example, if maxpriority is 15, then job priority within a group is from 1 to 15,
where 1 is the least priority, and 15 is the maximum priority. If this option is not set,
maximum priority for a group is 10 by default;
defpriority - set the default job priority. If the job's priority attribute is not set, the job
priority will be equal to the group's defpriority value.
defperiod - sets the default launching period for group jobs, in minutes;
maxjobcount - maximum number of jobs in the group running at a time.
Job attributes:
name - job name;
XML Customization 87
class - a fully qualified Java class name for the cron job (see Adding Custom CP
Crons (on page 84) for instructions on adding custom cron job classes);
disabled - if set to 1, the job is disabled; otherwise, it is enabled;
priority - if set, overrides the default group priority;
starttime - time when the job starts first. Format:
HH:MM - time in hours and minutes, for example, 5:15;
now - job starts immediately after CP start/restart;
now+HHhMMm - job starts in HH hours MM minutes after CP start/restart, for
example, now+15m, now+2h, now+2h15m.
If starttime is not set, the job won't start automatically.
period - sets the job launching period, in minutes; if not set, the job won't run;
maxinstancecount - maximum number of job instances running at a time.
threadcount - maximum number of threads running at a time in a multi-thread job.
db_mark - points to the job name in the Parallels H-Sphere database (value of the
name field in the last_start table).
See CP Crons in H-Sphere Sysadmin Guide for the last_start table description.
88 XML Customization
Adding Custom Promotion Validators and
Calculators
Parallels H-Sphere allows to define custom promotions - flexible discount systems and assign them for individual plans.
Usually, a customer enters a certain promotion code on signup, the system verifies the
entered code if it proves to be valid and corresponds to the chosen plan, that user signs
up with that discount. This is called a codeable promotion. There are also codeless promotions that don't require a code. Discount depends on a particular promotion and
the way the discount is calculated.
This document explains how to add and configure custom promotion validators and
calculators.
To add a custom promotion validator or calculator to Parallels H-Sphere:
1. Log into the CP server as the cpanel (on page 136) user.
2. Create a custom promotion validator or calculator:
To create a promotion validator, use the the
psoft.hsphere.promotion.PromoValidator Java class interface:
3. Configure custom promotion validator or calculator in the XML
configuration file.
All promotion validators and calculators should be added to and configured in the
promotions.xml file. Its default location is
~cpanel/shiva/psoft/hsphere/promotion/xml/. The file location can be altered with the PROMO_CONFIG and CUSTOM_PROMO_CONFIG properties in
~cpanel/shiva/psoft_config/hsphere.properties:
<promotions> - contains all defined promotion validators.
<promo> - configuration of a particular promotion validator.
Attributes:
id - a unique promotion identifier: 1,2,...
description - a short description of a validator. It shows up in the dropdown list of
promotions in Control Panel.
class - a name of a Java class for this validator.
itype - a type of the validator's interface. If it is set to "AUTO", interface for adding
the validator parameter will be built automatically, depending on parameters
defined for the validator or calculator; otherwise, values of the add_template and
edit_template attributes will be used as template names for adding/editing set of
data which is required for a given promotion validator.
add_template - a name of a template for adding the validator data; the value of
this attribute will take effect only in case if itype is not set to "AUTO".
edit_template - a name of a template for editing the validator data; the value of
this attribute will take effect only in case if itype is not set to "AUTO".
<calculators> - contains all defined promotion calculators.
<calc> - configuration of a particular promotion calculator. Attributes have the same
meaning as for promotion validators.
<params> - contains all parameters used by promotion validators or calculators.
<param> - configuration of a particular parameter.
Attributes:
label - a name of a label in
~cpanel/psoft/hsphere/lang/hsphere_lang.properties with the
message that appears on the page where users enters a promo code.
name - the parameter's name. The AbstractPromoDataStorage object stores
validators' or calculators' data from HttpRequest using this name with the prefix
pv_ for a validator and pc_ for a calculator. For example, if name="percent",
AbstractPromoDataStorage expects the pv_percent variable for the validator
and the pc_percent variable for the calculator to be present in HttpRequest.
XML Customization 91
Adding Custom MS Exchange Plans into
Parallels H-Sphere
Since version 2.5 Parallels H-Sphere provides integration with Microsoft Exchange mail
hosting plans. The following four default MS Exchange plans are already included into
Parallels H-Sphere as resources:
Base Mail
Gold Mail
Platinum Mail
Platinum Mail Pro
Parallels H-Sphere admin can also import more plans created on MS Exchange server
into Parallels H-Sphere as MS Exchange hosting resources. This document is an
example of a step-by-step procedure on how to do it:
1. Create a custom msExchangePlans.xml file with description of your
new custom MsExchange plan (it will be merged with the standard
msExchangePlans.xml):
<plans>
<plan type="new_plan">
<planName>NewPlanName</planName>
<planDescription>New MS Exchange Plan
Name</planDescription>
<planFeatures>
where new_plan is the name of the MS Exchange hosting plan you are adding. This
name must not exceed 10 symbols.
Notes:
1. Don't copy content of the existing standard HS MsExchange plan xml file.
2. Parallels H-Sphere 2.5 and up implements a Java utility that fetches this
information from MS Exchange hosting server:
java psoft.hsphere.tools.HePlanExctractor
This utility prints XML output with properties of all available MS Exchange
hosting plans. Or, you can obtain plan features in XML form in the
HostedExchange Web interface under the GetPlanDetail service.
3. Read more how to merge custom XML files in Customization Guide.
3. Log into the CP server as the cpanel user.
4. Create a special location where you will assemble and build a package
describing your MsExchange plan, for example,
~cpanel/shiva/custom/Packages:
mkdir ~cpanel/shiva/custom/Packages
5. Run package configurator (on page 113):
cd ~cpanel/shiva/custom/Packages
java psoft.hsp.tools.PkgConfigurator --withprefix=./ms_customization --with-xmls --with-properties -with-sql
Package configurator will create the ms_customization directory, which includes the
following structure:
src/pkg_config/ - directory with the default.properties file
src/pkg_xmls/ - directory directory where you will place msExchangePlans.xml
and msexchange.xml
src/_pkg.xml - file to set package name, version, build, vendor and description
src/_SCRIPTS/_pkg.sql - file to add the SQL query that will be executed during the
package installation
XML Customization 93
1. Set the package name, version, build, vendor, description in
src/_pkg.xml:
<?xml version="1.0" encoding="UTF-8"?>
<pkg build="00" description="Description for test package"
info="Additional information" name="MSExchangeCustomization"
vendor="Vendor" version="00.00.00">
<xmls src="pkg_xmls/"/>
<config path="pkg_config/default.properties"/>
Note: Package name can't contain spaces and special characters.
2. Edit src/_SCRIPTS/_pkg.sql. Add the following line into it:
where:
resource_type_id is an integer from the range 20100-21490, unique in the
type_name.
new_plan is a resource type name, up to 10 symbols string without spaces.
resource_type_description is your plan description.
RFS - price type, should be RFS for all MS Exchange plans you add.
For example, a standard MS Exchange plan will have the following records:
hsphere=# SELECT * from type_name where description like
'Hosted Exchange%';
id | name | price | description | rprice | required |
priority | ttl
groups - container for description of the groups of e-mail notifications. (In Settings->E-
Mail Notifications, notifications are displayed in groups, according to their purpose.)
group - tag for the group description.
Attributes:
id - group identifier.
name - group name, corresponds to the label in language bundles (on page 58)
(~cpanel/languages/hsphere_lang.properties).
emails - container for description of e-mail notifications.
email - tag with notification description.
Attributes:
tag - notification tag. Corresponds to the notification's ce.TAG_NAME.title
(name of the notification in the list in CP), and ce.TAG_NAME.desc (short
description in the list) labels in hsphere_lang.properties, where TAG_NAME
is the value set in the tag attribute of the notification in user_emails.xml
group_id - corresponds to the id attribute of the group to which this e-mail
notification belongs to.
template - pathname to the corresponding system e-mail notification template,
relative to the ~cpanel/shiva/shiva-templates/common directory of
default Parallels H-Sphere templates. For example,
template="mail/custom_registrar_registration.txt" points to the
template for the "welcome" message on creating a new account.
massmail_applicable - if set to 1, this notification is available for mass mail
delivery.
admin_only - if admin_only="true", this notification is available only from the
admin CP.
no_cc - if no_cc="true", no copies (the BCC: field) of this e-mail notification
are sent to the addresses defined in the CP admin's Settings->Notification Recipients menu. That corresponds to unchecking the Sent CC checkbox while
editing the notification in CP.
subject - tag with the subject of the e-mail message to be sent to customers.
96 XML Customization
Using Variables in Parallels H-Sphere E-Mail
Tag
Description
Variables
Misc
LOST_PASSWORD
Lost Password
Message
standard variables
OVERLIMIT
Overlimit Notification
suspend
over_limit_res
standard variables
SSH_NOTIFICATION
Shell Access
Notification
result
subject
standard variables
VPS_INIT
Virtual Private Server
Initialization
Notification
vpsname
ips
ci
standard variablesCustom Domain Registration
Parallels H-Sphere e-mail notifications can be customized directly in CP admin
interface in the Settings->E-Mail Notifications menu.
This document aims at advanced customization of these messages. It contains the
description of basic notification variables.
Below is the table illustrating which variables are used in which notifications. The
notifications are grouped and named according to their XML configuration file,
user_emails.xml. The Tag column corresponds to the names of the notifications set
in the tag attributes in user_emails.xml. In the Variables column, only variables
specific to that particular notifications are listed. Standard variables are variables
common for all notifications. Properties and methods for variables are listed below.
The List of Notification Variables
XML Customization 97
email_days
standard variables
CUSTOM_REGISTRAR_REGISTRATION
Custom Domain
Registration Request
Message
registrant
tech
admin
billing
domain_name
renew_days
email_days
standard variables
CUSTOM_REGISTRAR_RENEW
Custom Renew
Domain Registration
Message
registrant
domain_name
renew_days
email_days
period
standard variablesManaging Debtors
DEBT_DEL_NOT
Deletion Warning
bill
negative_date
current_date
suspend_date
delete_date
standard variables
DEBT_DEL_REASON
Account Deletion
bill
negative_date
current_date
suspend_date
delete_date
standard variables
DEBT_SUSP_NOT
Suspension Warning
bill
negative_date
current_date
suspend_date
delete_date
standard variables
DEBT_SUSP_REASON
Account Suspension
Not implemented
DEBT_WARN_NOTIFICATION
Outstanding Balance
Notification
bill
negative_date
current_date
suspend_date
delete_date
standard variables
TRIAL_SUSP_REGISTER
Trial Suspension
Notification
standard variables
Welcome Messages
98 XML Customization
FAILED_SIGNUP
Failed Signup
Notification
failed_signups_q
accounts
lang
NEW_ACCOUNT
Welcome Letter
bi
ci
standard variables
NEW_MODERATED
Welcome Letter For
Moderated Accounts
bi
ci
reseller_url
standard variables
NEW_MODERATED_CC
Welcome Letter For
Moderated Account
with CC
bi
ci
reseller_url
standard variables
TRIAL_MODERATED
Welcome Letter For
Trial/Moderated
Account
bi
ci
reseller_url
standard variables
TRIAL_REGISTER