For developers

/
/
/
Plug-in example: templates engine management

Plug-in example: templates engine management

Here's an example of a plugin for adding new fields to a website editing form and passing values ​​to the template engine. For demonstration purposes, we'll implement control over the nginx limit_rate parameter. On the website editing form, in the "Optimization and DDoS protection" tab, we'll add a "Rate ​​limit" field.

Control panel plugins are represented by XML files containing the plugin description. These files enable the customization of the plugin interface by adding or hiding various elements. 

The location of XML files is strictly defined, they must be located in the directory /usr/local/mgr5/etc/xml/. The name of each file should start with the prefix ispmgr_mod_ and end with a specific plugin name, for example ispmgr_mod_nginx_rate_limit.xml.

The XML file must have read/write permissions for the root user.

XML description of the plugin

<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
 <metadata name="site.edit" type="form">
    <form>
      <page name="optimization">
        <field name="site_nginx_rate_limit">
          <input type="text" name="site_nginx_rate_limit" check="int" checkargs="1,100000000000" />
        </field>
      </page>
    </form>
  </metadata>
  <metadata name="webdomain.edit" type="form">
    <form>
      <page name="optimization">
        <field name="nginx_rate_limit">
          <input type="text" name="nginx_rate_limit" check="int" checkargs="1,100000000000" />
        </field>
      </page>
    </form>
  </metadata>
  <lang name="en">
    <messages name="site.edit">
      <msg name="site_nginx_rate_limit">Rate limit</msg>
      <msg name="hint_site_nginx_rate_limit">Limits the rate of response transmission to a client</msg>
    </messages>
  </lang>
</mgrdata>

The information in two metadata blocks describes the procedure for adding a new field to the website editing form. This form has the attribute type="form" and the identifier name="webdomain.edit". The field will be added to the tab named "Optimization and DDoS protection" page name="optimization". The new field will have the identifier name="nginx_rate_limit" and the type "string field" type="text". Data validation will check the value as an integer in the range 1.1000000000000 check="int" checkargs="1.100000000000".

In the <metadata name="site.edit" type="form"> block, add the "site_" prefix to the field name.

Example: <field name="site_nginx_rate_limit">

Without this prefix, the plugin will not work!

The lang section defines description and hints in English. 

After adding new parameters via XML, restart the control panel using the following command:

/usr/local/mgr5/sbin/mgrctl -m ispmgr exit

Additional fields

To save form data to the panel's database, add a new column to the webdomain table. This can be done with the built-in mechanism.

Create the file /usr/local/mgr5/etc/sql/webdomain.addon/nginx_rate_limit with the following contents:

type=int
access_read=user+
access_write=user+

Templates

Editing the template file determines the directives that will be included in the Nginx configuration file.

Copy /usr/local/mgr5/etc/templates/default/nginx-vhosts.template and /usr/local/mgr5/etc/templates/default/nginx-vhosts-ssl.template to the /usr/local/mgr5/etc/templates/ directory.

In the /usr/local/mgr5/etc/templates/default/nginx-vhosts.template file, add the following:

{% if $NGINX_RATE_LIMIT != "" %}
    limit_rate [% $NGINX_RATE_LIMIT %];
{% endif %}

Change the path to the SSL template:

{% import etc/templates/nginx-vhosts-ssl.template %}

To the /usr/local/mgr5/etc/templates/nginx-vhosts-ssl.template file, add the following:

{% if $NGINX_RATE_LIMIT != "" %}
    limit_rate [% $NGINX_RATE_LIMIT %];
{% endif %}

Templates are updated as new features are added to the control panel. When you create custom templates (as in this example), you must update them manually to match the built-in templates.

Clear the database cache and restart ispmanager:

rm -rf /usr/local/mgr5/var/.db.cache*
/usr/local/mgr5/sbin/mgrctl -m ispmgr exit

The full plugin code can be downloaded from GitHub. To install it, simply run:

git clone https://github.com/ispmanager-official/plugin-examples.git
cd plugin-examples
./install.sh template-nginx-rate-limit

The system will be restarted automatically.

Filtering unknown parameters

Starting with ispmanager version 6.139.0, fields not declared in XML will be removed from the request and will not be passed to the handler or template engine. For example, if you added a new parameter in the site.edit handler but did not declare it in XML and instead passed it via the API, this parameter will not be passed to the handler.

If you need to pass parameters that are not present in the form via the API to the handler or template engine, add this field to the form's XML description with the hidden type and the safe_value="yes" tag. Example:

<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
 <metadata name="site.edit" type="form">
    <form>
      <page name="mainsettings">
        <field name="site_custom_param">
          <input type="hidden" name="site_custom_param" safe_value="yes"/>
        </field>
      </page>
    </form>
  </metadata>
  <metadata name="webdomain.edit" type="form">
    <form>
      <page name="mainsettings">
        <field name="custom_param">
          <input type="hidden" name="custom_param" safe_value="yes"/>
        </field>
      </page>
    </form>
  </metadata>
</mgrdata>

This change affects the following functions:

site.edit
webdomain.edit
webdomain.suspend
webdomain.resume
webdomain.delete
webdomain.error.edit
webdomain.error.delete
webdomain.redirect.edit
webdomain.redirect.delete
webdomain.diraccess.edit
In this article