Parallels H-Sphere - 3.6.1 Customization Guide
Parallels H-Sphere 3.6.1 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 .............................................................................. 12
Skeletons ........................................................................................................................... 12
Web Interface Templates .................................................................................................. 12
Designs .............................................................................................................................. 14
Replacements.................................................................................................................... 15
Template Directory Structure ............................................................................................ 15
Template Lookup Sequence ............................................................................................. 16
Customizing Templates Step by Step ......................................................................................... 17
Pre-Cautions ...................................................................................................................... 17
Pre-Requisites ................................................................................................................... 17
Step-By-Step Template Customization Procedure ........................................................... 18
Compiling Templates With Client-Side Form Validation .............................................................. 19
Customizing Skeleton Templates ................................................................................................ 20
Adding Context Help Pages ........................................................................................................ 20
System E-Mail Templates ............................................................................................................ 22
Customizing User Signup ............................................................................................................ 25
Design Customization 31
Skin And Icon Set Customization ................................................................................................ 32
Design XML Customization ............................................................................................... 32
Implementation of Custom Design Templates .................................................................. 33
Design XML Configuration ........................................................................................................... 35
Icons .................................................................................................................................. 35
Skill Icon Groups ............................................................................................................... 36
Icon Image Sets................................................................................................................. 37
Common Images ............................................................................................................... 38
Color Types ....................................................................................................................... 39
Designs .............................................................................................................................. 39
Interface Controls And Colors in Templates ................................................................................ 41
Interface Colors ................................................................................................................. 43
Adding Custom Icons................................................................................................................... 43
Menu Customization 47
Menu XML Customization ........................................................................................................... 48
Changing Menu Structure ............................................................................................................ 48
Location ............................................................................................................................. 48
Preface 4
XML Structure.................................................................................................................... 49
Modifying Menu Groups And Items ................................................................................... 49
Configuring Individual Menu Layouts For Different Hosting Plans .................................... 51
Assigning External Links to Menu Items ........................................................................... 52
Menu Design Customization ........................................................................................................ 54
Interface Text Customization (Language Bundles) 57
Understanding Interface Text (Language) Bundles ..................................................................... 58
Interface Text Customization ....................................................................................................... 60
Language Bundle Compiler ......................................................................................................... 62
Localization 64
Adding New Languages To Parallels H-Sphere .......................................................................... 65
Translating Language Bundles.......................................................................................... 65
Adding New Language Bundles Into Parallels H-Sphere ................................................. 66
With packages ................................................................................................................... 66
Compiling bundles ............................................................................................................. 66
Changing Language of Context Help .......................................................................................... 68
Updating Translation of Parallels H-Sphere Interface ................................................................. 69
XML Customization 70
Merging XML Configuration Files ................................................................................................ 71
XML Manager .............................................................................................................................. 73
XML Manager Implementation .......................................................................................... 73
XML Merge Processing Instructions.................................................................................. 75
Creating Plan Wizards with XML ................................................................................................. 77
Introduction ........................................................................................................................ 77
Adding a New Wizard to the List of Plan Wizards ............................................................. 78
Defining Plan Wizard ......................................................................................................... 78
Adding Custom CP Cron Jobs ..................................................................................................... 84
CP Cron XML Configuration .............................................................................................. 86
Adding Custom Promotion Validators and Calculators ............................................................... 88
Adding Custom MS Exchange Plans into Parallels H-Sphere .................................................... 91
Customizing E-Mail Notification List ............................................................................................ 94
Using Variables in Parallels H-Sphere E-Mail Notifications .............................................. 96
Packages 112
Building Packages ..................................................................................................................... 113
Step 1. Preconfiguration .................................................................................................. 115
Step 2. Configuration ....................................................................................................... 117
Step 3. Package Builder .................................................................................................. 119
Building Language Packages .................................................................................................... 119
Java Tools For Packaging ......................................................................................................... 122
Package Configurator ...................................................................................................... 122
Package Builder .............................................................................................................. 124
Package Installer ............................................................................................................. 125
Package Uninstaller ........................................................................................................ 125
Package Checker ............................................................................................................ 126
Package XML Configuration File (_pkg.xml) ............................................................................. 126
Template Customization With Packages ................................................................................... 129
XML Customization With Packages .......................................................................................... 130
Package Installation................................................................................................................... 132
Package Uninstallation .............................................................................................................. 133
Package Upgrade ...................................................................................................................... 134
Preface 5
Appendix 135
Logging in as the cpanel User ................................................................................................... 136
Restarting Parallels H-Sphere Control Panel ............................................................................ 136
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.
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.
In this chapter:
Understanding Parallels H-Sphere Templates ................................................... 11
Customizing Templates Step by Step ................................................................ 17
Compiling Templates With Client-Side Form Validation ..................................... 19
Customizing Skeleton Templates ...................................................................... 20
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:
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/
12 Template Customization
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/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.
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
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.
~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.
16 Template Customization
~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/
Template Customization 17
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 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:
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 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:
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.
20 Template Customization
4. Run ./configure in the templates directory. This will create
Makefile's for all of designs.
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 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:
<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 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
Tax
Exemption
Approved
Notification
(Moderated
Accounts)
tax_exemption_approved_n
ew.txt
to new customers
signed up to tax
exemption plan,
awaiting moderation
Tax
Exemption
Rejected
Notification
(Moderated
Accounts)
tax_exemption_rejected_n
ew.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.t
xt
to customers on tax
exemption approval
Tax
Exemption
Rejected
Notification
(Live
Accounts)
tax_exemption_rejected.t
xt
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:
<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)
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_osr
s.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'.
Loading...