Design XML Configuration

H-Sphere design configuration is represented in the file, which can be found by default in the /hsphere/local/home/cpanel/shiva/psoft/hsphere/ directory. You can customize this XML configuration to add your own designs, color schemes, colors and images.

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

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)

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

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

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.

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 element 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:

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

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