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 explains how to customize plan wizards by modifying plan wizard XML configuration files.
H-Sphere supports XML-based plan wizards.
Wizards are located in the ~cpanel/shiva/psoft/hsphere/plan/wizard/xml directory.
Location can be altered by setting PLAN_WIZARDS_DIR in
~cpanel/shiva/psoft_config/hsphere.properties to a target directory.
PLAN_WIZARDS_DIR = /hsphere/local/home/cpanel/shiva/psoft/hsphere/plan/wizard/xml
The list of wizards is defined in the plan_wizards.xml file, which is by default located
in the plan wizards directory.
The file's name and location is set in the PLAN_WIZARDS parameter in hsphere.properties
(the full path to the file is required):
PLAN_WIZARDS = /hsphere/local/home/cpanel/shiva/psoft/hsphere/plan/wizard/xml/plan_wizards.xml
When you customize plan wizard XMLs make sure the PLAN_WIZARDS_DIR and PLAN_WIZARDS parameters
are set in hsphere.properties.
You can also customize plan wizard XML files by means of H-Sphere packages.
Adding A New Wizard To The List Of Plan Wizards
To add a new wizard, add the following line to the list of wizards in plan_wizards.xml:
<wizard name="NAME" description="DESCRIPTION"/>
- name - the name of a plan's XML file. It must be specified without .xml extension
(.xml will be appended automatically).
The file contains plan wizard specification.
- description is a language bundle label defined in
It should not contain the "lang." prefix.
Read more about
bundles in Customization Guide.
<wizard name="unix" description="planeditor.res_unix"/>
Here, Unix plan XML definition file is ~cpanel/shiva/psoft/hsphere/xml/unix.xml, and the plan's
description is set in the lang.planeditor.res_unix label in
Defining Plan Wizard
Plan wizard definition starts with creating a new .xml file.
See unix.xml as
an example of planwizard definition.
The root XML tag is:
<PlanWizard name="NAME" description="DESCRIPTION">
- name - should match the filename (without .xml prefix)
and the corresponding name attribute in plan_wizards.xml.
- description - language bundle with plan wizard description
from hsphere_lang.properties without "lang." prefix.
The PlanWizard construction includes the following tags:
DefaultName is the name that will serve as the default plan name in creating plans.
DefaultValues is a construction where the plan's default values are set. Usually, the
add _template and menuId values are added here.
The categories tag defines plan resources.
Resources are grouped into categories and described within the <category> tags.
Each category tag can have the description attribute which is optional.
Categories are used in plan wizard screens to group resources into logical groups.
The following tags are used inside the category tag:
The <resource> tag defines the resource class, name, description
and includes the following attributes if necessary:
- name - name of the resource, like account, mailbox;
- class - name of the resource class;
- help (optional) - description of the resource from hsphere_lang.properties file;
- unit (optional) - units for the resource, MB or GB;
- required (optional) - if it is set to 1,
the resource is required in the plan and regarded to be automatically
included to the plan;
- include (optional) - if it is set to 1,
the resource will be marked as included by default to the plan wizard;
- active (optional) - if active parameter is not set,
no active checkbox will be available for the resource.
Otherwise, if it is set to 1, resource will be marked as active by default.
Any other value - active checkbox will be present but not checked;
- noprice (optional) - if 1, the wizard will not prompt to enter pricing for the resource;
- ifresource (optional) - list of resources separated by the vertical bar '|' character.
If any of the resources are included to or required in the plan, this resource will also be included.
Inside the <resource> construction,
the <field> tag allows to get more info from the user for a resource specified.
The data will be returned as a part of HTTP request and can be used later via the #name parameter.
- name - name of the field, you can retrieve it later via the #name parameter;
- label - label from hsphere_lang.properties, refers to a caption to be displayed in the wizard;
- type - type of the field to be displayed: textbox|checkbox.
If type = "textbox", the following attributes are set:
- value - the default value;
- planvalue - name of the resource plan value (value defined in the plan);
While editing the plan, the wizard will try to retrieve this value and show it as the textbox value;
- size - size of the textbox;
- check - yafv check (not implemented yet).
<field type="textbox" name="max_conn" label="planeditor.max_connections" value="10"
If type = "checkbox", the following attributes are set:
- value - value of the checkbox;
- planvalue - name of the resource plan value (value defined in the plan).
While editing the plan, the wizard will try to retrieve this value and, if it matches to the value, checkbox will be checked.
The <LogicalGroup> tag defines a logical server,
allows user to select one logical server if several are present.
- name - name of the group;
- type - type of the group;
- help - help message;
- default - default group.
<LogicalGroup name="unix_real" type="unix_real" help="admin-editwizard-o_lsgunix_real"/>
The <ifresource> element allows to
group resources/LogicalGroup and activate them for the plan,
only if the resource is enabled via global resources, or for the reseller plan.
- name - resource name. Will be checked by admin.isResourceDisabled;
- description - description of the resource from hsphere_lang.propeperties.
The <ifgroup> element works in the same way as
ifresource but checks if the server group is available.
- name - server group name;
- else - resource name to show as unavailable.
The <resources> element is used to define resources and their initialization sequence.
Resources are defined in the resources element in the custom res_RESOURCE_NAME child tag where RESOURCE_NAME is
the resource mnemonic identifier.
For example, for the unixuser resource the tag would look like:
The <mod> tags determine what mods will be defined in the plan.
- name - name of the mod; "" if missing;
- ifresource - list of resources delimited with '|'.
If any of those resources will be available in plan, i.e., required,
selected through the Web as included, or derived as included,
the mod will be defined in the plan, otherwise it won't be defined.
Inside the mod element the following tags are structured:
The <initresource> tags inside mod constructions define what child resources
are created with the creation of this resource.
The <initvalue> tag defines initial plan values.
Initvalues are passed to the resource constructor as a Collection, and you need to
be very careful with their order. Initvalue names aren't used as keys.
Typically, the constructor would read initvalues like this:
Iterator i = initValues.iterator();
value1 = (String) i.next();
value2 = (String) i.next();
- type - one of the following types as defined in psoft.hsphere.plan.InitValue:
- static - the value enclosed in the tag.
- field - the value taken from the submitted form by the name enclosed in the tag.
- relative - the value obtained with the 'TemplateModel get(String key)' method of
the resource chain from the current resource up the resources tree.
The search stops upon finding the first not null value.
- absolute - the value obtained with the 'TemplateModel get(String key)' method of
the current resource. Unlike 'relative', it allows geting values of TemplateHash
values returned by 'TemplateModel get(String key)'.
Example: Let's say a resource returns a hash accessible from TemplateModel
get(String key) by key 'a'. This hash, in its turn, contains a value
accessible by key 'b'. To access this value, you need to set initvalue to 'a.b'.
- relative_rec - implements embedding as in 'absolute' with support of ascending
recursion as in 'relative'.
- absolute_rec - implements embedding, but calls 'TemplateModel get(String key)' of
the top resource in the tree - the account.
- hostgroup - is used to get a random HostEntry object within the given logical
server group. The value of the group is stored as a plan value with id '_HOST_' + value of the
current init value.
- plan_free - returns free units for the current resource if applicable.
- plan_value - returns plan value accessible by the current initvalue as key.
- label - is not used anymore, can be considered a comment.
The initvalue tag content is a string.
If it starts with #, the value will be used as a name of the parameter which is passed via http request.
Here are several pre-defined variables that could serve as the initvalue tag content:
<initvalue type="static" label="Home Directory">#homedir</initvalue>
The <if> tag allows to include
initresources or initvalues under a certain condition. For example:
<if type="eq" left="#mixedip" right="dedicated">
<true><initresource name="ip" mod="dedic_no_a"/></true>
<false><initresource name="ip" mod="shard_no_a"/></false>
Here, the value of the mixedip parameter that is passed via HTTP request is checked
for being equal to the value of the dedicated parameter.
The <values> element includes the <value> constructions inside.
The <value> tag defines the resource values in the plan.
- name - mnemonic identifier.
If the tag content string starts with #, the value will be used as a name of
the parameter that is passed via HTTP request.
The <special> element is used to define some additional settings such as tld pricing.
It allows to add checkbox to any resource and, if checkbox is selected, to include another template.
To define the special attribute for a resouce, create the
<res_RESOURCE_NAME> tag (like <res_opensrs>) inside the <special> element
(you can have multiple tags insdie special section).
Inside <res_RESOURCENAME> tag, the <field> tag is used to define the HTML field.
- type - checkbox type;
- name - name of the checkbox field;
- label - label from hsphere_lang.properties referrring to the field caption;
- value - value of the checkbox;
- checked - equals 1 if checked.
Inside the <field> element, the <include> tag defines a template
to be included.
- ifvalue - a value to match against the field; if it matches, the template is included;
- name - the name of the template to be included.
<field type="checkbox" name="leave_osrs_prices"
label="planwizard.leave_osrs_prices" value="1" checked="1">
<include ifvalue="" name="admin/wizards/tldprices.html"/>