Category:XML

From ISPWiki
Jump to: navigation, search

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 control panel.

The following attributes can be used with practically any element describing the interface.

if
specifies the (Feature) that makes this element available.
before
inserts 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 attribute coincides with the value of the before attribute. ,
after
similar to before, but the element will be placed after the selected element.
first
possible value - "yes". The element will be the first on the list.
last
possible value - "yes". The element will be the last on the list.
level
you 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.

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

type
interface element type. Possible values - form (describes a form), list (describes a list of data), report (describes a report).
name
specifies a name of the function that this element describes.
helpurl
if specified, the value for the Help link will be taken from this attribute.
level
specifies 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.
secured
if "yes", data will be hidden in answers to COOKIE requests with invalid REFERER
include
enables to add contents of another metadata element into metadata. Name of the element to be added should be specified in the name attribute.
externalscript
enables 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>
level
access level described by this menu.
startpage
page that opens by default. Specify a function name from the main menu. If not specified, name of the first menu item referring to the list will be used automatically.
node
describes menu elements and its subsections.

level is the attribute. However, when forming 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).

name
name of the function to be called. It can also be used for languages.
type
specifies a function type. Possible values: list or form. This attribute is set automatically.
action
specifies 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.
function
specifies 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=<current session access level> parameter is called. It will return the URL that will be inserted into the function attribute.

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>
    </label>
    <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>
name
code of the language described. For example: en, fr, ru, es.
messages
describes messages for a specific function.

Description of messages for functions (the messages element)

name
name of the function described.
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 behaviour 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">
      <event name="auth" after="yes"/>
  </handler>
</mgrdata>
name
name of the executable file that should locate in the addon dirrectory
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 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.
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).
base
specifies 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 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.