H-Sphere Documentation Customization Guide

For more information contact us at info@psoft.net

Template Customization

 

Related Docs:  

Interface Controls and Colors Skin and Icon Set Customization Left Menu Customization Providing Multilingual Support Compiling Templates

This document will guide you through:

Throughout this document we will often relate to the shiva/ directory, which is located in the /hsphere/local/home/cpanel/ cpanel user home directory. Hereafter, we will refer to it as shiva.

WARNING:
1. Advanced customization may produce unpredictable results after updating H-Sphere, since updates affect the template structure and the page generation.
2. Advanced customization performed by H-Sphere customers is done at their own risk and is not supported by the PSoft team.
3. You may order customization from the PSoft team. Such customization is supported hereafter. Please contact sales@psoft.net for pricing details.

 

Customizing Templates

Templates are HTML documents that contain instructions for including dynamically-generated data. In other words, context data is put into the templates to create relevant H-Sphere pages. Templates are modified to change the web page layout, e-mail notifications, and context help texts.

IMPORTANT:
Template customization affects ALL H-Sphere accounts, regardless of their plans!
In terms of H-Sphere customization, only two types of accounts are customized, regardless of plans: admin accounts which are 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.
 

Location of Templates

The default templates are located on the CP server in the shiva/shiva-templates/ directory in the /hsphere/local/home/cpanel/ cpanel user home directory.

 

Types of Customizable Templates

The following types of templates can be customized:

  • Web page layout: you may find the pairs of .html and .html.in files - two types of templates that are responsible for displaying web pages.

    • *.html.in templates are templates with client-side form validation. It is generally preferrable to modify these templates, and you should do this if you perform serious changes in template structure, for example, when you change your default DocumentRoot from the shiva/shiva-templates directory to your custom directory, or when you change the default location of images. However, *.html.in template customization is a sophisticated procedure, as it requires re-compilation before modifications would take effect. Read more about compiling templates with client-side form validation.

    • *.html templates are templates for server-side form validation. It is easier to customize such templates, as they don't require recompilation, and any modification takes effect immediately. It is sufficient to customize *.html templates if you don't change default template settings.

  • E-mail notifications: system e-mails are also generated from templates and must be changed according to the instructions laid out in this document. E-mail templates are located in the shiva/shiva-templates/common/mail directory and have .txt extension. See the list of system e-mail templates.

  • Online help: special templates, each with a topic header and a body. They can be modified according to the procedure described in this section. Online help files are located next to templates in the 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 providing context help in different languages.

 

How To Find Templates That Need To Be Modified

Depending on H-Sphere design, template file is located in these standard design subdirectories of the shiva-templates directory:

  • common - the so-called left-menu interface design;
  • nomenu - the so-called no-menu interface design;
  • text_based - the so-called text-based interface design: no-menu design without icons.

Read more about H-Sphere designs in Skin and Icon Set Customization Guide.

a) Header:

design/top.html - template responsible for displaying the Control Panel header. Depending on design, this template is located in the three above mentioned standard design directories.

b) Footer:

design/bottom.html - template responsible for displaying the control panel footer. Depending on design, this template is located in the three above mentioned standard design directories.

c) Other Templates:

To find out the name and location of the template that needs to be modified, do the following:

  1. View the source of the web page to be modified.
  2. At the beginning of the page, find the tag that would have the following format:
    <!-- BEGIN ./path_to_template/template_file.html -->
  3. Depending on design, this file is located in the following subdirectories of the shiva-templates directory:
    common/path_to_template/template_file.html
    nomenu/path_to_template/template_file.html
    text_based/path_to_template/template_file.html

Example: The page displaying the list of plans in the INFO->Plan Creation Wizards menu has the following tag with template name:
<!-- BEGIN ./admin/plan_wizards.html -->
Thus, depending on the design, the template is located in the following directories:
/hsphere/local/home/cpanel/shiva/shiva-templates/common/admin/plan_wizards.html
/hsphere/local/home/cpanel/shiva/shiva-templates/nomenu/admin/plan_wizards.html
/hsphere/local/home/cpanel/shiva/shiva-templates/text_based/admin/plan_wizards.html

 

Template Customization Pre-Requisites

  • Before you do any customization, log in as the cpanel user, e.g., under root:
    # su - cpanel
    To implement customization correctly, all template files and directories should have cpanel:cpanel ownership, and the make directive which is performed to rebuild *.htmltemplates should be run ONLY under the cpanel user.

  • 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

Step 1. On the CP server, login as the cpanel user under root:
# su - cpanel

Step 2. In shiva/, create directory custom/templates/.

Step 3. Copy the templates you would like to substitute into shiva/custom/templates/ preserving their file paths relative to this directory. E.g. If you are going to substitute the
shiva/shiva-templates/not_recomended/to_change/FILE, copy it to
shiva/custom/templates/not_recomended/to_change/FILE. In case of mail templates, copy
shiva/shiva-templates/common/mail/mail_template to
shiva/custom/templates/common/mail/mail_template.

The original configuration can be restored without server restart by simply deleting your custom files from the shiva/custom/templates 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!

Step 4. Make sure the file is owned by cpanel:cpanel.

Step 5. Modify the templates you have copied to the shiva/custom/templates/ directory. Please carefully follow the instructions on Interface Controls and Colors and Skin and Icon Set Customization. To edit interface texts, please refer to the section below.

Step 6. Now that you have had the templates edited, get them used instead of the defaults. In the file shiva/psoft_config/hsphere.properties find the USER_TEMPLATE_PATH line. Here, enter the full name of the directory with your custom templates, e.g. /hsphere/local/home/shiva/custom/templates/. Important: 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.

Step 7. Log in as root and restart H-Sphere. You don't need to restart H-Sphere if you did nothing on step 4. If you don't know how to restart your H-Sphere, click here.

 

Editing Interface Texts
(version 2.07 and higher)

This section explains how to override original menu items and labels for the admin and user control panels with custom texts. E-mail notifications and context help texts are changed according to the procedure described in the Customizing Templates paragraph.

Interface texts are stored in the form of key=value sets called resource bundles, or bundles, where key is the text mnemonic identifier, and value is the text itself that may vary depending on language. Templates include mnemonic identifiers and thus generate language-independent dynamic content.

Default menu items and labels are set in the following files of the shiva/psoft/hsphere/lang/ directory:

- hsphere_lang.properties - template and tooltip texts;
- menu.properties - the navigation menu texts;
- messages.properties - H-Sphere system messages.

Interface texts in other languages are stored in the same directory in the corresponding files:

- hsphere_lang_LANG.properties
- menu_LANG.properties
- messages_LANG.properties

where LANG is a language identifier. For more details, please refer to the Providing Multilingual Support documentation.

WARNING:
Do not make any changes to these default lang files!
You may need them to restore the original setup, and you will lose all your changes with the next upgrade.

To alter original menu items and labels, do the following:

Step 1: Log in as cpanel user:
su - cpanel
All modified files should have the cpanel:cpanel ownership.

Step 2: Create the custom bundle directory shiva/custom/bundles/. If this directory already exists, skip this step.

Step 3: In the listed files, find the string you want to modify. Next, in the newly created directory, create a new empty file with exactly the same name as the one with the original string. For example, you are going to change the label Shell Access to SSH Access. It is stored in the shiva/psoft/hsphere/lang/hsphere_lang.properties file. Create the file shiva/custom/bundles/hsphere_lang.properties.

Step 4: Copy the line with the identifier and the value you want to change into the new file and change its value the way you want. You should use two single quotes (apostrophes) instead of one in labels containing curly brackets, such as {0}. For example:
search.view_invoice = View Client's Invoice
but
billing.del_no = No, I don''t want to delete {0}

WARNING:
Don't copy the texts you are not changing! This will override the default settings, and you will not see the changes that come with new versions!

Step 5: Make sure the file is owned by cpanel:cpanel.

Step 6: Now you need to declare the custom bundles. In the hsphere.properties file, uncomment the line that corresponds to the file you have created:

CUSTOM_TEMPLATE_BUNDLE = custom.bundles.hsphere_lang
CUSTOM_MENU_BUNDLE = custom.bundles.menu
CUSTOM_USER_BUNDLE = custom.bundles.messages

Step 7: Create two symlinks in your document root:
hsphere_lang_en.properties to hsphere_lang.properties and
menu_en.properties to menu.properties

Step 8: Log in as root and restart H-Sphere. You don't need to restart H-Sphere if you did nothing on step 4.


Related Docs:  

Interface Controls and Colors Skin and Icon Set Customization Left Menu Customization Providing Multilingual Support Compiling Templates



Home   Products   Services   Partners   Support   News   Contact   Forum
© Copyright 1998-2003. Positive Software Corporation.
All rights reserved.