Description of lists

Introduction

The metadata element for lists can have the following additional attributes:

• key - key field. Its value will be sent to the form in the elid parameters upon editing;
• keyname - specifies a field which value is used for displaying a list of selected elements when performing a group operation. If not specified, a key field value will be used;
• autoupdate - specifies a time period in seconds to automatically update the page;
• selficon - the list has its own logo. Its value is a picture name.

  <metadata name="product" type="list" key="mpname" keyname="name" mgr="core">
    <toolbar view="buttontext">
      <toolgrp name="one">
        <toolbtn func="product.params" type="edit" default="yes" img="t-edit" name="params">
          <hide name="isinstalled" value="off"/>
        </toolbtn>
        <toolbtn func="product.update" type="edit" img="t-retry" name="update">
          <hide name="isinstalled" value="off"/>
        </toolbtn>
        <toolbtn func="product.install" type="edit" img="t-install" name="install">
          <hide name="isinstalled" value="on"/>
        </toolbtn>
        <toolbtn func="product.delete" type="group" img="t-delete" name="delete">
          <hide name="isinstalled" value="off"/>
          <hide name="name" value="COREmanager"/>
        </toolbtn>
      </toolgrp>
      <toolgrp name="two">
        <toolbtn func="product.go" type="edit" img="t-goisp" name="go">
          <hide name="isinstalled" value="off"/>
          <hide name="name" value="COREmanager"/>
        </toolbtn>
      </toolgrp>
      <toolgrp name="three">
        <toolbtn func="product.config" type="new" img="t-attr" name="config"/>
      </toolgrp>
    </toolbar>
    <coldata>
      <col name="name" type="data" sort="alpha" sorted="yes"/>
      <col name="version" type="data"/>
      <col name="avail_version" type="data"/>
      <col name="state" sort="prop">
        <prop name="installed" defimg="p-off" onimg="p-on"/>
        <prop name="installing" onimg="p-install" animated="yes"/>
        <prop name="updating" onimg="p-install" animated="yes"/>
        <prop name="deleting" onimg="p-install" animated="yes"/>
      </col>
      <col name="descr" type="msg"/>
    </coldata>
  </metadata>

Toolbar (toolbar element)

A toolbar contains buttons, that can be separated into groups (toolgrp element).

• view - specifies interface of the toolbar. This attribute is set automatically and its value depends on current user settings. Possible values: button (displays only buttons); buttontext (displays button captions).
• toolgrp - designed for logical separation of buttons, contains toolbtn elements, must have a name attribute;
• toolbtn - see "Toolbar button".

Toolbar group (toolgrp element)

• name - a group name. Used for button identification and localization purposes;
• img - an image name. If this attribute is set, when collapsing into groups, a fake button will be displayed instead of the first button in the group, with an image from the attribute value and a caption sourced from local messages by the group name.
• collapsed - indicates that the group of buttons should be shown as a dropdown, which is unfolded when the cursor is hovered over it.

Toolbar button (toolbtn element)

Attributes:

• name — button name. Used for button identification and localization purposes;
• func — name of the function to be called when clicking the button;
• img — name of the picture that will be shown on the button. Should be specified without extensions;
• customicon — URL for an SVG icon, such icon has priority over @img and is themed automatically (when changing the theme of the panel from dark to light and vice versa);
• sprite — value set to “yes” indicates that the button icon is in the ispmanager icons sprite;
• progressbar — value set to “yes” indicates that a progressbar will be shown while the action is being processed;
• default —  value set to"yes" indicates a default action (double-click on a table row); the attribute can be present in several elements, in this case the function of the first active button will be called;
• cgi — address of a cgi script to which the request will be addressed. For example /mancgi/download;
• sametab — the module will open in the same tab of the panel instead of the child tab;
• newtab — the module will open in a new tab of the panel instead of the child tab;
• drawer — the module will open in a drawer instead of a child tab; the value describes the width of the drawer - large, medium or small;
• nogroupedit — prohibit group editing;
• detached — the value set to “yes” indicates that this is a separate button that can be located outside the toolbar. Often used to indicate creation of new entity in lists;
• danger — value set to “yes” means that the confirmform button will be red;
• confirmform — indicates the function (func) of the form to source the input fields from for display in the confirmform;
• location — the only possible context value means that the button should be displayed in the context menu of the element in the table instead of the toolbar;
• type — type of action, can have the following values:
  • new: will show a new object creation form;
  • back: back to the previous list;
  • edit: show an edit form for the selected item;
  • action: operation over a selected item without confirmation;
  • editnosel: similar to edit but allows to call an edit form even if no items were selected;
  • editlist: call a list-function which parent element (plid) is the selected element from the list.;
  • group: group operation over selected items;
  • groupform: show an edit form for the group of selected items;
  • groupformnosel: similar to groupform, but allows to call a function even if no items were selected;
  • groupdownload: similar to group operation, but the expected result is a file;
  • list: call a list-function;
  • refresh: call a function for updating the current list;
  • windownosel: call a function in a new tab;
  • window: call a function for the selected item in a new browser tab;
  • groupwindow: call a function for the gropu of selected items in a new browser tab;
  • url: follow the URL specified in the func attribute in a new browser tab;
  • preview: an image given by the called function will be displayed.

Messages

The following messages are used for localization of toolbar buttons:

• hint_<button name> - messages for the tooltip;
• short_<button name> - caption under a button in the toolbar;
• msg_confirm_<button name> - message used to confirm an operation (@type='group');
• msg_confirm_delimiter - string to be used as a delimiter in the confirmation request when multiple items are to be selected. By default, a comma with a space is used as the delimiter.

Hide, show, remove elements

The hide element

To disable a button depending on the selected string.

Attributes:

name - column name;

value - the value that makes the button unavailable.

The show element

To activate a button depending on the selected string.

name - column name;

value - the value that makes the button available.

The remove element

To remove a button depending on the selected string.

name - column name;

value - the value that makes the button to be removed.

Context menu description (contextmenu element)

The contextmenu is displayed for each row of the table and allows performing actions similar to those performed by the Toolbar buttons. The contextmenu element is used inside the metadata element at the same level as toolbar and coldata. It has no additional attributes and, like toolbar, contains toolgrp elements (in this case, elements describing groups of menu items separated from each other by horizontal lines), which in turn contain toolbtn elements.

The toolgrp and toolbtn elements used to describe the context menu may have the same attributes as in the toolbar description (see above), but not all of them affect the behavior or display of the menu in the current version of the toolbar UI (Dragon).

Example:

<metadata>
  <toolbar> <!-- ... --> </toolbar>
  <coldata> <!-- ... --> </coldata>
  <contextmenu>
    <toolgrp name="go">
      <toolbtn name="go" func="webdomain.go" type="window" img="t-insert" sprite="yes" spritesvg="yes"/>
      <toolbtn name="go_db" func="site.db.redirect" type="window" img="t-insert" sprite="yes" spritesvg="yes">
        <hide name="database" value="Not used"/>
      </toolbtn>
    </toolgrp>
    <toolgrp name="edit">
      <toolbtn name="edit" func="site.edit" type="edit" img="t-edit" default="yes" sprite="yes" spritesvg="yes"/>
      <toolbtn name="php" func="phpconf" type="editlist" img="t-editlist" sprite="yes" spritesvg="yes">
        <show name="php_mode" value="FastCGI (Nginx + PHP-FPM)"/>
        <show name="cgi_site_settings" value="on"/>
        <show name="php_mode" value="Apache"/>
      </toolbtn>
    </toolgrp>
  </contextmenu>
</metadata>

In case the list description does not contain the contextmenu element in metadata, the context menu for the list items is based on the toolbar description, but the items with the following type attribute values are excluded from it: new, list, back, refresh, url.

Table column description (coldata element)

The coldata node must contain one or several col nodes that describe table columns.

• col - describes a table column;
• setcolor - specifies a row color. See setcolor element description.

Column description (col element)

Attributes:

name - column name. Must be unique within one metadata. Also used for localization purposes;

type - data type in a column. Possible values:

• data: data from the control panel; used by default;
• indicator: indicator of the limit value and actual used value transmitted by the control panel;
• msg: display messages corresponding to the value from the control panel;
• toggle: displays a string toggle. Used as an alternative to toolbtn to perform actions more quickly. Value in cells: on when enabled and off when disabled. Used together with toggle element within the col element. The toggle element can contain hide elements and can  be locked depending on the data in the string. Can have attributes: name - name of the property, onenable - specifies the name of the function to be called when the switch is set to “on”, ondisable - specifies the name of the function to be called when the switch is set to “off”;
• prop:  used in conjunction with prop and xprop elements within the col element, displayed in the status icon column.

sort - specifies how to sort out data in columns. Possible values:

• alpha: sort by alphabetical order; by default;
• calpha: case-insensitive alphabetical sorting;
• digit: sort in increasing order;
• version: sort software versions;;
• file: similar to “alpha”, but the '/' character counts less than any other, so files within the same directory are always placed together;
• indicator: sort out by the "actual usage" indicator; only for columns with indicators;
• ip: sort out IP addresses;
• prop:  sort out by properties, if the same properties are used, sort by column value in alphabetic order;
• priority: sort alphabetically by the @priority attribute.

sorted - sets the default sorting principle. A value should be a number specifying the sorting order, the sign before the number defines the direction '-' - descending, '+' - ascending (the sign is mandatory);

stat - show the sum of numbers in the given column. In addition, if a number is followed by some string (suffix), the summation is done separately for each suffix. For indicators, both total and used values are summarized. If the value of a list item has a total attribute, total=“ignore” will exclude the row from the sum when selected, and total=“final” will display this value as the sum;

wrap - if specified, line breaks in the data will not be ignored. The data in the column is displayed in multiple rows;

align - data alignment. Possible values: left, right, center;

width - column default width, in percent;

editform - cell value will be displayed as a link to the edit form. The function name must be specified in the attribute value, the elid of the row and plid of the list will be added to the edit form request;

fastfilter - the icon of quick list filtering will be displayed, allowing quick access to a filter by cell value of the list table;

if - see Introduction;

hidden - if specified, the column will be hidden by default. To reveal it, it is necessary to customize the table view;

level - see Introduction;

noescaping - if specified, html escaping will be disabled;

convert - specifies encoding algorithm for the column. All values in that column will be converted using the specified algorithm. Currently only punycode is supported allowing to convert from punycode into UTF-8 encoded symbols.

edit - enables to edit element directly on the list. Value of the attribute specifies a function name (form) to be called for saving the value. Make sure the column value matches the field name (field) on the form. The column name (scolname) and the list name (stablename) will be also sent to the form. 

The following types of form fields are supported: input[type=text][zoom, unlimit, date], select, radio, slider, textarea.

nestedlist - specifies the name of the list to jump to when clicking on a value in this column. A filter will be set on the list before jumping to it. The filter parameters will be taken from the @nestedlist value, which has QUERY_STRING format. In addition to the list name, which should be the start of the @nestedlist value, the following macros can be used in the attribute:

• col_value — cell value;
• elid — row identifier (@key);
• plid — sublist identifier;
• +values of filter fields of the current list.

Example:

<coldata>
  <col sort="ip" sorted="yes" name="name" type="data" nestedlist="webdomain&ipaddr=__col_value__"/>
</coldata>

Click on the value in the IP address list will display the list of sites (webdomain). Before calling the list, a filter will be set on it by the following call webdomain&ipaddr=col_value&sok=ok, where the cell value will be substituted for _col_value_. To ignore this functionality for certain rows, the nestedlist=“no” attribute should be used in the element with the value.

• nestedlist_blank attribute - the lists will be opened in a new tab of the panel, used only in conjunction with the nestedlist attribute;
• nestedlist_child attribute - the lists will be opened in a child tab of the panel, used only in conjunction with the nestedlist attribute;
• setcolor element - sets conditions for cell coloring. For more details see the description of the setcolor element.

Column hint (hint) messages can contain column hints: hint_<column_name>

Property description (prop/xprop element)

A column may contain up to 64 properties (prop and xprop elements). Properties are sorted out according to how they are added into metadata.

The prop element is displayed if the value with the name specified in the @name attribute is present in the string.

The xprop element is displayed if the value specified in the @name attribute matches the value specified in the @value attribute. If the @value attribute is not specified or its value is empty, the property will be displayed in case the value of this element does not correspond to any xprop with the same @name.

Attributes:

name - see description above;

value - only for xprop, see description above;

img - specifies an image to be displayed;

animated - an .img image, an animated .gif file;

cgi - address of the cgi script the request will be sent to. For example, /mancgi/download;

func - specifies a function to be called when clicking an image. The following values are sent to that function as parameters: elid - selected row identifier, plid - identifier in the base list, value - property value.

sort - specifies the sorting type for this property. The sort attribute can only be used in conjunction with sorting of type=“prop”. Possible values of this attribute:

• no: this property will not be taken into account during sorting;
• invert: rows without this property will go before rows with it when sorting in descending order.

type - specifies a type of the @func function. Possible values:

• edit: call the editing form for one selected element;
• list: call a list function which will be a child element for the selected element in the current list (plid);
• group: an operation on a selected element with confirmation;
• window: call the function in a separate browser tab;
• url: open the URL specified in the func attribute in a separate browser tab.

stat - displays a total number of rows with that property at the bottom of the table.

activehint - if specified as activehint=“yes”, the message describing the property will be loaded from the panel by a separate request every time it should be displayed. For this purpose the function of list generation will be called with parameters hint_field containing property name, value - its value, elid - string identifier. The result of the operation should be an xml document containing the value element with the message text. The text will be substituted in the corresponding message (see below) instead of the _value_ macro.

Messages may contain description of a property:

hint_p_ - description for xprop with a specified name and value;

hint_p_ - description for prop/xprop. The __value__ macros will be changed into a value.

Color scheme (setcolor element)

The setcolor element is applied to one cell only (text color), if described within the col element or set to the whole row (background color), if described within the coldata element. You can describe any number of conditions for rows and cells coloring.

Attributes:

• name - specifies an element name (it may be col, prop, xprop or a column name, which is not described in the XML), which value will be compared with the one specified in the value attribute. You may dismiss this attribute when adding rules for cell colors. In that case the value will be sourced from the cell with a specified rule;
• value - specifies the value that will be compared to a field value specified by the @name attribute. If not specified or empty, the field in the line will be checked;
• color - specifies the color that will be applied if the specified condition is met. 

Table rows and cells can be colored manually when generating data (the elem elements). Add the color attribute into a corresponding elem element for coloring a row or into any element with cell data for coloring a corresponding cell. When sending data to the xslt handler, all conditions specified by the setcolor element will be defined and corresponding attributes will be set in data elements of the list.

The following color are currently supported: red, green, blue, yellow, cyan. Example of state coloring in the change list:

...
        <col name="state" sort="alpha" type="msg">
            <setcolor color="red" value="testing"/>
            <setcolor color="yellow" value="planned"/>
            <setcolor color="green" value="release"/>
        </col>
...

Diagram description (diagram element)

You can also add visual representation of data to tables using the diagram element.

Attributes:

• type - diagram type. Possible values: line, histogram, pie (see the examples);
• label - column which value descriptions will be sourced from;
• data - column which data for a pie chart will be sourced from (applicable only for type="pie");
• min - specifies the lower vertical limit for the diagram (applicable only for type=“line” and type=“histogram”);
• max - specifies the upper vertical limit for the diagram (applicable only for type=“line” and type=“histogram”);
• others - specifies the minimum percentage to be displayed on the circle, all data below this percentage will be displayed as “other” (applicable only for type=“pie”, set by a fractional number, e.g. 20% is 0.2). 

Line element -  one or more such elements describe the data to be displayed on the diagram.

Attributes:

• @data attribute of this element specifies the name of the column from which the values will be sourced;
• @color attribute specifies the color of the line/column, set this attribute for all line elements to apply.