Last modified: 28 Dec 2007
WARNING: This documentation covers Parallels H-Sphere versions up to 3.1. For the latest up-to-date Parallels H-Sphere documentation, please proceed to the
official Parallels site.
What Are Templates
H-Sphere templates is basically what lays behind the H-Sphere Control Panel Web interface.
For the most part, templates are written using
Freemarker Java processing language
for dynamic content generation. Currently, version 1.7.5 of Freemarker is used.
Location of Templates
1) Template root directory
H-Sphere template root directory is by default /hsphere/local/home/cpanel/shiva/shiva-templates.
It is set by the TEMPLATE_PATH parameter in the
TEMPLATE_PATH = /hsphere/local/home/cpanel/shiva/shiva-templates/
2) Default (common) design directory
Design, or skin, is the Control Panel GUI representation.
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 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!
3) Custom template directory
Custom template directory is usually /hsphere/local/home/cpanel/shiva/custom/templates.
Its location is set in hsphere.properties:
Custom templates directory structure should
correspond with the default template root directory (shiva-templates) tree. However,
you should be aware that templates in the custom template directory override
the corresponding templates in the default template directory, thus all
modifications and new features in existing default templates coming with new 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 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
list of the system e-mail templates.
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
Web Interface Templates
Templates for generating Control Panel interface pages are of the following types:
main templates, control templates,
submit templates, function templates,
and some special purpose templates.
There are also templates for generating context help pages.
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
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
Contol templates, or controls, are responsible for generation and management of
forms in the working area of 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:
- .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.
- 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 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.
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
- ~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/shiva-templates/<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 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 H-Sphere interface.
Also read about
context help in different languages.
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 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 and
system e-mail notification templates,
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 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.
If a certain template is not found for a particular design,
H-Sphere gets that template in the common directory.
The default design configuration file design_config.xml is located in the
See Skin and Icon Set Customization
document for description of designs and their modification rules.
Replacements are templates that override basic
templates for particular plans. Replacements' root directory for each design is the
Replacements are located in separate subdirectories
as the Template Directory parameter, relative to the replacement directory.
H-Sphere first searches for a template in the
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.
Template Directory Structure
- ~cpanel/shiva/shiva-templates/<design> - template directory for one of the H-Sphere basic
- ~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.
- template replacements
overriding templates in corresponding subdirectories for that design.
- ~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
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:
If the template is not found in replacements, H-Sphere searches in the design directory, first in
among the custom templates, then amonng the corresponding default templates:
If the template is not found for this design,
the search continues in the same sequence in the common design template directory: