First steps: "Hello, World!" plugin

This article describes the process of creating a plugin in ispmanager with a bash script handler. As a result, a new menu item will be created with the “Hello, world!” page.

What will be required

• Edit and upload files. Use the File manager or connect to the server via SSH or FTP.
  
• Super administrator (root) privileges to perform actions.
  

XML description of the plugin

The code of any ispmanager plugin will necessarily include an XML file that describes the changes that are added by the plugin.

For ispmanager to see this plugin, its XML description file must:

• be located in /usr/local/mgr5/etc/xml directory;
• the filename must be in ispmgr_mod_*.xml format.

To create a plugin:

1. Open /usr/local/mgr5/etc/xml directory.

2. Create ispmgr_mod_helloworld.xml file in it.

3. Copy and paste the XML code below into the file you created:

<?xml version="1.0" encoding="UTF-8"?>
<!-- The mgrdata tag should always be at the top level of any plugin -->
<mgrdata>
    <!-- section that adds groups and items to the menu -->
    <mainmenu level="30">
        <!-- in modern versions of ispmanager the main menu is described by 
             the modernmenu tag inside the mainmenu tag -->
        <modernmenu>
            <!-- ispmanager has two-level menus - groups within which 
                 items are links to pages, and for both of them 
                 node tag is used; if we want to create 
                 menu item without a group, add at the group level the attribute type="noname" -->
            <node name="helloworld_group" type="noname">
                <!-- the second-level node tag specifies a particular menu item,
                     the name attribute is used as a func for the page when specifying the handler well as for specifying the localization string in the msg tag below -->
                <node name="helloworld" />
            </node>
        </modernmenu>
    </mainmenu>
 
 <!-- the handler tag specifies the, handler file name - 
         in the name attribute -->
    <handler name="helloworld.sh" type="xml">
        <!-- the func tag inside the handler tag defines which calls (e.g. pages)
             will be handled by this handler. -->
        <func name="helloworld" />
    </handler>
    
    <!-- the lang tag specifies a section of localization messages for one language,
         it can contain localization messages for many pages within it -->
    <lang name="ru"> 
        <!-- the messages tag specifies a localization message section for one func 
             or, in this case — for navigational elements common for all
             pages (name="desktop") -->
        <messages name="desktop">
            <!-- the msg tag specifies a localization string with a single 
                 attribute-identifier name. In this case,the
                 modernmenu_ prefix indicates that we are specifying a localization for a
                 menu item with the name specified after the prefix -->
            <msg name="modernmenu_helloworld">Plugin Hello, World </msg>
        </messages>
    </lang>
</mgrdata>

The XML code above is an explanation of what happens on each line.

Other concepts that will be encountered throughout the plugin development process include:

• func, «function» — identifier of some part of ispmanager functionality (built-in or added in plugins) used in ispmanager API. Every ispmanager page is necessarily bound to some function that provides data for displaying the page. In some cases, a function may serve several pages or, on the contrary, the functionality of one page may involve several functions. The function identifier links the different parts of the functionality together. In the given XML description of the plugin, it is specified for a menu item (<node name="helloworld" />) and links the menu item and the handler that should return data to display the page when the menu item is selected;

• localization strings — the text for UI elements is set separately from the elements themselves (in the case above, the text for a menu item is set separately from the menu item itself). To specify the language, the <lang> tag is used, within which there may be one or more <messages> tags, and each individual line is specified by the <msg> tag.

In the above XML description of the plugin there is a link to a handler file, this will be the second file you need to create for your plugin.

Handler

Plugin handler files must meet the following requirements:

• be located in the /usr/local/mgr5/addon folder;
• there are no restrictions for the file name, but the file must be executable for the root user and group.

To create a handler:

1. Go to /usr/local/mgr5/addon folder.

2. Create the helloworld.sh file in it (the file name you specified in the name attribute of the <handler> tag in the plugin's XML description).

3. Assign permissions 750 to the file using the Attributes button in the File Manager or using the console command:

chmod 750 /usr/local/mgr5/addon/helloworld.sh

4. Copy the bash handler script code below. Paste it into the file you have created:

#!/bin/bash
cat << EOM
<?xml version="1.0" encoding="UTF-8"?>
<doc lang="ru" func="helloworld">
    <metadata type="form">
        <form>
            <field name="helloworld_field">
                <textdata name="helloworld_message" type="msg" /> 
            </field>
        </form>
    </metadata>
    <messages>
        <msg name="title">Plugin Hello, world!</msg>
        <msg name="helloworld_message">Hello, world!</msg>
    </messages>
</doc>

Plugin activation

1. Run the following command from the terminal to restart the ispmanager panel (you can also use the Shell client menu page in ispmanager):

pkill core

2. Refresh the ispmanager panel page.

Result

There is a new item Plugin Hello, World in the menu.

If you click it, it will open your plugin page.

Conclusion

The created handler outputs static XML code that is placed between the EOM on the second line and the EOM on the last line. The func value from the plugin's XML description is used here in the func attribute of the <doc> tag.

There are also <messages> and <msg> tags you've come across in the plugin's XML description, which specify localization strings. In general, this XML describes a page of type "form", which has a header and a single field (<field>) with static text (<textdata>).

For a more detailed description of plugins, please see Structure and functionality of plugins.