For developers

/
/
/
Main page (Dashboard) description

Main page (Dashboard) description

Introduction

A Dashboard is the main page of the control panel, it is intended for quick access to the ispmanager functions and the most frequently required information (version of the panel and OS, available resources, their load, resource limits, etc.).

The Dashboard consists of a set of blocks of different types. Blocks of url and taskbar types are displayed above other blocks. Blocks of other types can be displayed in 1, 2 or 3 columns depending on the width of the browser window and can be moved from column to column, as well as up and down that very column. Blocks can be minimized.

The contents of the Dashboard are described using xml documents located in the /usr/local/mgr5/etc/xml directory. The final view of the Dashboard is generated from the following sources:

  • base XML file describing the Dashboard for a given access level with a name like ispmgr_dashboard_[access level number].xml, e.g. ispmgr_dashboard_16.xml. It is recommended to avoid editing such files, as they will be replaced with new ones when ispmanager panel is updated.
  • plugin files that allow you to change the structure and data displayed on the Dashboard of the kind ispmgr_mod_[plugin name].xml, e.g. ispmgr_mod_dashboard.xml. Example of extending the functionality of the Dashboard with a plugin: How to add a quick action to the dashboard
  • saved information about the settings of the Dashboard for an individual user: collapsed and expanded blocks, displayed quick actions, the order in which blocks are displayed and the frequency of automatic refreshing of the page.

Example of the ispmanager Dashboard:

XML description

The XML description of the Dashboard must contain one or more <block> elements within the <doc> element. Each of the elements describes a block on the home page.

Please find an XML example of the ispmanager Dashboard.

Example of Dashboard XML

<?xml version="1.0"?>
<doc lang="ru" func="dashboard" binary="/ispmgr" host="https://localhost:4200" themename="dragon" stylesheet="dashboard" features="3a604f5c3c6d5683f90a1f63f1d171aa0" notify="0" favorite="no" pin="no">
  <block name="license.mgr.info" position="right" type="isplicense" func="license.mgr.info" display="" prev=""/>
  <block name="capacity" position="right" type="list" func="server_capacity" enable_autoupdate="yes" prev="" display=""/>
  <block name="session" position="right" type="list" func="session" rows="5" enable_autoupdate="yes" prev="" display="">
    <toolbtn name="gotodetails" func="session" type="list"/>
    <toolbtn name="kill"/>
    <col name="name" sort="alpha" sorted="+1"/>
    <col name="level"/>
    <col name="ip"/>
    <col name="idle"/>
  </block>
  <block name="longtask" position="right" type="list" func="longtask" rows="5" enable_autoupdate="yes" prev="" display="">
    <toolbtn name="gotodetails" func="longtask" type="list"/>
    <toolbtn name="view" default="yes"/>
    <toolbtn name="delete"/>
    <col name="realname" type="data" sort="alpha"/>
    <col name="startdate" type="data" sort="alpha" sorted="-1"/>
    <col name="enddate" type="data" sort="alpha"/>
    <col name="state" sort="prop"/>
  </block>
  <block name="authlog" position="right" type="list" func="authlog" rows="5" enable_autoupdate="yes" prev="" display="">
    <toolbtn name="gotodetails" func="authlog" type="list"/>
    <col name="time" sort="alpha" sorted="-1"/>
    <col name="user" sort="alpha" sorted="+2"/>
    <col name="ip" sort="alpha"/>
  </block>
  <block name="taskbar" position="left" type="toolbar" display="" prev=""/>
  <block name="sysinfo" position="left" type="list" func="dashboard.sysinfo" enable_autoupdate="yes" prev="" display="">
    <toolbtn name="gotodetails" func="sysinfo" type="list"/>
  </block>
  <block name="software_info" position="left" type="software" func="dashboard.software" prev="" display="">
    <toolbtn name="gotodetails" func="feature" type="list"/>
  </block>
  <block name="changelog.changes" position="left" type="changelog" func="changelog.changes" rows="5" prev="" display="">
    <toolbtn name="gotodetails" func="changelog" type="list"/>
    <col name="desc" sorted="+1"/>
    <col name="type"/>
  </block>
  <block name="new_features" position="top" type="url" display="" prev="">
    <url>https://www.ispmanager.ru/sites/all/themes/custom/ispmanagertheme/ispmanageradv/ru6/?mgrurl=https://localhost:4200/ispmgr</url>
  </block>
  <messages name="dashboard" checked="3a604f5c3c6d5683f90a1f63f1d171aa">
    <msg name="actioncolumn">Action</msg>
    <msg name="taskbar_admin">Panel administrator</msg>
    <msg name="taskbar_help">Help</msg>
    <msg name="taskbar_usrparam">User settings</msg>
    <msg name="title">Dashboard</msg>
    <msg name="title_changelog.changes">Changelog 6.84.0</msg>
    <msg name="title_usageinfo">Time usage</msg>
    <msg name="title_taskbar">Taskbar</msg>
    <msg name="hint_reload">Update data</msg>
    <msg name="tip_dashboard_top">You can add a panel administrator and log in to it in one click (most administration tasks are performed with admin privileges)</msg>
    <msg name="title_new_features">New features</msg>
    <msg name="taskbar_adduser">Create user</msg>
    <msg name="taskbar_addwebdomain">Create site</msg>
    <msg name="taskbar_addemail">Create mailbox</msg>
    <msg name="taskbar_adddomain">Create domain</msg>
    <msg name="taskbar_shellclient">Launch Shell client</msg>
    <msg name="taskbar_addsorter">Set email filter</msg>
    <msg name="taskbar_responder_settings">Configure autoresponder</msg>
    <msg name="taskbar_phpmyadmin">Open phpMyAdmin</msg>
    <msg name="taskbar_phppgadmin">Open phpPgAdmin</msg>
    <msg name="taskbar_roundcube">Open webmail client</msg>
    <msg name="taskbar_adddatabase">Creare database</msg>
    <msg name="taskbar_addemaildomain">Create mail domain</msg>
    <msg name="taskbar_adddocker">Create Docker container</msg>
    <msg name="taskbar_addcron">Create a Cron job</msg>
    <msg name="taskbar_addbackup">Crate backup</msg>
    <msg name="taskbar_addftp_user">Create FTP user</msg>
    <msg name="taskbar_execute">Execute command</msg>
    <msg name="taskbar_restart">Reboot server</msg>
    <msg name="taskbar_update">Update the panel</msg>
    <msg name="title_license.mgr.info">About Ispmanager Trial</msg>
    <msg name="title_capacity">Server resources</msg>
    <msg name="title_session">Active sessions</msg>
    <msg name="title_longtask">Background tasks</msg>
    <msg name="title_authlog">Access log</msg>
    <msg name="title_sysinfo">System information</msg>
    <msg name="title_software_info">Server software</msg>
  </messages>
  <blockOrder>{"3col":[["capacity","license.mgr.info","session"],["longtask","authlog","sysinfo"],["software_info","changelog.changes"]],"2col":[["capacity","license.mgr.info","session","longtask"],["authlog","sysinfo","software_info","changelog.changes"]]}</blockOrder>
  <tparams>
    <out>devel</out>
    <func>dashboard</func>
  </tparams>
  <saved_filters/>
</doc>

<block> element

XML block example

<block name="authlog" position="right" type="list" func="authlog" rows="5" enable_autoupdate="yes" prev="" display="">
  <toolbtn name="gotodetails" func="authlog" type="list"/>
  <col name="time" sort="alpha" sorted="-1"/>
  <col name="user" sort="alpha" sorted="+2"/>
  <col name="ip" sort="alpha"/>
</block>

name attribute

A unique block name. It is used for identifying blocks in the Dashboard. It is also used for languages

type attribute 

A block type. Possible values:

toolbar

Quick action bar, always displayed at the top

list, report 

A list or a list-based chart, both currently denote the same type

url

An HTML banner which content is retrieved from a given URL, is always displayed at the top

 isplicense, software, changelog

specialized types of blocks for displaying information about the license, software versions and latest updates, respectively

autoupdate attribute

Sets the block update timeout, in seconds

update attribute

Sets the block update when switching to the dashboard

display attribute

Indicates the state of the block, takes min/max values ​​for collapsed or expanded display, respectively

func attribute

name of the function to call to get the block content. Relevant for types list, report, isplicense, changelog, software

position attribute

Not used in the dragon theme (currently used in ispmanager). In the orion theme, block position can take the ​​top, left, right values 

Description of the quick action block (type="toolbar")

XML block example

<block name="taskbar" position="top" type="toolbar">
  <toolbtn form="site.edit" img="d-site" name="addwebdomain" spritesvg="yes"/>
  <toolbtn form="wordpress.theme" img="d-wordpress" name="addwordpressdomain" spritesvg="yes"/>
  <toolbtn window="dashboard.phpmyadmin" img="d-phpmyadmin" name="phpmyadmin" spritesvg="yes"/>
</block>k>

A control panel block contains a number of buttons for quick access to panel's functions.

Each button is described by a <toolbtn> tag with the following attributes:

window

if set, the button opens a new window (attribute value — function name)

top

presence of this attribute indicates that the function from the attribute value should be called and the displayed UI panel should be updated (can be used for actions that add new items to the menu, etc.)

form

if specified, the button will open a form (the value of the attribute is a function name)

list

if specified, the button will open a list (the value of the attribute is a function name)

img

name of the icon on the button; if the spritesvg attribute is not set, the .png extension is added to the name in the img attribute and a file with that name in the /usr/local/mgr5/skins/common/img folder is used; with spritesvg="yes" the attribute value specifies the name of the icon in the standard ispmanager sprite

spritesvg

spritesvg="yes" indicates that the icon should be taken from the standard SVG sprite ispmanager

customicon

path to the custom svg icon in absolute or relative form. The relative path should look as follows: `/manimg/dragon/default/google.svg`, i.e. the alias `/manimg` is used, which leads to the `/skins` folder. The icon can be of any size and color, but in the interface it will be converted to a single-color standard size

name

a unique name for the button within the block, intended to identify the button and for cocalization purposes

Localization

See "Description of localization messages" at the end of the article.

Description of list-block (type="list")

Example of the list-block (type="list")

<block name="authlog" position="right" type="list" func="authlog" rows="5" enable_autoupdate="yes" prev="" display="">
  <toolbtn name="gotodetails" func="authlog" type="list"/>
  <col name="time" sort="alpha" sorted="-1"/>
  <col name="user" sort="alpha" sorted="+2"/>
  <col name="ip" sort="alpha"/>
</block>

A list-block is used for describing a list (table) of data or a graph constructed from a data table. Buttons can be located in an additional column, in each row.

The <block type="list"> element can contain 2 types of tags: <col> (table columns) and <toolbtn> (buttons).

Please note!
There must be a column  (<col>)  with the sorted attribute. Otherwise, the limitation on the number of displayed rows specified by the rows attribute will not work.

The tag has the following additional attributes:

func attribute

function name (action name), which data should be shown in that block

rows attribute

limits the number of rows to be displayed on the Dashboard

The toolbtn element

Describes a button.

type attribute

If type="list" is specified, the button will be displayed at the bottom of the table, otherwise the button will be displayed in each table row in the last column.

func attribute

Used with type="list", specifies a function that should be called when the button is clicked.

name attribute

Button unique name; must match the name of the function button (action name) — see the func attribute of the list-block.

The col element

Describes a column.

name attribute

Column name; must match the name of the column of data passed to the function specified by the func attribute of the <block> element.

Data delivery for a list block

Each block with type="list" when displaying the Dashboard (and during auto-refresh, if enabled for the block) makes a separate HTTP request of the form GET MGR_URL?func=[block function]&dashboard=[block name], where the function and block name are specified by the func and name attributes of the <block> element. The XML returned by such a function complies with the general format of XML page descriptions. The <doc> element of the received data must contain <elem> elements with data for the table displayed in the block, similar to how data is passed for list pages. In addition, the <metadata> element can contain a <band> element, which is used to build a graph inside the block based on data from the <reportdata> element, similar to data for report pages.

Description of the banner block (type="url")

Example of block-html description (type="url")

        <block name="journal" position="top" type="url">
               <url>https://ispsystem.com/journal?manager=__manager__</url>
        </block>

Block-html is designed to insert an arbitrary html from a given address. It contains one tag: (address of arbitrary html).

Please note that if the panel is accessed via https, the browser will block http addresses and https addresses with a suspicious certificate.

Description of the block with type="software"

This is a list of label-value type, divided into groups.

Screenshot:

 

The data to be displayed is obtained by requesting GET MGR_URL?func=[block function]&dashboard=[block name], where the function and block name are specified by the func and name attributes of the <block> element.

Example XML for the data to be obtained:

<doc lang="ru" func="dashboard.software">
  <metadata name="dashboard.software" type="infolist" mgr="ispmgr" dashboard="yes">
    <rowdata>
      <rowgroup name="soft">
        <row name="apache_version" type="data"/>
        <row name="mysql_version" type="data"/>
        <row name="php_version" type="data"/>
        <row name="kernel_version" type="data"/>
      </rowgroup>
    </rowdata>
  </metadata>
  <messages name="dashboard.software" checked="a5b30e8b989f395a98cadceb52f96ff9">
    <msg name="title">Server software</msg>
    <msg name="soft">Software versions</msg>
    <msg name="apache_version">Apache</msg>
    <msg name="mysql_version">MySQL</msg>
    <msg name="php_version">PHP</msg>
    <msg name="phpcgi_version">PHP (CGI)</msg>
    <msg name="perl_version">Perl</msg>
    <msg name="kernel_version">Kernel</msg>
    <msg name="short_gotodetails">Go to section</msg>
    <msg name="actioncolumn">Action</msg>
  </messages>
  <elem>
    <apache_version>2.4.41-4ubuntu3.23</apache_version>
  </elem>
  <elem>
    <kernel_version>5.4.0-208-generic </kernel_version>
  </elem>
  <elem>
    <mysql_version>8.0.42-0ubuntu0.20.04.1</mysql_version>
  </elem>
  <elem>
    <php_version>7.4.3-4ubuntu2.29</php_version>
  </elem>
</doc>

The rowgroup element

A group of elements united by a certain logic.

rowgroup attributes

name attribute

an element name, used for group's name localization.

The row element

Describes a row.

row attributes

name attribute

an element name, used for row's name localization.

Description of the block with type="isplicense"

The block displays information about the current license of the panel. The data for display is obtained by requesting GET MGR_URL?func=[block function]&dashboard=[block name], where the function and block name are specified by the func and name attributes of the <block> element.

Description of the block with type="changelog"

The block displays information about changes in the latest version of the panel. The data for display is obtained by requesting GET MGR_URL?func=[block function]&dashboard=[block name], where the function and block name are specified by the func and name attributes of the <block> element. 

Localization messages description

Most Dashboard messages are uploaded automatically by the name of the specified function when a request is made to the data of a specific block. However, some messages need to be specified in the XML for the dashboard function, for example in the plugin's XML description file.

Example of message description

	<messages name="dashboard">
		<msg name="title">/Dashboard</msg>
		<msg name="title_taskbar">Toolbar panel</msg>
		<msg name="taskbar_usrparam">Control panel</msg>
		<msg name="taskbar_report">Operation log. Report</msg>
		<msg name="taskbar_brand">Branding settings</msg>
	</messages>

msg name="title"

describes the Dashboard heading

msg name="title_[block]"

describes the block name; [block] — block name (<block>)  

msg name="[block]_[button]"

describes the button caption; [block] — block name (<block>), [button] — button name (<toolbtn>); used for toolbar blocks (for example, <msg name="taskbar_addwebdomain"> in standard ispmanager quick actions for the "Create site" button with name="addwebdomain" of the quick action block with name="taskbar"), for list blocks, localization messages for buttons are obtained in requests by the name of a specific function along with the data of a specific block.

 

In this article