Interface XML description

Introduction

Descriptions of forms, tables, menus, and messages of the platform are stored in XML files in the /usr/local/mgr5/etc/xml directory and use UTF-8 encoding. The platform returns the result of any operation in XML format.

It is not recommended to modify standard XML files. However, you can:

• create your own forms and tables;
• add or remove fields from existing forms using plugins and events.

Positioning and access attributes

Common attributes of elements

The following attributes apply to most interface elements:

• if— determines the condition (Feature) under which the element is accessible;
• before— determines which element the element should be placed before. The platform searches for an element with a matching key attribute value (usually name) in the current context;
• after — determines after which element an element should be placed. Similar to before;
• first — places the object first in the list. The acceptable value is yes;
• last —  places the object last in the list. Acceptable value is yes;
• level— Access level for displaying an item and related data. Applies within  metadata and mainmenu. Hiding an element results in the deletion of associated data:
  • for a table column (col) — data in rows is deleted;
  • for data elements (input, select, slider, textarea, text, htmldata) — the corresponding top-level elements are removed.
    Value format:
    
    • a number from 0 to 31 — access level;
    • string — name of the access level or mask;
    • the + symbol after a number or string means that access must be no lower than the specified level. The string must be a level name, not a mask.

In COREmanager, there are a number of registered names with different access levels:

• nobody — level 0;
• super — level 30;
• admin — level 29;
• reseller — level 24;
• user — level 16;
• all — "any user" mask;
• registered — mask "user with access above 0" (authorized).

Example values:

• nobody+;
• all;
• 0+.

For the metadata and mainmenu elements, the algorithm for processing thelevel attribute differs:

• for metadata, the levelattribute is set by a pseudonym. For example, admin+ or registered;
• For mainmenu, the level attribute is set as a number. For example, 29, 16, 8, etc.

Key attributes

When loading data from XML files, the platform merges identical elements. At this point, the content of the elements and their attributes are merged. Elements are considered identical if they:

• are in the same context;
• have the same name;
• have the same value for the key attribute (if any). For most elements, the name attribute is key.

Exceptions that never merge:

• toolsep;
• jscript;
• if;
• else.

When loading XML files, the platform does not change the content of the following elements (nested elements are not analyzed):

• jscript;
• func;
• event;
• query;
• msg.

Metadata

Metadata is used to describe elements of the platform interface. Each metadata element describes one interface element. Attributes:

• type –- interface element type. Can take the following values:
  • form — input form;
  • list — list of data;
  • report — report.
• name — sets the name of the function described by this element;
• helpurl — sets the URL value for the "Help" link. Applies to the form tag inside metadata;
• level — pecifies which users have access to the interface element (the function whose name is specified in the nameattribute). The format of the attribute value is described in the section Positioning and access attributes ;
• secured — if the value is yes, the data is hidden in responses when authorizing with a cookie with an incorrect HTTP Referer header. Applies to any elements within metadata, most often used for input within field :
  Example of using secured

  <field name="password">
  	<input name="password" type="password" required="yes" secured="yes"/>
  </field>

• readonly — refers to elements within field. Applies to metadata form elements (e.g., input, select, textarea), not to stored data. Controls field editing in the interface. Does not affect the recording of values in the database.

For more information about form attributes, see the article Description of forms.

To set an attribute, modify the form structure in the XML file in one of the following ways:

• in the XML template:
  
  Example of the XML template:

  <input name="type" type="text" readonly="yes"/>

• in the code:
  
  Example of setting an attribute via the ses.xml object

  ses.xml.GetNode("/doc/metadata/form//field/*[@name='type']").SetProp("readonly", "yes");

The include element

A child element that adds the content of another metadata element. The name of the included element must be specified in the name attribute.

Rules for processing include conditions when loading metadata:

• elements without prefixe label_:
  • conditions (if, after, before, first, last) are processed before documents are merged. For more details on conditions, see section Positioning and access attributes;
  • the order of nodes changes before merging;
• elements with prefix label_:
  • terms are processed after the documents are merged.

Main menu (mainmenu)

The COREmanager main menu (mainmenu) uses a two-level structure:

• all items must be grouped by section;
• sections cannot contain subsections.

<mainmenu level="30" startpage="session">
  <node name="srvset">
    <node name="product" action="product" type="list"/>
  </node>
  <node name="stat">
    <node name="session" action="session" type="list"/>
    <node name="journal" action="journal" type="list"/>
    <node name="longtask" action="longtask" type="list"/>
  </node>
  <node name="set">
    <node name="brand" action="brand" type="form"/>
    <node name="usermenu" action="usermenu" type="list"/>
    <node name="usrparam" action="usrparam" type="form"/>
  </node>
  <node name="mgrhelp">
    <node name="changelog" action="changelog" type="list"/>
    <node name="handbook" function="http://en.example.com/index.php/core-handbook-30"/>
  </node>
</mainmenu>

Attributes of mainmenu:

• level — access level for the menu;
• startpage — default page name (function from the menu). If not specified, the first available item is used.

The level attribute is key for the menu. When creating a menu for an access level, all mainmenu elements with that level are combined.

To add a menu item for all access levels, execute the command:

  <mainmenu level="registered">
    <node name="stat">
      <node name="mystat" first="yes"/>
    </node>
  </mainmenu>

This XML code:

• creates the stat section if it does not exist;
• adds the mystat item to the stat section for users of all levels (level=“registered”);
• makesmystat the first item in the stat section (first=“yes”).

nodeelement

The node element describes:

• a menu item (without child elements);
• a menu section (with child node elements).

Attributes:

• name — function name. Used for calling and localization;
• type — function type (list or form). Substituted automatically;
• action — name of the called function. Copies name. Substituted automatically;
• function — URL for transition. Automatically substituted for external functions.

The handbook menu item is handled in a special way. If the handbook item is present:

1. The helpfunction is called with the following parameters:

   • topic=handbook
   • level=
2. The returned URL is substituted into the attribute called function.

Language descriptions and translations (lang)

The lang element describes translations for a language. For example, the description of COREmanager messages in English in the core_msg_en.xml file will look like this:

  <lang name="en">
    <messages name="label_langs">
      <msg name="bg">Български</msg>
      <msg name="cn">汉语</msg>
      <msg name="cs">Český</msg>
      <msg name="de">Deutsch</msg>
      <msg name="en">English</msg>
      <msg name="es">Español</msg>
      <msg name="fi">Suomi</msg>
      <msg name="fr">Français</msg>
      <msg name="hu">Magyar</msg>
      <msg name="jp">日本語</msg>
      <msg name="ku">کوردی</msg>
      <msg name="nl">Nederlands</msg>
      <msg name="pl">Polski</msg>
      <msg name="pt">Português</msg>
      <msg name="ru">Русский</msg>
      <msg name="th">ภาษาไทย</msg>
      <msg name="ua">Українська</msg>
      <msg name="xx">Developer</msg>
      <msg name="zh">中文</msg>
    </messages>
    <messages name="usrparam">
      <include name="label_langs"/>
      <msg name="addr">Allowed IP-addresses</msg>
      <msg name="atallow">allow for listed IP-addresses</msg>
      <msg name="atany">allow for any IP-address</msg>
      <msg name="atype">Access to the control panel</msg>
      <msg name="button">Icons</msg>
      <msg name="buttontext">Icons and captions </msg>
      <msg name="buttonview">Toolbar view</msg>
      <msg name="confirm">Re-enter password</msg>
      <msg name="email">E-mail for notifications </msg>
      <msg name="hint_rows">Enter the number of rows per page that will be displayed by default</msg>
      <msg name="hint_startpage">Select a page that will be displayed once you log in to the control panel</msg>
      <msg name="hint_theme">Select the theme that will be used to display the control panel</msg>
      <msg name="hint_timezone">Select the time zone for your region </msg>
      <msg name="lang">Language</msg>
      <msg name="msg_error_notuniqueemail">The selected e-mail is already used </msg>
      <msg name="msg_passwd">Password do not match!</msg>
      <msg name="name">Username</msg>
      <msg name="password">Password</msg>
      <msg name="recordlimit">Number of records </msg>
      <msg name="rows">Rows per page</msg>
      <msg name="startpage">Start page</msg>
      <msg name="text">Text</msg>
      <msg name="theme">Theme</msg>
      <msg name="timezone">Time zone</msg>
      <msg name="title">General settings</msg>
      <msg name="title_new">General settings</msg>
    </messages>
  </lang>

The name attribute contains the code of the language being described. For example: en,fr, ru, es.

The messages element

Describes messages for a specific function. The name attribute contains the name of the function.

The msg element

Contains the message text. Has no child nodes. The name attribute specifies the name of the message.

The include element

Imports messages from another section. The name attribute specifies the name of the section.

COREmanager has a number of special messages sections. They are used even though the value of their name attribute does not correspond to any function:

• alert — messages for banners;
• common — general messages;
• msgerror — error descriptions;
• form — messages for forms and reports;
• list — messages for lists and reports;
• report — messages for reports.

Tips (hint)

Tooltips for interface elements are defined in localized messages. The names of such messages begin with the hint_ prefix.

Features of hints:

• support HTML markup;
• tags must be valid XML elements.

To insert a link into a tip, use the command:

<msg name="hint_multiselect">You can select more than one <a href="http://en.5.ispdoc.com/" target="_blank">item</a></msg>

To highlight important text with color, use the command:

<msg name="hint_multiselect">You can select <span style="color:red;">more than</span> one item</msg>

To record HTML tags, use the following options:

• using CDATA:

  Example of tag recording

  <msg name="hint_color">I am<![CDATA[<font color="yellow">yellow</font>]]></msg>

• with special character escaping. To use this option, replace:
  • < for <
  • > for >
  Example of tag recording

  <msg name="hint_link">I am a &lt;a href="https://google.com"&gt;link&lt;/a&gt;</msg>

External handlers (handler/library)

COREmanager provides a mechanism for changing system behavior. The platform allows you to integrate user logic through:

• external handlers (any programming language);
• C++ libraries (shared libraries).

The handler element

Thehandler element is used to describe external handlers:

<mgrdata>
  <handler name="lastlogin" type="cgi" ignore_errors="yes">
      <event name="auth" after="yes"/>
  </handler>
</mgrdata>

Attributes of handler:

• name — name of the executable file in the addon directory;

• type — type of interaction with the handler. Possible values:

  • cgi — handler is called using the CGI interface. It receives data via environment variables and POST. The result is combined with the platform's response;
  • xml — handler receives data via environment variables and POST, additionally receives the current XML response. The result completely replaces the platform response;
• ignore_errors — when "yes" is specified, handler errors do not affect the platform operation. Optional parameter. Applies only to those handlers for which it is specified.

The eventelement specifies an existing function that triggers the handler when called.

The funcelement creates a new platform function. The logic is fully implemented by the handler.

The library element

Loads the user library from the lib directory:

<mgrdata>
  <library name="test"/>
</mgrdata>

Event handlers (event element)

COREmanager allows you not only to add your own event handlers, but also to define the order in which they are called. To do this, the event element has a number of attributes:

• priority — specifies the order in which the handler is called. Can take the following values:
  • before — the handler will be called before the base handler;
  • after — the handler will be called after the base handler (see the base attribute).
• base — sets the name of the base handler relative to which the order is defined by the priority attribute.  If the base handler is not specified, then with @priority=before the handler will be added to the beginning of the queue, and with @priority=after — to the end.

Even if you specify that your handler should be called first/last or before/after another handler, this does not guarantee that it will actually take the specified position in the queue. For example, if there are several handlers with priority="before", they will be executed before all others, in reverse order of their creation (the last one created will be the first). If the order differs from the expected one, you need to explicitly specify after or before which handler the desired one should be executed.

If the handler specified in the base attribute does not exist, the attribute value is ignored.

Caching

The platform does not work with source XML files directly. It uses a two-level caching system to optimize metadata processing.

Level 1. Precaching

The first stage consists of the following steps:

1. Merging all XML documents according to the rules.
2. Split into separate files (onemetadata or messages per file).
3. Saving the files you get in directories:
   
   • var/.xmlcache/<manager>.0
   • var/.xmlcache/<manager>.1
4. Create a symbolic link var/.xmlcache/<manager> that points to the active directory. The second directory is used for pre-caching. The operation is performed using the following commands:
   Example of a command

   # metadata caching
   sbin/xmlinstall --manager <manager> --meta-cache [--apply]
   # message caching
   sbin/xmlinstall --manager <manager> --lang-cache ru --base en [--apply]

The --apply parameter activates changes in the directory that the platform is currently working with, without restarting.

Level 2: Finalizing the cache

The second stage consists of the following steps:

1. Processing of include directives.
2. Nodes reorganization.
3. Adding missing messages from other modules.
4. The result is saved in the var/.xmlcache/<manager>.X/checked catalog

The result is rebuilt:

• if the platform's feature set changes;
• when the cache is completely rebuilt.

The operation is performed by the platform as needed, when access to certain XML files is required.

Pre-caching

To avoid downtime when restarting the platform, run the command:

sbin/xmlinstall --manager <manager> --recache [--apply]

Where is the name of the product being used. For example, billmgr

In this case:

• a new cache directory is created next to the current one. If the <manager>.0 directory is used, the <manager>.1 directory will be created, and vice versa;
• the platform checks both directories at startup, and if one of them contains current data, it makes it active;
• the --applyparameter activates changes in the directory that the platform is currently working with without restarting;
• the platform reads part of the data (for example, access level information) from XML files only at startup;
• to apply all changes, the platform must be restarted.