Creating Plan Wizards with XML

This document explains how to customize plan wizards by modifying plan wizard XML configuration files.

Introduction

Parallels 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

Important: 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 Parallels 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"/>

Here,

• 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 ~cpanel/shiva/psoft/hsphere/lang/hsphere_lang.properties. It should not contain the lang.

Example:

<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 ~cpanel/shiva/psoft/hsphere/lang/hsphere_lang.properties.

Defining Plan Wizard

Plan wizard definition starts with creating a new .xml file. See unix.xml (http://hsphere.parallels.com/HSdocumentation/xmls/unix.xml) as an example of planwizard definition.

<PlanWizard>

The root XML tag is <PlanWizard>:

<PlanWizard name="NAME" description="DESCRIPTION">

Attributes:

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

<DefaultName>

DefaultName is the name that will serve as the default plan name in creating plans.

<DefaultName>name</DefaultName>

<DefaultValues>

DefaultValues is a construction where the plan's default values are set. Usually, the add _template and menuId values are added here.

<DefaultValues>

<value name="NAME1">VALUE1</value>

<value name="NAME2">VALUE2</value>

...

</DefaultValues>

<categories>

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.

<categories>

<category>

...

</category>

<category description="DESCRIPTION">

...

</category>

</category>

<resource>

The <resource> tag within the <category> construction 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 the 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.

<field>

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.

Attributes:

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

Example:

<field type="textbox" name="max_conn" label="planeditor.max_connections" value="10" planvalue="MAX_CONN" size="4" check="vPriceReq"/>

<LogicalGroup>

The <LogicalGroup> tag defines a logical server, allows user to select one logical server if several are present.

Attributes:

• name - name of the group;
• type - type of the group;
• help - help message;
• default - default group.

Example:

<LogicalGroup name="unix_real" type="unix_real" help="admin-editwizard-o_lsgunix_real"/>

<ifresource>

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.

Attributes:

• name - resource name. Will be checked by admin.isResourceDisabled;
• description - description of the resource from hsphere_lang.propeperties.

<ifgroup>

The <ifgroup> element works in the same way as ifresource but checks if the server group is available.

Attributes:

• name - server group name;
• else - resource name to show as unavailable.

<resources>

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:

<res_unixuser> </res_unixuser>

<mod>

The <mod> tags determine what mods will be defined in the plan.

Attributes:

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

<initresource>

The <initresource> tags inside mod constructions define what child resources are created with the creation of this resource.

Attributes:

• name - name of the resource. The system automatically checks if the resource is included in the plan before adding the initresource;
• ifactive - list of resources delimited with '|'. If any of these resources are selected in the plan wizard as activated, the initresource is created; otherwise, it won't be created, but will be available for creation by account owners.
• unique (optional) - a flag to mark the initresource whose mod will be changed in the plan wizard. For example, you may set initresource for the IP resource to shared IP, and then change shared IP to dedicated IP in the plan wizard in Control Panel. In this case, if you don't set the unique attribute in the initresource tag, another initresource record will be added to the system database and that will cause serious malfunctions.

  However, if unique="1" is set, no new initresouce record will be created when another mod is selected; instead, the existing initresource record will be modified.

Example:

<initresource name="ip" mod="shared" unique="1"/>

<initvalue>

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();

Attributes:

• 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 getting values of TemplateHash returned by the TemplateModel get method.

  Example: A resource returns a hash accessible from TemplateModel get(String key) by the key a. This hash, in its turn, contains a value accessible by the 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:

• $STOPGAP_ZONE
• $STOPGAP_PREFIX
• $INSTANT_ZONE
• $INSTANT_PREFIX

Example:

<initvalue type="static" label="Home Directory">#homedir</initvalue> <initvalue type="static">$INSTANT_PREFIX</initvalue>

<if>

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>

</if>

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.

<values>

The <values> element includes the <value> constructions inside.

<value>

The <value> tag defines the resource values in the plan.

Attributes:

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

Example:

<value name="SSI">1</value>

<special>

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 inside the special section).

<field>

Inside <res_RESOURCENAME> tag, the <field> tag is used to define the HTML field.

Attributes:

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

<include>

Inside the <field> element, the <include> tag defines a template to be included.

Attributes:

• ifvalue - a value to match against the field; if it matches, the template is included;
• name - the name of the template to be included.

Example:

<special>

<res_opensrs>

<field type="checkbox" name="leave_osrs_prices"

label="planwizard.leave_osrs_prices" value="1" checked="1">

<include ifvalue="" name="admin/wizards/tldprices.html"/>

</field>

</res_opensrs>

</special>