XML Customization With Packages

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

• The List of Customizable XML Configuration Files
• Building Packages With Custom XMLs

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

Note:

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 hsphere.properties 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/default.properties file will be created in the package directory.

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

$ su - cpanel
bash-2.05a$ java psoft.hsp.tools.PkgConfigurator --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 default.properties 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 hsphere.properties 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
     DESIGN_SCHEME_CONFIG=design_config.xml
     # Custom menu
     MENU_CONFIG=menu.xml
     
     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 psoft.hsp.tools.PkgBuilder --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 psoft.hsp.tools.PkgInstaller --package=./MyPackage