Parallels H-Sphere Documentation Customization Guide

 

Understanding H-Sphere Templates

 
 

Related Docs:   Template Customization

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 ~cpanel/shiva/psoft_config/hsphere.properties file:

TEMPLATE_PATH = /hsphere/local/home/cpanel/shiva/shiva-templates/

2) 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 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:

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. 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.

 

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 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 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.

 

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.

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/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):

  • 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 ~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.

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.

 

Template Directory Structure

  • ~cpanel/shiva/shiva-templates/<design> - template directory for one of the 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.
  • ~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:

  1. ~cpanel/shiva/custom/templates/<design>/replacements/
  2. ~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:

  1. ~cpanel/shiva/custom/templates/<design>/
  2. ~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:

  1. ~cpanel/shiva/custom/templates/common/replacements/
  2. ~cpanel/shiva/shiva-templates/common/replacements/
  3. ~cpanel/shiva/custom/templates/common/
  4. ~cpanel/shiva/shiva-templates/common/

Related Docs:   Template Customization



© Copyright 2017. Parallels Holdings. All rights reserved.