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. You can edit this file to add your own designs, color schemes, colors and images.

This document explains all important parts of the design configuration file, including:

• Icons
• Skill Icon Groups
• Icon Image Sets
• Common Images
• Color Types
• Designs (Skins)

Besides that, the document provides hints on

• Custom Design Implementation

Icons

By icon we mean an H-Sphere control that provides quick access to a certain functional page of the control panel. All H-Sphere icons are displayed only on the Quick Access page, which is based on the quick/quick_view.html template.

An icon description includes the following:
- id - the mnemonic system name of the icon
- url_param - typically, the name of the base template for the functional page this icon links to. Multiple url parameters are separated with the & delimiter
- rtype - the list of H-Sphere resource types whose availability determines whether the icon will be drawn. It may include simple resource types separated by semicolons and commas in the following way:

• res1 - simple resource type, icon will appear if the resource is available;
• res1,res2,res3 - group of resources where all of them must be available to show an icon (operation 'AND');
• res1; res2; res3 - icon will be shown if any of the resources is available (operation 'OR'). Example: rtype="webalizer; modlogan; urchin"
• res1,res2; res3,res4; res5,res6 - combination of groups where an icon will be shown if any of the groups - res1,res2 or res3,res4 or res5,res6 includes both available resources. If translated to C or Java, this would mean (res1 & res2) || (res3 & res4) || (res5 & res6)

One icon can have many visual representations. This means that it will have a different look depending on which icon image set was selected by the user. You can specify which icon image sets will be available for each individual design, e.g.:

  <allowed_icon_image_sets>
    <set id="wooden"/>
    <set id="square_set"/>
    <set id="cartoon_set"/>
    <set id="bubble_set"/>
  </allowed_icon_image_sets>

Skill Icon Groups

In terms of the H-Sphere interface visual settings, 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.

Skill icon groups determine the structure of the icon groups in the Quick Access page for these two types of accounts and are defined as follows:

<skill_icon_sets account_type="account_type">
  <skill_set id="standard" label="icon_skill_set.standard_account_type_l">
    <icon_group id="group_id" label="icongroups.group_id">
      <icon id="icon_id1"/>
    . . .
    <icon_group>
 . . .
 <skill_set>

 <skill_set id="advanced" label="icon_skill_set.advanced_account_type_l">
    <icon_group id="group_id" label="icongroups.group_id">
      <icon id="icon_id1"/>
          . . .
    <icon_group>
 . . .
 <skill_set>

 <skill_set id="simplified" label="icon_skill_set.simplified_account_type_l">
    <icon_group id="group_id" label="icongroups.group_id">
      <icon id="icon_id1"/>
    . . .
    <icon_group>
 . . .
 <skill_set>
<skill_icon_sets>

Account types: admin for admin accounts and user for user accounts.

Skill set ids are of the following types: usually, standard for the common ('left menu') interface, and advanced for the 'no menu' interface. simplified skill set may be chosen for any of the two types of accounts.

Icon groups are defined within the skill_set element structure. The icon group id attribute corresponds to menu groups, such as Info, FTP, mail, etc., and is a mnemonic identifier of the icon group (mail, admin_mail, and the like).

icon_group construction enlists the set of icons which are displayed in this icon group. Each icon is defined in the icons construction described above in the previous section.

Icon Image Sets

By icon image set we mean the set of icons corresponding to a certain H-Sphere color scheme:

<icon_image_sets base_dir="/IMAGES">
  <icon_image_set id="image_set_id" label="iconsets.image_set_id" dir="relative_image_set_dir">
    <preview_image file="/IMAGES/previews/icons_default.gif" width="375" height="60"/>

    <image id="icon_id" file="filename_with_relative_path" width="xx" height="yy"/>
    . . .
  <icon_image_set>
  . . .
<icon_image_sets>

base_dir attribute defines the directory where the H-Sphere images, both standard and custom, are to be stored. Typically, it is the IMAGES directory in the Apache document root directory (usually, ~cpanel/shiva/shiva-templates).

Note: The base image directory is actually relative to the alternative directory for images which is located in the document root. This directory is set in the IMAGES variable in the hsphere.properties file. If it is not set there, base_dir contains the path relative to the document root.

icon_image_set element sets the list of images corresponding to a color scheme. Attributes:

• id attribute refers to mnemonic name of the color scheme. It is default for the default color scheme; cocoa, bubble and some other schemes go with H-Sphere installation, while others may be created manually.
• dir is the path relative to the base_dir directory. If it is empty, images are located in the base images directory.

preview_image tag refers to the preview image appeared in the H-Sphere Look and Feel interface when choosing the available design.

The following attributes are determined for the preview image:

• file - filename and path to the preview image relative to the document root directory.
• width, height - image width and height.

image - image description tag.

Please keep in mind that the image should be set for EACH color scheme. In order to add a new image, first, add the image definition to the icons tag, and then add image elements with the same id attribute to EACH icon_image_set element.

The following attributes should be set:

• id attribute value refers to the icon described in the icons section.
• file is the image filename with the path relative to the icon image set subdirectory of the image set basic directory.
  For example, if base_dir="/IMAGES" and dir="wooden", then images for wooden scheme will be located in /IMAGES/wooden directory. However, if dir="", then, to do so that H-Sphere would find, let say, a GIF image, you should set the file attribute as file="wooden/name_of_the_file.gif
• width, height - image width and height. Unless these parameters are not changed, the user custom image would be displayed by H-Sphere with this width and height, regardless of the image size parameters.

Common Images

Common images are the set of images that have the same look in all designs, such as, arrows, bullets, home icon, etc.

The common_images element structure is as follows:

<common_images base_dir="/IMAGES/">
  <image id="spacer" file="spacer.gif" width="1" height="1"/>
  <image id="arrow" file="arrow.gif" width="22" height="22"/>
  . . .
</common_images>

The base_dir attribute is defined in the same way as for the icon image sets.

The image id attribute is an image mnemonic name used in templates.

Color Types

Color types comprise all possible interface entities for which colors are set: basic text, background, header, menu, error messages, etc.

The following attributes are present in the color_type tag:

• id is a mnemonic color type identifier later used in designs description;
• label is a mnemonic id to the caption under which this color type is configured in the CP interface.

Designs

Design, or skin, is a GUI representation including certain icon image sets and color schemes. There are 3 basic H-Sphere designs:

• common is the left-menu design. All basic templates are made for this design scheme.
• nomenu is the design with no left menu. It is turned on as the default user design after the H-Sphere installation.
• text-based is the alternative look of the nomenu design where only captions with no icons are provided in the Quick Access menu page.

Attributes of the design element:

• id is a design mnemonic identifier: nomenu, common, text-based.
• label is a mnemonic id to the design name in the CP interface.
• template_dir is a directory relative to the document root directory where where template files for this design are located.
• default_color_scheme is the default color scheme identifier (see below, color_scheme tag description).

preview_image tag defines the design preview image settings. The structure is the same as for the icon image sets.

colors element defines all available colors for this design. They are taken by default for every color scheme. Individual color settings for each color scheme could be defined in the corresponding color_scheme constructions (see description below).

Color id attribute refers to the color type identifier (see Color types).

base_images is the set of images that look the same for all color schemes in this design. The base_images tag structure is the same as for the common images.

The image_sets element contains the settings for each image set enabled for this design. base_dir attribute points to the images directory (usually, IMAGES). The elelent includes the following tags:

• set_images element contains the list of images in a standard image description which are taken by default for this design.
• image_set tag contains image definitions for a color scheme to override the set_images default definitions. Here you may set an alternative directory where images for this color scheme will be searched, or modify settings so that an image will be taken from a file different from the default image file. image_set may contain image tags for images with alternative settings (for example, if the image file name is different from the default one).

  Attributes:
  - id - identifier for a color scheme (for example, default or cocoa);
  - label - color scheme label;
  - dir - alternative image directory relative to the base_dir directory; if it is empty the image search would be performed in the base_dir directory (usually, IMAGES).

  Example: If we need to change the banner.jpg image to the banner1.jpg image in the default color scheme so that this image would be searched in the base directory, the image tag should be inserted into the image_set construction in the following way:

  <image_set id="default" label="imagesets.default" dir=""/>
     <image id="banner" file="banner1.jpg" width="468" height="60"/>
  </image_set>
  		

allowed_skill_icon_sets tags are used to determine a skill icon set for user and admin accounts (see Skill icon groups):

  <allowed_skill_icon_sets account_type="user">
    <set id="standard"/>
  </allowed_skill_icon_sets>

allowed_icon_image_sets tags determine icon image sets that would be available for each account type (see Icon sets):

  <allowed_icon_image_sets account_type="admin">
    <set id="default"/>
  </allowed_icon_image_sets>

color_scheme sets page colors, image sets and icon image sets in this design.

Attributes:

• id - color scheme identifier (for example, blue_haze or default);
• label color scheme label defined in hsphere.properties;
• image_set - image set identifier (for example, blue_haze or default);
• icon_image_set - icon image set identifier (for example, blue_haze or default).

Color scheme element may include the color tags to set colors for this color scheme. If these colors are not set here, default colors would be taken from the colors tag definition for this design.

Example:

  <color_scheme id="marsh" image_set="marsh" icon_image_set="marsh" label="imagesets.marsh">
    <color id="logo_bgcolor" value="#C9D1CA"/>
    . . .
 </color_scheme>

Custom Design Implementation

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: We don't recommend you to modify the /hsphere/local/home/cpanel/shiva/psoft/hsphere/design_config.xml file. These modifications would be lost after each H-Sphere update. Instead, we suggest to create the custom design configuration file and perform modifications there:

1. copy the standard design_config.xml file to a certain custom directory (it may be /hsphere/local/home/cpanel/shiva/custom):
   cp /hsphere/local/home/cpanel/shiva/psoft/hsphere/design_config.xml /hsphere/local/home/cpanel/shiva/custom/design_config.xml
2. in /hsphere/local/home/cpanel/shiva/psoft_config/hsphere.properties, change the DESIGN_SCHEME_CONFIG variable to point to this new file:
   DESIGN_SCHEME_CONFIG = /hsphere/local/home/cpanel/shiva/custom/design_config.xml

Custom design templates are usually created in the /hsphere/local/home/cpanel/shiva/custom/templates 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 /hsphere/local/home/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.

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
/hsphere/local/home/cpanel/shiva/web
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 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. Restart H-Sphere.