|
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
~cpanel/shiva/psoft_config/hsphere.properties file:
TEMPLATE_PATH = /hsphere/local/home/cpanel/shiva/shiva-templates/
2) Default (common) design directory
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:
USER_TEMPLATE_PATH=/hsphere/local/home/cpanel/shiva/custom/templates/
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.
Starting with v.2.4, 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.
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.
Control Templates
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.
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/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.
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 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):
- 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.
Note: Text-Based is an obsolete design completely removed from H-Sphere
in version 2.4.
- xcp - the XPressia design implemented in version 2.4
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 is located in the
~cpanel/shiva/psoft/hsphere/ directory.
See Skin and Icon Set Customization
document for description of designs and their modification rules.
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.
Template Directory Structure
- ~cpanel/shiva/shiva-templates/common/JS - JavaScript functions (used for all designs)
- ~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/<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
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/
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:
- ~cpanel/shiva/custom/templates/<design>/
- ~cpanel/shiva/shiva-templates/<design>/
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/
|
