|
Introduction
Since version 2.4, 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 WIZARDS_DIR to the currect directory.
Editing the XML file would require proper knowledge of XML, so that the document remains well-formed and correct.
Adding New Wizard to the List of Plan Wizards
The list of wizards is defined in the plan_wizards.xml file.
To add a new wizard, add the following line:
<wizard name="NAME" description="DESCRIPTION"/>
Here,
- NAME will be used as name of XML file without .xml extension (.xml suffix will be appended automatically).
The file contains the plan wizard specification.
- DESCRIPTION is a lang string defined in hsphere_lang.properties. It should not contain "lang." prefix.
Defining Plan Wizard
New plan wizard definition starts from creating a new .xml file.
The root XML element is:
<PlanWizard name="NAME" description="DESCRIPTION">
Attributes:
- NAME should match the filename (without .xml prefix) and NAME attribute in plan_wizards.xml file.
- DESCRIPTION is the plan wizard description from hsphere.properties file without lang. prefix.
PlanWizard element include the following entries:
<DefaultName>name</DefaultName>
This is the name that will serve as the default plan name in creating the plan.
<DefaultValues>
<value name="NAME1">VALUE1</value>
<value name="NAME2">VALUE2</value>
...
</DefaultValues>
Add default values to the plan. Usually, add _template and menuId values are added here.
<categories>
<category>
...
</category>
<category description="DESCRIPTION">
...
</category>
</category>
categories tag is used to define resources.
Resources are grouped into categories and described within the <category> element.
Each category tag can have the description attribute which is optional.
Categories are used in plan wizard screens to group resources into "logical" groups.
Following tags can be used inside category tag:
The <resource> element defines the resource class, name, description and include the following attributes if necessary:
- name - the 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 resource is required to be in the plan and regarded to be automatically
included to the plan;
- include (optional) - if it is set to 1 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> element, <field> tag allows to get more info from the user for the specified resource.
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 - a label from hsphere_lang.properties, refers to the 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"/>
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> element 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"/>
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> element works 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.
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 unixuser resource the tag would look like this:
<res_unixuser>
</res_unixuser>
These tags contain the list <mod> tags where mods that will be defined in the plan are described.
Attributes:
- name - name of the mod; "" if missing;
- ifresource - list of resources separated with '|' sign.
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 will not be defined.
Inside the mod element the following tags are structured:
The <initresource> tag is used to define initresources inside the mod.
Attributes:
- name - name of initresource. The system automatically checks that resource is included in the plan before adding initresource;
- ifactive - list of resources, separated by the '|' sign.
If any of this resources are active in the plan (i.e, created by default), the initresource will be defined;
otherwise, it will not be defined.
The <initvalue> tag is used to define initvalues.
Attributes:
- type - one of the following types as defined in psoft.hsphere.plan.InitValue:
static, field, relative, absolute, relative_rec, absolute_rec, hostgroup, plan_free, plan_value
- label - is not used anymore, can be considered a comment.
The initvalue tag content is a string.
If it starts with # sign, 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>
The <if> tag allows include initresources or initvalues according to 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.
The <values> element included <value> tags inside.
The <value> tag used to define the resource values in the plan.
Attributes:
- name - mnemonic identifier.
If the tag content string starts with # sign, the value will be used as a name of
the parameter that is passed via HTTP request.
Example:
<value name="SSI">1</value>
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 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 a 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.
Inside the <field> element, <include> tag defines a template to include:
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>
|
