Interface XML description
Introduction
Descriptions of forms, tables, menu items and messages are kept in XML-files in the /usr/local/ispmgr/etc/xml directory. The control panel uses UTF-8 encoded XML files. Performing any operating by the control panel will result in an XML-document.
You must not edit XML files of your control panel. However, you can add your forms and tables, add or hide form fields using plug-ins and events.
This article describes XML files that are used by the control panel.
The following attributes can be used with practically any element describing the interface.
ifspecifies the (Feature) that makes this element available.beforeinserts your content before the content of the selected element. If specified, the panel will look through all elements in the same context and inserts the element before the same-name element which value of the main attributecoincides with the value of the before attribute. ,aftersimilar to before, but the element will be placed after the selected element.firstpossible value - "yes". The element will be the first on the list.lastpossible value - "yes". The element will be the last on the list.
levelyou can use this attribute for any element within metadata and mainmenu to specify access level a user must have to view certain data. Elements will be deleted from metadata. Data corresponding to those elements will be deleted as well. For the col element that describs a table raw, all elements corresponding to table raws will be deleted. For input, select, slider, textarea, text, htmldata - corresponding elements of the upper level. The attribute may contain several values space separated. Each value must have the following format:
- 0 to 31 - access level
- string - access level or mask
- the '+' sign after a figure or string means the minimum access level. Note, that the string must specify access level, rather than a mask.
COREmanager contains a number of reserved names:
- nobody 0 access level
- super 30 access level
- admin 29 access level
- reseller 24 access level
- user 16 access level
- all mask - any user
- registered mask - user with access level higher than 0 (successful authorization)
For example, the following records are identical: nobody+, all, 0+
The metadata and mainmenu elements process the level attribute in a different way.
Key attributes
When getting data from XML-files, the control panel combines similar elements. Their contents and attributes will be combined as well. Similar elements are those from one context, having the same names and values of the main attribute (the name attribute for most elements). Some elements, such as toolsep, jscript, if, else can never be combined.
While uploading XML files the control panel does not change contents of the following elements (does not analyse enclosed elements): jscript, func, event, query и msg.
metadata
Metadata are used for describing elements of the control panel. Each element describes one interface element.
typeinterface element type. Possible values - form (describes a form), list (describes a list of data), report (describes a report).namespecifies a name of the function that this element describes.helpurlif specified, the value for the Help link will be taken from this attribute.levelspecifies users for which the selected interface element will be accessible (the function which name is specified in the name attribute). See Introduction for correct format.securedif "yes", data will be hidden in answers to COOKIE requests with invalid REFERERincludeenables to add contents of another metadata element into metadata. Name of the element to be added should be specified in the name attribute.externalscriptenables browsers to download JavaScript code from external files.
Main menu (mainmenu)
Currently a two-level system is used. All menu elements must be grouped by sections. Sections must not contain subsections.
Following is the example of the COREmanager main menu:
<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://ru.5.ispdoc.com/index.php/core-handbook-30"/>
</node>
</mainmenu>levelaccess level described by this menu.startpagepage that opens by default. Specify a function name from the main menu. If not specified, the name of the first menu item referring to the list will be used automatically.nodedescribes menu elements and its subsections.
level is the attribute. However, when forming the menu for a specific login level, all mainmenu elements available on that level will be combined.
For example, if you want to add a menu element to all login levels, you can write:
<mainmenu level="registered">
<node name="stat">
<node name="mystat" first="yes"/>
</node>
</mainmenu>The above XML adds the mystat menu element into the stat section (the stat section will be created, if needed) for all login levels (level="registered"). Note, that mystat will be the first element in the stat section (first="yes").
Menu elements (the node element)
The node element describes a menu element (without child nodes) or its section (child nodes describe elements).
namename of the function to be called. It can also be used for languages.typespecifies a function type. Possible values: list or form. This attribute is set automatically.actionspecifies a function name to be called. This parameter is set automatically for items that refer to panel's functions. Its value coincides with that of the name attribute.functionspecifies the URL. This parameter is set automatically, if the external function (extaction), which name is specified by the name attribute is present in the panel.
The handbook menu element differs from the above elements. If any, the help function with the topic=handbook and level=
Description of languages and translations (lang)
Following is the example of COREmanager text messages in English (part of the file core_msg_en.xml):
<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>namecode of the language described. For example: en, fr, ru, es.messagesdescribes messages for a specific function.
Description of messages for functions (the messages element)
name name of the function
msg contains a message
include import messages from the selected section
COREmanager contains a number of special sections for messages. They are used if though the value of their @name attribute does not correspond to any function:
alert messages for banners
common common messages
msgerror error messages
form messages for forms and reports
list messages for lists and reports
report messages for reports
Message description (the msg element)
name message name.
This element doesn't have child nodes. It contains message text.
External handlers (handler/library)
COREmanager enables you to modify system behavior according to your needs. You may use external handlers written on your popular programming language or shared libraries written on C++.
The handler element is used for writing external handlers:
<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
<handler name="lastlogin" type="cgi" ignore_errors="yes">
<event name="auth" after="yes"/>
</handler>
</mgrdata>name — name of the executable file that should locate in the addon
type — type of interaction with your handler. Possible values: cgi and xml. cgi — the handler will be called using the CGI interface. It will get all the data through environment variables, and contents of the POST request will sent to stdin. xml - the handler will get all the data through environment variables and contents of the POST request will be sent to stdin. Beside contents of the POST request it will get an xml document generated for responding to that request. Both cases will result in a valid XML document sent to stdout. In the first case, it will be combined with the XML document inside the control panel, in the second case — the xml document will fully replace the one generated earlier.
ignore_errors — ignore errors that occur. Optional parameter. If you specify this attribute with the value "yes", then errors occurring during the handler operation will not affect the performance of the control panel. The option applies only to those handlers for which it is specified.
the event element specifies a function that should be called to start your handler. This function must exist. Using the func element will create a new function.
the func element creates a new function (its name is specified by the @name attribute of this element) that will be implemented by the handler.
The library element is used for using a custom library. The following XML will upload the test library from the lob directory:
<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
<library name="test"/>
</mgrdata>Event handler (the event element)
COREmanager enables not only to add custom event handlers, but also specify in which order they should be called. The event element has a number of attributes:
priority specifies how to call your handler. Possible values: before and after for calling the handler before or after the base one (see the @base attribute).basespecifies a name for base handler associated with the @priority attribute. If not specified, @priority=before will put the handler to the beginning of the queue, @priority=after - to the end.
Even if you specified that your handler should be called first/last or before/after another handler, it doesn't guarantee that it will do so. For example, if several handlers are supposed to be first, they will be processed prior to other handlers in descending order (the last created will be processed first). Otherwise, you should specify the handler before or after which you want your handler to be processed.
If the handler specified in the @base attribute does not exist, its value will be ignored.