Plug-in example: templates engine management

Our task is to add the checkbox "1C-Bitrix" on the domain edit form. Depending on the checkbox status, different values for the directive open_basedir will be automatically integrated to the configuration Apache file:

• the checkbox is selected — the open_basedir value is "none";
• the checkbox is empty — the open_basedir value equals the domain home directory.

Control panel plug-ins are represented by XML files containing the plug-in description. These files enable the customization of the plug-in interface by adding or hiding various elements. The XML file also describes a handler, which is a script that is executed before or after certain actions take place in the control panel.

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 plug-in name, for example /usr/local/mgr5/etc/xml/ispmgr_mod_bitrix.xml

XML description of the plugin

<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
 <metadata name="site.edit" type="form">
    <form>
      <page name="additional">
        <field name="site_drupal_nginx">
          <input type="checkbox" name="site_drupal_nginx" />
        </field>
      </page>
    </form>
  </metadata>

  <metadata name="webdomain.edit" type="form">
    <form>
      <page name="additional">
        <field name="drupal_nginx">
          <input type="checkbox" name="drupal_nginx" />
        </field>
      </page>
    </form>
  </metadata>

  <lang name="ru">
    <messages name="site.edit">
      <msg name="site_drupal_nginx">Drupal NGINX</msg>
      <msg name="hint_site_drupal_nginx">Отметьте, чтобы конфигурации NGINX были оптимизированы под Drupal.</msg>
    </messages>
  </lang>
  
  <lang name="en">
    <messages name="site.edit">
      <msg name="site_drupal_nginx">Drupal NGINX</msg>
      <msg name="hint_site_drupal_nginx">Check for optimized Drupal NGINX config.</msg>
    </messages>
  </lang>
</mgrdata>

The information about the two metadata sections describes the procedure for adding a new field to the web domain edit form.  This form has attribute type=“form” and identifier name=“webdomain.edit”. The field will be added to the tab with WWW-domain page name=“domain”. The new field will have identifier name=“bitrix” and type "checkbox" type=“checkbox”.

For the site.edit section, it is recommended to add the prefix site_ for better identification. 

<field name="site_drupal_nginx">

The handler section defines the next actions after editing the web domain (webdomain.edit). After the web domain is edited, a script named bitrix (handler name=“bitrix”) with  the xml type  (type=“xml”) will be called.

The type xml indicates that an XML file with parameters will be passed to the script via standard input (stdin). The plug-in must return the same XML as a response via standard output (stdout), where custom parameters can be added or existing parameters can be modified.

The lang section defines description and hints in the Russian and English languages. 

After you have added the custom xml, restart the control panel using the following command:

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

Additional fields

If additional fields, such as checkboxes or other items, need to be added to a table, the corresponding table must be modified. For instance, if the checkbox is positioned in the Sites section, the webdomain table will need to be modified. For more information, please follow the link.

Handler

• location: the handler script must always be located in the /usr/local/mgr5/addon directory;
• file name: the file name must match the one specified in XML in the handler section.

In our example, we have the file /usr/local/mgr5/addon/bitrix, which has the following contents:

#!/bin/bash 

if [[ "$PARAM_bitrix" = "on" ]] 
        then    
                cat | sed 's|</doc>$|<params><CUSTOM_BASEDIR>none</CUSTOM_BASEDIR></params></doc>|'
        else    
                cat | sed 's|</doc>$|<params><CUSTOM_BASEDIR>'$PARAM_docroot':.</CUSTOM_BASEDIR></params></doc>|'
fi

Set permissions for the handler with the following commands:

chmod 750 /usr/local/mgr5/addon/<handler_file_name>
chown 0:0 /usr/local/mgr5/addon/<handler_file_name>

The value of the variable $PARAM_bitrix is checked in the condition. The control panel sends some parameters to the environment variables and they can be used in the plugin handler. $PARAM_bitrix is the variable that can be on, if the checkbox "1C-Bitrix" is selected on the domain edit form, and can be off, if the checkbox is not empty.

The plug-in returns to the control panel the same xml file that it has received to stdin input, but adds its custom parameter CUSTOM_BASEDIR. This parameter can have the value none, if the checkbox "1C-Bitrix" is selected, or <domain home directory>, if the checkbox is empty.

Editing the template engine file determines what directives will be specified in the Apache configuration file.

Edit the following line in the file /usr/local/mgr5/etc/templates/apache2-vhosts.template

 php_admin_value open_basedir "{% $BASEDIR_PATH %}"

into the line below:

 php_admin_value open_basedir "{% $CUSTOM_BASEDIR %}"