Parallels H-Sphere - 3.6.3 Customization Guide
Printed on 11 December, 2013
Parallels H-Sphere 3.6.3 Customization
Guide
Legal and Copyright Notice
Parallels IP Holdings GmbH
Vordergasse 59
CH-Schaffhausen
Switzerland
Phone: +41-526320-411
Fax: +41-52672-2010
Copyright © 2012 Parallels IP Holdings GmbH. All rights reserved.
www.parallels.com
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.
Contents
Preface 6
Typographical Conventions ........................................................................................................... 6
Feedback ....................................................................................................................................... 7
Introduction To Parallels H-Sphere Customization 8
Template Customization 10
Understanding Parallels H-Sphere Templates ............................................................................ 11
What Are Templates ......................................................................................................... 11
Location of Templates ....................................................................................................... 11
System E-Mail Notification Templates .............................................................................. 11
Skeletons ........................................................................................................................... 12
Web Interface Templates .................................................................................................. 12
Designs ............................................................................................................................. 14
Replacements ................................................................................................................... 14
Template Directory Structure ............................................................................................ 14
Template Lookup Sequence ............................................................................................. 15
Customizing Templates Step by Step ......................................................................................... 16
Pre-Cautions ..................................................................................................................... 16
Pre-Requisites ................................................................................................................... 16
Step-By-Step Template Customization Procedure ........................................................... 16
Compiling Templates With Client-Side Form Validation ............................................................. 18
Customizing Skeleton Templates ................................................................................................ 19
Adding Context Help Pages ........................................................................................................ 19
System E-Mail Templates ........................................................................................................... 21
Customizing User Signup ............................................................................................................ 24
Design Customization 30
Skin And Icon Set Customization ................................................................................................ 31
Design XML Customization ............................................................................................... 31
Implementation of Custom Design Templates .................................................................. 32
Design XML Configuration .......................................................................................................... 34
Icons .................................................................................................................................. 34
Skill Icon Groups ............................................................................................................... 35
Icon Image Sets ................................................................................................................ 36
Common Images ............................................................................................................... 37
Color Types ....................................................................................................................... 37
Designs ............................................................................................................................. 38
Interface Controls And Colors in Templates ............................................................................... 40
Interface Colors ................................................................................................................. 41
Adding Custom Icons .................................................................................................................. 42
Menu Customization 45
Menu XML Customization ........................................................................................................... 46
Changing Menu Structure ........................................................................................................... 46
Location ............................................................................................................................. 46
XML Structure ................................................................................................................... 47
Modifying Menu Groups And Items ................................................................................... 47
4
Configuring Individual Menu Layouts For Different Hosting Plans ................................... 48
Assigning External Links to Menu Items ........................................................................... 49
Menu Design Customization ....................................................................................................... 51
Interface Text Customization (Language Bundles) 54
Understanding Interface Text (Language) Bundles .................................................................... 55
Interface Text Customization ....................................................................................................... 57
Language Bundle Compiler ......................................................................................................... 58
Localization 61
Adding New Languages To Parallels H-Sphere .......................................................................... 62
Translating Language Bundles ......................................................................................... 62
Adding New Language Bundles Into Parallels H-Sphere ................................................. 63
With packages ................................................................................................................... 63
Compiling bundles ............................................................................................................. 63
Changing Language of Context Help .......................................................................................... 65
Updating Translation of Parallels H-Sphere Interface ................................................................. 66
XML Customization 67
Merging XML Configuration Files ................................................................................................ 68
XML Manager .............................................................................................................................. 70
XML Manager Implementation .......................................................................................... 70
XML Merge Processing Instructions ................................................................................. 72
Creating Plan Wizards with XML ................................................................................................. 74
Introduction ........................................................................................................................ 74
Adding a New Wizard to the List of Plan Wizards............................................................. 75
Defining Plan Wizard ......................................................................................................... 75
Adding Custom CP Cron Jobs .................................................................................................... 80
CP Cron XML Configuration .............................................................................................. 82
Adding Custom Promotion Validators and Calculators ............................................................... 84
Adding Custom MS Exchange Plans into Parallels H-Sphere .................................................... 87
Customizing E-Mail Notification List ............................................................................................ 90
Using Variables in Parallels H-Sphere E-Mail Notifications .............................................. 92
Packages 108
Building Packages ..................................................................................................................... 109
Step 1. Preconfiguration .................................................................................................. 110
Step 2. Configuration ...................................................................................................... 112
Step 3. Package Builder .................................................................................................. 114
Building Language Packages .................................................................................................... 114
Java Tools For Packaging ......................................................................................................... 116
Package Configurator ..................................................................................................... 117
Package Builder .............................................................................................................. 119
Package Installer ............................................................................................................. 119
Package Uninstaller ........................................................................................................ 120
Package Checker ............................................................................................................ 120
Package XML Configuration File (_pkg.xml) ............................................................................. 121
Template Customization With Packages .................................................................................. 123
XML Customization With Packages .......................................................................................... 125
Package Installation .................................................................................................................. 126
Package Uninstallation .............................................................................................................. 127
Package Upgrade ...................................................................................................................... 128
5
Appendix 129
Logging in as the cpanel User ................................................................................................... 130
Restarting Parallels H-Sphere Control Panel ............................................................................ 130
In this chapter:
Typographical Conventions ............................................................................... 6
Feedback .......................................................................................................... 7
Formatting convention
Type of Information
Example
Special Bold
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.
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
(Skins And Icon
Parallels H-Sphere interface design has a broader
meaning than just configuration of certain color
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:
9
Sets)
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.
In this chapter:
Understanding Parallels H-Sphere Templates ................................................... 11
Customizing Templates Step by Step ................................................................ 16
Compiling Templates With Client-Side Form Validation ..................................... 18
Customizing Skeleton Templates ...................................................................... 19
Adding Context Help Pages .............................................................................. 19
System E-Mail Templates .................................................................................. 21
Customizing User Signup .................................................................................. 24
C H A P T E R 3
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/shivatemplates. It is set by the TEMPLATE_PATH parameter in the
~cpanel/shiva/psoft_config/hsphere.properties file:
TEMPLATE_PATH = /hsphere/local/home/cpanel/shiva/shivatemplates/
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:
USER_TEMPLATE_PATH=/hsphere/local/home/cpanel/shiva/custom/te
mplates/
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
12
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 21).
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 19).
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 21) for generation of the page header, menu and footer, and includes control
templates for processing forms.
Main templates are .html files located in the ~cpanel/shiva/shiva-
templates/<design>/ directories for each design (on page 21).
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 18).
13
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/common/functions - generic macro
collection, Does not depend on designs.
~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.
~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 19). Also read about context help in different
languages (on page 65).
14
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.
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
Parallels H-Sphere basic designs.
~cpanel/shiva/shiva-templates/common/JS - JavaScript functions (used
for all designs)
~cpanel/shiva/shiva-templates/<design>/design - contains templates for
special purposes such as login page, password reminder page, header and footer
templates and the like.
~cpanel/shiva/shiva-templates/<design>/CSS - CSS styles for a design.
15
~cpanel/shiva/shiva-templates/<design>/<subdir> - main templates are
placed into separate subdirectories, according to their tasks, e.g., admin,
billing, MSSQL, etc.
~cpanel/shiva/shiva-templates/<design>/control/<subdir> -
corresponding control templates.
~cpanel/shiva/shiva-templates/<design>/submit/<subdir> - corresponding
submit templates.
~cpanel/shiva/shiva-templates/<design>/replacements/ - template
replacements for different types of plans.
~cpanel/shiva/shiva-templates/<design>/replacements/<plan>/<subdir>
- template replacements overriding templates in corresponding subdirectories for
that design. directory.
~cpanel/shiva/shiva-
templates/<design>/replacements/control/<resources> - control templates
for corresponding replacements.
~cpanel/shiva/shiva-
templates/<design>/replacements/submit/<resources> - submit
templates for corresponding replacements.
Template Lookup Sequence
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:
~cpanel/shiva/custom/templates/<design>/replacements/
~cpanel/shiva/shiva-templates/<design>/replacements/
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:
~cpanel/shiva/custom/templates/<design>/
~cpanel/shiva/shiva-templates/<design>/
3. If the template is not found for this design, the search continues in the
same sequence in the common design template directory:
~cpanel/shiva/custom/templates/common/replacements/
~cpanel/shiva/shiva-templates/common/replacements/
~cpanel/shiva/custom/templates/common/
~cpanel/shiva/shiva-templates/common/
16
Customizing Templates Step by Step
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 130) 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.
Step-By-Step Template Customization Procedure
17
1. On the CP server, log in as the cpanel (on page 130) 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:
USER_TEMPLATE_PATH=/hsphere/local/home/cpanel/shiva/custom/te
mplates/
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 40)
Skin and Icon Set Customization (on page 31)
Edit Interface Texts (on page 57)
Important:
1. We don‟t recommend inserting the interface text directly into the templates. Use
text labels defined in language bundles (on page 55) 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 130).
18
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 130)
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:
TEMPLATE_PATH = /hsphere/local/home/cpanel/shiva/shivatemplates/
2. Uncomment the USER_TEMPLATE_PATH parameter and set it to your custom
templates directory, for example:
USER_TEMPLATE_PATH =
/hsphere/local/home/cpanel/shiva/custom/templates/
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.
4. Run ./configure in the templates directory. This will create
Makefile‟s for all of designs.
19
Warning: Running ./configure clean would remove ALL the compiled
templates in the nested directories and delete ALL Makefile‟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 130) 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
65).
To add a new context help page to Parallels H-Sphere interface:
1. Log into the CP server as the cpanel (on page 130) 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.
20
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:
<call draw_help(“admin-emanager-l_availableforsignup”,””)>
Alternatively, you can call the function that draws help PLUS gives a link to send a
trouble ticket:
<call draw_tt_help(“RESOURCE_ID”, “HELP_ID”, “LABEL”)>
6. In plan creation and edit wizard templates, context help file IDs are
passed with resource calls:
<call service(TAG,PARENT,STRMOD,CAN_ENABLED,OH_ID)>
where OH_ID is the id of the file specified in
~cpanel/shiva/psoft/hsphere/online_help.xml. For example:
<call service(“asp”, “hosting”,””,”1”,”admin-editwizardw_asp”)>
7. If the edited template is in *.html.in format, run make in this
template‟s directory.
8. Restart Parallels H-Sphere (on page 130).
21
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.txt
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
Trial
Registration
trial_account.txt
to customer on account
trial period expiration
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:
22
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.tx
t
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)
Welcome
Letter (Tax
Exemption)
new_account_tax_exemption
.txt
to new customers
awaiting approval of
their Tax Exemption
Codes
23
Tax
Exemption
Approved
Notification
(Moderated
Accounts)
tax_exemption_approved_ne
w.txt
to new customers
signed up to tax
exemption plan,
awaiting moderation
Tax
Exemption
Rejected
Notification
(Moderated
Accounts)
tax_exemption_rejected_ne
w.txt
to new customers
signed up to tax
exemption plan, on
failing to verify tax
exemption data
Tax
Exemption
Approved
Notification
(Live
Accounts)
tax_exemption_approved.tx
t
to customers on tax
exemption approval
Tax
Exemption
Rejected
Notification
(Live
Accounts)
tax_exemption_rejected.tx
t
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:
24
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 18).
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:
<form name=”login” action=”psoft.hsphere.CP” method=”POST”>
or
<form name=”login”
action=”protocol://cp.domain.name:PORT/psoft/servlet/psoft.hs
phere.CP” method=”POST”>.
For example:
<form name=”login”
action=”http://www.psoft.net:8080/psoft/servlet/psoft.hsphere
.CP” method=”POST”>
Note: psoft.hsphere.CP is case sensitive!
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)
User Contact Info
Billing Info (not used for trial registration)
Credit Cards
Billing Period
25
Domains
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
_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
Domain Registration
Domain Regisration Contact Info
Basic (service fields required for signup)
User Contact Info
26
_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‟.
_bi_type
“CC” - credit card,
“Check” - check or
bank transfer,
“PayPal” - PayPal,
“2CheckOut” -
2CheckOut,
“TRIAL”
Payment type
Field name
Possible Values
Explanation
_bi_cc_name
alphanumeric
Credit card name
_bi_cc_number
numeric
Credit Card number
Credit Cards
27
_bi_cc_type
strings available in
the Merchant
Gateway
Manager: “VISA”,
“MC”, etc.
Credit Card type
_bi_cc_exp_month
two digits
the month of Credit Card expiry date
_bi_cc_exp_year
four digits
the year of Credit Card expiry date
Below are the fields for Solo/Switch debit cards used in some countries:
Field name
Possible Values
Explanation
_bi_cc_issues_no
alphanumeric
Issue number
_bi_cc_start_mon
th
two digits
Card Start Month
_bi_cc_start_yea
r
four digits
Card Start Year
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_domain
“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.
Billing Period
Domains
28
domain_name
alphanumeric
Domain name; may be
omitted if
type_domain=”empt
y_domain”
Domain Registration
Field name
Possible Values
Explanation
period
numeric
Registrar‟s periods (years)
_srs_owner_first_nam
e
alphanumeric
User‟s first name
_srs_owner_last_name
alphanumeric
User‟s last name
_srs_owner_address1
alphanumeric
User‟s address 1
_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_co
de
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‟.
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
Domain Registration Contact Info
29
_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=‟NA
‟.
This chapter explains how to customize graphic elements of the Parallels H-Sphere
In this chapter:
Skin And Icon Set Customization ...................................................................... 31
Design XML Configuration ................................................................................. 34
Interface Controls And Colors in Templates ...................................................... 40
Adding Custom Icons ........................................................................................ 42
C H A P T E R 4
Design Customization
Web interface.
Loading...