Developer Guide

/
/
/
Report plugin example

Report plugin example

Below is an example of a report plugin with a diagram, a table and data selection form. Unlike the example given in the article Description of reports, where the data for the report was generated by the panel through a request in the <query> element, the data here will be passed from the plugin handler code.

Plugin XML description

Please refer to this article to find more information about structure and functionality of plugins.

Let's create a file /usr/local/mgr5/etc/xml/ispmgr_mod_report_example.xml with the following contents:

/usr/local/mgr5/etc/xml/ispmgr_mod_report_example.xml
<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
    <mainmenu level="admin+">
        <modernmenu>
            <node name="my_group" icon="m-plugin">
                <node name="report.example" icon="m-plugin"/>
            </node>
        </modernmenu>
    </mainmenu>
    <handler name="report_example.sh" type="xml">
        <func name="report.example" />
    </handler>
    <lang name="en">
        <messages name="desktop">
            <msg name="modernmenu_my_group">Plugins</msg>
            <msg name="modernmenu_report.example">Report example</msg>
        </messages>
    </lang>
</mgrdata>

This is how a new Plugins — Report example section is added. It points to the report.example function and registers the report_example.sh handler for this function.

Plugin handler

Let's create a handler file /usr/local/mgr5/addon/report_example.sh and give it permissions 750 (root user and group). The contents of the file will be the following:

/usr/local/mgr5/addon/report_example.sh
#!/bin/bash

# notice the value that came from the form from <select name=“period” /> and
# if the “Previous month” option was selected, one set of strings will be written to the variable reportdata,
# in other cases (including default options before selection in the form) - else
period=$PARAM_period
if [[ "$period" == "previousmonth" ]]
then
read -r -d '' reportdata <<-EOM
    <elem><value1>7.0</value1><value2>13.0</value2><date>2024-10-29</date></elem>
    <elem><value1>10.0</value1><value2>26.0</value2><date>2024-10-30</date></elem>
    <elem><value1>12.0</value1><value2>11.0</value2><date>2024-10-31</date></elem>
EOM
else
read -r -d '' reportdata <<-EOM
    <elem><value1>10.0</value1><value2>24.0</value2><date>2024-11-01</date></elem>
    <elem><value1>12.0</value1><value2>18.0</value2><date>2024-11-02</date></elem>
    <elem><value1>8.0</value1><value2>20.0</value2><date>2024-11-03</date></elem>
EOM
fi

# output an XML for the page with a set of lines above incorporated in it
cat << EOM
<?xml version="1.0" encoding="UTF-8"?>
<doc lang="ru" func="report.example">
    <metadata type="report">
        
        <!-- form metadata for period selection at the top of the report -->
        <form>
            <field name="period">
                <select name="period" />
            </field>
            <buttons>
                <button type="ok" action="report.example" name="ok"/>
            </buttons>
        </form>
        
        <!-- Page title -->
        <text name="title" />
        
        <!-- Report description: one table withe three columns and a diagram based on the table -->
        <band name="values" psort="date">
            <col name="date" type="data" sort="alpha" />
            <col name="value1" type="data" sort="digit" />
            <col name="value2" type="data" sort="digit" />
            <diagram name="values" label="date" type="line" >
                <line data="value1" />
                <line data="value2" />
            </diagram>
        </band>
    </metadata>
    
    <!-- report data, insert the generated set of <elem> lines here-->
    <reportdata>
        <values>
            ${reportdata}
        </values>
    </reportdata>
    
    <!-- Localization messages -->
    <messages>
        <msg name="title">Report example</msg>
        <msg name="values">Series of values</msg>
        <msg name="value1">Parameter 1</msg>
        <msg name="value2">Parameter 2</msg>
        <msg name="date">Date</msg>
        <msg name="period">Period</msg>
        <msg name="msg_ok">Show the report</msg>
        <msg name="msg_hidedata">Hide data</msg>
        <msg name="msg_nodata">No data</msg>
        <msg name="msg_showdata">Show data</msg>
    </messages>
    
    <!-- values for period selection form -->
    <slist name="period">
        <val msg="yes" key="currentmonth">Current month</val>
        <val msg="yes" key="previousmonth">Previous month</val>
    </slist>
    
    <!-- value of the selected period to be displayed in the selection form after data submission-->
    <period>${period}</period>
</doc>
EOM

Now, for ispmanager to apply the added XML description of the plugin, execute the command in the server command line:

pkill core

Result

After reloading the page in the browser, a new group Plugins should appear in the Navigation board section (the very last menu item) and an item Report example. After clicking on the Report example item you will open the report page:

Details

Find more information on how the code works in the created file /usr/local/mgr5/addon/report_example.sh.

Additionally note:

  • This article gives an example of code for a simple report with one table and a diagram on the data from the table. Ispmanager allows you to generate more complex reports with child tables and diagrams. See an example of data transfer for such reports in the article Description of reports.
  • Transferring and receiving form data with report parameters is also performed as demonstrated in the article Example of using form field values. The same features are available for creating forms at the top of reports as in regular forms.

In this article