Parallels H-Sphere Documentation Customization Guide


Skin And Icon Set Customization


Related Docs:   Template Customization Interface Controls and Colors Menu Customization Adding Custom Icons

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.

H-Sphere interface design has a broader meaning than just configuration of certain color schemes and the corresponding icon sets, what is called the skin. It also determines the set of skins available for this design, specifies the sets of icons in the Quick Access page and enables to override the standard settings with the custom ones.

To provide multiple design support, H-Sphere uses the design_config.xml file, which can be found in the /hsphere/local/home/cpanel/shiva/psoft/hsphere/ directory. Its structure is explained in the Design XML Configuration guide.

The current document shows you how to customize this file to add your own designs, color schemes, colors and images. For this, you need to:

  1. customize design_config.xml
  2. implement custom design templates

1. Design XML Customization

A designer should have access to the H-Sphere server as the "cpanel" user. To implement customization correctly, all template files and directories should have cpanel:cpanel ownership.

Important: Since 2.5 RC 3 and up, templates, images, CSS and JavaScript files and directories must have cpanel:httpdcp ownership.

We don't recommend you to modify the default ~cpanel/shiva/psoft/hsphere/design_config.xml file. These modifications will be lost with the next H-Sphere updates.

There are the following ways of customizing design XML configuration:

  1. With packages

    You can customize design_config.xml by means of packages. In this case, within a package you create custom XML file that will be merged with default XML configuration.

  2. Merging custom XML configuration

    Instead of creating a package, create a custom XML configuration file to be merged with the default XML configuration and a custom package XML if installed.

  3. Overrriding default XML configuration with custom XML configuration

    You create the custom design configuration file and perform modifications there:

    1. Login to cpanel user under root:

      su -
      su -l cpanel

    2. copy the standard design_config.xml file to a certain custom directory (it may be /hsphere/local/home/cpanel/shiva/custom/xml):

      cp ~cpanel/shiva/psoft/hsphere/design_config.xml ~cpanel/shiva/custom/xml/design_config.xml

    3. make changes into the custom design_config.xml structure.
    4. in ~cpanel/shiva/psoft_config/, change the DESIGN_SCHEME_CONFIG variable to point to this new file:

      DESIGN_SCHEME_CONFIG = /hsphere/local/home/cpanel/shiva/custom/xml/design_config.xml


2. Implementation of Custom Design Templates

Custom design templates are created in the ~cpanel/shiva/custom/templates custom template directory. In order to implement these custom designs, the symlinks to them should be put into the Apache DocumentRoot directory which is set by default to the ~cpanel/shiva/shiva-templates standard templates directory.

However, on the subsequent H-Sphere update all symlinks in ~cpanel/shiva/shiva-templates would be lost, and custom designs would not be displayed correctly.

To avoid this, we suggest to use another directory as DocumentRoot and to create there the symlinks to ALL design directories, for both custom designs and the H-Sphere built-in designs.

Don't change the TEMPLATE_PATH variable in!
TEMPLATE_PATH points to the default template directory. If you change it, you won't see any updates in the default templates.

1. Create the /hsphere/local/home/cpanel/shiva/web directory.

2. Create the symlinks to the design directories using the ln -s command.

You should have something similar to this:

bash-2.05a$ pwd
bash-2.05a$ ls -la


lrwxrwxrwx 1 cpanel cpanel 55 Jun 4 08:55 common -> /hsphere/local/home/cpanel/shiva/shiva-templates/common
lrwxrwxrwx 1 cpanel cpanel 46 Jun 2 13:39 counter -> /hsphere/shared/SiteStudio/public_html/counter
lrwxrwxrwx 1 cpanel cpanel 47 Jun 2 13:39 custom-images -> /hsphere/local/home/cpanel/shiva/custom/images/
lrwxrwxrwx 1 cpanel cpanel 50 Jun 2 13:39 custom-templates -> /hsphere/local/home/cpanel/shiva/custom-templates/
lrwxrwxrwx 1 cpanel cpanel 48 Jun 2 13:40 guestbook -> /hsphere/shared/SiteStudio/public_html/guestbook
lrwxrwxrwx 1 cpanel cpanel 55 Jun 2 13:42 IMAGES -> /hsphere/local/home/cpanel/shiva/shiva-templates/IMAGES
lrwxrwxrwx 1 cpanel cpanel 46 Jun 2 13:40 masonry -> /hsphere/shared/SiteStudio/public_html/masonry
lrwxrwxrwx 1 cpanel cpanel 55 Jun 4 08:55 nomenu -> /hsphere/local/home/cpanel/shiva/shiva-templates/nomenu
lrwxrwxrwx 1 cpanel cpanel 43 Jun 2 13:40 poll -> /hsphere/shared/SiteStudio/public_html/poll
lrwxrwxrwx 1 cpanel cpanel 48 Jun 2 13:41 shiva-templates -> /hsphere/local/home/cpanel/shiva/shiva-templates
lrwxrwxrwx 1 cpanel cpanel 59 Jun 4 08:55 text_based -> /hsphere/local/home/cpanel/shiva/shiva-templates/text_based
lrwxrwxrwx 1 cpanel cpanel 62 Jun 2 15:19 YourDesign1 -> /hsphere/local/home/cpanel/shiva/custom/templates/YourDesign1
lrwxrwxrwx 1 cpanel cpanel 62 Jun 2 15:19 YourDesign2 -> /hsphere/local/home/cpanel/shiva/custom/templates/YourDesign2

Here, the counter, guestbook, masonry, and poll directories are SiteStudio-related directories; YourDesign1 and YourDesign2 are custom design directories.

3. Make the /hsphere/local/home/cpanel/shiva/web directory in the DocumentRoot directory.

To do this, in the ~cpanel/apache/etc/httpd.conf Apache configuration file change the DocumentRoot global definition line:

DocumentRoot "/hsphere/local/home/cpanel/shiva/shiva-templates"

to the following line:

DocumentRoot "/hsphere/local/home/cpanel/shiva/web"

Then, delete all other instances of the DocumentRoot definition (for virtual hosts) in this file. Also, delete all DocumentRoot definitions in all configuration files located in the ~cpanel/apache/etc/sites directory.

4. Logout from cpanel back to root and restart H-Sphere.

Related Docs:   Template Customization Interface Controls and Colors Menu Customization Adding Custom Icons

© Copyright 2017. Parallels Holdings. All rights reserved.