Template Customization

Last modified: 28 Dec 2007

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

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

Pre-Requisites

• Before you do any customization, log into CP server under root as the cpanel user.

  Notes:

  1. Template Ownership.
  Make sure templates have the cpanel:cpanel ownership. Mind, however, that since H-Sphere 2.5 RC 3 images, CSS and JavaScript files and directories have cpanel:httpdcp ownership and you must not change their ownership to cpanel:cpanel. H-Sphere 2.5+ updater checks and automatically sets correct ownership and permissions on respective default and custom files and directories (this does not refer to H-Sphere packages). We don't recommend changing manually the ownership and permissions of default templates!

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

Step-By-Step Template Customization Procedure

Step 1. On the CP server, log in as cpanel user.

Step 2. In the ~cpanel/shiva/ directory, create the custom template directory custom/templates/ if it doesn't exist.

Step 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/templates/

The directory name must end with a slash. Don't do anything if the directory name is already there.

Step 4. Copy the templates you would like to customize into shiva/custom/templates/, preserving their file paths relative to this directory. E.g., 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.

Step 5. (only before 2.5!) Make sure all custom template files have correct ownership.

Step 6. Modify the templates you have copied to the ~cpanel/shiva/custom/templates/ directory.

The following documents will be helpful:

- Interface Controls and Colors
- Skin and Icon Set Customization
- Edit Interface Texts

Important:

1) We don't recommend inserting the text directly into the templates. Use text labels defined in language bundles to ensure multilingual support.

2) H-Sphere uses the 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.

Step 7. Restart H-Sphere.