Parallels H-Sphere Documentation Developer Guide


XML Customization With Packages


Related Docs:   Building Packages Template Customization With Packages

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.

This document dwells on building H-Sphere packages to customize XML configuration files.

The following H-Sphere components are configured by means of XML files:

Component Property
Default Location
CP Skins (Designs) DESIGN_SCHEME_CONFIG /hsphere/local/home/cpanel/shiva/psoft/hsphere/design_config.xml
CP Menu MENU_CONFIG /hsphere/local/home/cpanel/shiva/psoft/hsphere/menu.xml
CP Crons CRON_CONFIG /hsphere/local/home/cpanel/shiva/psoft/hsphere/cron_config.xml
Online (Context) Help HELP_CONFIG,
Promotion Validators And Calculators PROMO_CONFIG /hsphere/local/home/cpanel/shiva/psoft/hsphere/promotion/xml/promotions.xml
Merchant Gateways MERCHANT_GATEWAYS_CONF /hsphere/local/home/cpanel/shiva/psoft/hsphere/merchants.xml
Domain Registrars REGISTRAR_CONF /hsphere/local/home/cpanel/shiva/psoft/hsphere/registrar.xml
E-Mail Notifications USER_EMAILS /hsphere/local/home/cpanel/shiva/psoft/hsphere/user_emails.xml


Some custom XML files can be merged with default XMLs by means of XML merger. Instead of moving and changing a default XML file, a small custom file is created containing necessary changes and its location is specified in in the parameter with the "CUSTOM_" prefix added to the default parameter name, e.g.:

MENU_CONFIG = /hsphere/local/home/cpanel/shiva/psoft/hsphere/menu.xml
CUSTOM_MENU_CONFIG = /hsphere/local/home/cpanel/shiva/custom/xml/menu.xml


Building Packages With Custom XMLs

1. Log into CP server as cpanel user

1. Create Custom XML files

Custom XML files should contain only parts to be added to or to modify default XMLs. During the package installation these custom files will be merged with default XMLs. Please refer to the XML Manager guide for examples.

2. Run Package Configurator

Run package configurator in the package directory you created with the following options, at least:

  • --with-prefix=path/to/package/directory: specify a target directory (relative to the current directory) where all package files will be collected and the package will be configured. We will call it package directory later in the text.
    Hint: You may create a special directory with corresponding package directories where you assemble package source files. For example, it may be ~cpanel/shiva/custom/packages.
  • --with-xmls[=path/to/xml/directory]: specify directory with custom XML files. Note that if you don't specify the directory, the empty src/pkg_xmls directory will be created in the package directory and you will need to copy custom XML files there manually.
  • --with-properties[=path/to/package/properties/directory]: this option is required to include custom XML files to the package properties in order to merge custom XMLs with default XMLs on package installation. If you don't specify the directory, the empty src/pkg_config/ file will be created in the package directory.

Thus, package configurator's command line will look like:

$ su -l cpanel
bash-2.05a$ java --with-prefix=/hsphere/local/home/cpanel/shiva/custom/packages/MyPackage --with-properties --with-xmls

3. Configure the Package

To include custom XMLs into the package configuration, add corresponding parameters into the package properties file:

  1. Go to the src/pkg_config directory of the package directory (hsphere/local/home/cpanel/custom/packages/MyPackage in the above example).
  2. Edit the file. It will be empty if you did not specify the path to the package properties file in the --with-properties option of package configurator.
    • You don't need to copy all contents of the default file to your package properties file. Only add custom parameters that will be merged with the default ones when the package is installed.
    • In the package properties file, specify just the names of the XML config files to be customized, without paths to the. For example, to include changes in menu and designs, just add these lines to the properties file:
      # Custom design
      # Custom menu
      Parameters corresponding to each XML configuration file are given in the above table.

After you have configured package properties, proceed to other package configuration options required.

4. Run Package Builder

Run package builder to build the package, for example:

java --with-source=/hsphere/local/home/cpanel/custom/packages/MyPackage

The package will be assembled to the .hsp Jar file in the current directory.

5. Install the Package

Login as cpanel and run package installer, for example:

java --package=./MyPackage

Related Docs:   Building Packages Template Customization With Packages

© Copyright 2017. Parallels Holdings. All rights reserved.