Parallels H-Sphere Documentation Developer Guide

 

XML Manager

 
 

Related Docs:   Building Packages With XML Configuration Files Merging XML Configuration Files

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.

XMLManager serves for loading custom XMLs into H-Sphere and merging them with the standard, or default, H-Sphere XML configuration files. This enables to extend H-Sphere by adding new elements, like custom menu items, without changing the standard XML configuration files. This mechanism makes customization more flexible to the H-Sphere updates. Now you don't need to apply custom settings each time the standard configuration files are rewritten by new releases.

 

XMLManager Implementation

XMLManager is the subclass of the psoft.hsphere.util class of H-Sphere utilities. XMLManager returns either Document object or TemplateXML object.

XMLManager searches for custom XML configuration files, by the key, not by the filename:

  1. in hsphere.properties;
  2. in the predefined values (see psoft.hsphere.util.PackageConfigurator).

For example, the menu XML configuration file is set in hsphere.properties as follows:

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

XMLManager looks for the MENU_CONFIG key instead of the full pathname (/hsphere/local/home/cpanel/shiva/psoft/hsphere/menu.xml).

XMLManager may also process the group of XML files. It is currently implemented for XML plan wizards, where the key is compounded from the corresponding path + the name of XML file, like:

XMLManager.getXML(PLAN_WIZARDS_DIR, "unix.xml");

Example:

Consider an example of merging menu default and custom menu XMLs. For details, please refer to Menu Customization in Customization Guide.

1) Log in as the cpanel user.

2) Create custom XML file and specify its location as CUSTOM_XML_CONFIG in hsphere.properties (see XML Merge Customization in Customization Guide for details):

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

3) To add a custom menu item, ~cpanel/shiva/custom/xml/test1_menu.xml should look like this:

<?xml version="1.0"?>
<!DOCTYPE config [
 <!ELEMENT config (menus,interface)>
  <!ELEMENT menus (menu+)>
  <!ELEMENT menu (menuitem*,initmenu*)>
  <!ELEMENT menuitem (#PCDATA)>
  <!ELEMENT initmenu (#PCDATA)>
  <!ELEMENT interface (menudef+)>
  <!ELEMENT menudef (initmenu*,menuitem*)>


  <!ATTLIST menudef id CDATA #REQUIRED>

  <!ATTLIST menu name CDATA #REQUIRED>
  <!ATTLIST menu label CDATA #REQUIRED>
  <!ATTLIST menu platform_type CDATA "">
  <!ATTLIST menu resource CDATA "">
  <!ATTLIST menu defaultitem CDATA #REQUIRED>
  <!ATTLIST menu tip CDATA "">

  <!ATTLIST menuitem name CDATA #REQUIRED>
  <!ATTLIST menuitem label CDATA #REQUIRED>
  <!ATTLIST menuitem URL CDATA #REQUIRED>
  <!ATTLIST menuitem platform_type CDATA "">
  <!ATTLIST menuitem resource CDATA "">
  <!ATTLIST menuitem tip CDATA "">
  <!ATTLIST menuitem check_type CDATA "1">
  <!ATTLIST menuitem new_window CDATA "0">

  <!ATTLIST initmenu name CDATA #REQUIRED>
]>

<config>
<menus>
<menu name="info" label="info.label" defaultitem="info-plans" tip="info.tip">
  <menuitem name="xyz-wow" label="NEW PAGE" URL="/newpage.html" resource="" tip="Positive Software Corporation"/>
</menu>
</menus>
</config>

IMPORTANT:
In the custom XML file to be merged with the default one, you must define the same DTD structure!

Also note that we don't copy the whole structure of the standard menu.xml file. The custom menu will be merged with the standard menu in the following way (the NEW PAGE item in the INFO menu):

4) To check if the merge is performed correctly, run the DOMLoader utility and check out.xml afterwards:

java psoft.util.xml.DOMLoader /hsphere/local/home/cpanel/shiva/psoft/hsphere/menu.xml
     /hsphere/local/home/cpanel/shiva/custom/xml/test1_menu.xml > out.xml

With DOMLoader, you may merge more than two XML files:

java psoft.util.xml.DOMLoader file1.xml file2.xml ... fileN.xml > out.xml

 

XML Merge Processing Instructions

In your custom XML configuration files you should use the processing instructions to change or remove certain fragments in the default configuration file, instead of merging these fragments directly.

There are three major processing instructions: <?change?>, <?remove?>, and <?merge?>. The merge instruction is used by default and can be omitted.

The <?changeattr?> instruction is added to customize tag attributes in XML documents.

In order to change, remove, or merge an element, you need to create a well formed XML document, which describes the location of this element relative to other elements. Leave out the elements you don't want to change/remove/merge. Put the instruction before the XML element that needs to be changed/removed/merged.

Examples:

1) To remove a certain (tt) item from the the default menu configuration:

<?xml version="1.0"?>
<!DOCTYPE config [
 <!ELEMENT config (menus,interface)>
  <!ELEMENT menus (menu+)>
  <!ELEMENT menu (menuitem*,initmenu*)>
  <!ELEMENT menuitem (#PCDATA)>
  <!ELEMENT initmenu (#PCDATA)>
  <!ELEMENT interface (menudef+)>
  <!ELEMENT menudef (initmenu*,menuitem*)>


  <!ATTLIST menudef id CDATA #REQUIRED>

  <!ATTLIST menu name CDATA #REQUIRED>
  <!ATTLIST menu label CDATA #REQUIRED>
  <!ATTLIST menu platform_type CDATA "">
  <!ATTLIST menu resource CDATA "">
  <!ATTLIST menu defaultitem CDATA #REQUIRED>
  <!ATTLIST menu tip CDATA "">

  <!ATTLIST menuitem name CDATA #REQUIRED>
  <!ATTLIST menuitem label CDATA #REQUIRED>
  <!ATTLIST menuitem URL CDATA #REQUIRED>
  <!ATTLIST menuitem platform_type CDATA "">
  <!ATTLIST menuitem resource CDATA "">
  <!ATTLIST menuitem tip CDATA "">
  <!ATTLIST menuitem check_type CDATA "1">
  <!ATTLIST menuitem new_window CDATA "0">

  <!ATTLIST initmenu name CDATA #REQUIRED>
]>

<config>

<interface>

<menudef id="unix">
<?remove?>
        <initmenu name="tt"/>
</menudef>

</interface>

</config>

2) To replace the whole icon section to the one with only 3 icons:

<?change?>
<icons>
<icon id="changelanguage" url_param="template_name=misc/langs.html"
      rtype="" platform="" label="nomenu.language" tip="" help=""/>
<icon id="changedesign"
      url_param="template_name=misc/user_account_lf.html" rtype="" platform=""
      label="nomenu.lookfeel.alt" tip="" help=""/>
   <icon id="cgiwiz_formmail"
         url_param="template_name=quick/choice_script.html&sname=formmail"
         rtype="hosting" platform="unix"
         label="quick.quickview.cgiwiz_formmail"
         tip="quick.quickview.cgiwiz_formmail"
         help=""/>

</icons>

3) To remove a certain (cgiwiz_formmail) icon from the default configuration:

<icons>
<icon id="changelanguage" url_param="template_name=misc/langs.html"
      rtype="" platform="" label="nomenu.language" tip="" help=""/>
<icon id="changedesign"
      url_param="template_name=misc/user_account_lf.html" rtype="" platform=""
      label="nomenu.lookfeel.alt" tip="" help=""/>
<?remove?>

   <icon id="cgiwiz_formmail"
         url_param="template_name=quick/choice_script.html&sname=formmail"
         rtype="hosting" platform="unix"
         label="quick.quickview.cgiwiz_formmail"
         tip="quick.quickview.cgiwiz_formmail"
         help=""/>
</icons>

4) To change and add tag's attributes:

<?changeattr newtag="xyz" tip="My Tip"?>
<icon id="changelanguage" url_param="template_name=misc/langs.html"
      rtype="" platform="" label="nomenu.language" tip="" help=""/>

The resulting element will look like:

<icon id="changelanguage" url_param="template_name=misc/langs.html"
     rtype="" platform="" label="nomenu.language" tip="My Tip" help="" newtag="xyz"/>

Related Docs:   Building Packages With XML Configuration Files Merging XML Configuration Files



© Copyright 2017. Parallels Holdings. All rights reserved.