Adding control elements

From ISPWiki

Following is an example on how to add a custom parameter into the interface.

Task

• We need to a add a desired web mail program into the user properties form in ISPmanager.
• A list of available web-mail programs is located in the /usr/local/ispmgr/etc/webmail.list file:

squirrelmail /webmail/
roundcube /roundcube/

Solution

1) Create a file /usr/local/ispmgr/etc/ispmgr_mod_userwebmail.xml with the following content to describe a plug-in

<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
    <handler name="userwebmail.pl" type="cgi">
      <event after="yes">usrparam</event>
    </handler>
    <metadata name="usrparam">
        <form>
           <field name="webmail">
              <select name="webmail"/>
           </field>
        </form>
    </metadata>
    <lang name="en">
        <messages name="usrparam">
            <msg name="webmail">Favorite webmail</msg>
            <msg name="hint_webmail">Favorite webmail</msg>
            <msg name="squirrelmail">SquirrelMail</msg>
            <msg name="roundcube">RoundCube</msg>
        </messages>
    </lang>
    <lang name="ru">
        <messages name="usrparam">
            <msg name="webmail">Web mail</msg>
            <msg name="hint_webmail">Interface of a desired web mail.</msg>
        </messages>
    </lang>
</mgrdata>

2) Create a file handler /usr/local/ispmgr/addon/userwebmail.pl with the following contents

#!/usr/bin/perl
use CGI;
my $Q = new CGI;
open DATA, "<var/user.webmail";
my @rows = <DATA>;
close DATA;
my $user = $ENV{"REMOTE_USER"};
 
if ($Q->param("sok")) {
       open DATA, ">var/user.webmail";
       foreach $row (@rows) {
           my @elems = split / /, $row, 2;
           printf DATA "%s", $row if ($elems[0] ne $user);
       }
       printf DATA "%s %s\n", $user, $Q->param("webmail");
       close DATA;
 
       print "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<doc/>\n";
} else {
       print "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<doc>\n";
 
       foreach $row (@rows) {
           chomp($row);
           my @elems = split / /, $row, 2;
           if ($elems[0] eq $user) {
               print "<webmail>$elems[1]</webmail>\n";
               last;
           }
       }
 
       # Provide a list of possible web-mail interfaces
       print "<slist name=\"webmail\">\n";
       open WLIST, "<etc/webmail.list";
       my @wlist = <WLIST>;
       close WLIST;
       foreach $webmail (@wlist) {
           my @elems = split / /, $webmail, 2;
           print "<msg>$elems[0]</msg>\n";
       }
       print "</slist>\n";
 
       print "</doc>\n";
}

3) Set privileges on the file handler

chmod 750 /usr/local/ispmgr/addon/userwebmail.pl
chown 0:0 /usr/local/ispmgr/addon/userwebmail.pl

4) Restart ISPmanager

Comments

Use the function of the user "General settings" module, which internal name is "usrparam". Add a new field called "webmail" into the interface of this form. The field will be displayed as a select drop-down list

   <metadata name="usrparam">
       <form>
          <field name="webmail">
             <select name="webmail"/>
          </field>
       </form>
   </metadata>

Add ru and en text messages into the interface description

• Text to the left of the input field

           <msg name="webmail">Web mail</msg>

• Text with detailed information that appears when moving a mouse cursor over a field

           <msg name="hint_webmail">Interface of a desired web mail.</msg>

• Names of the existing web mail interfaces (we add only en texts, because they do not need to be translated into other languages)

           <msg name="squirrelmail">SquirrelMail</msg>
           <msg name="roundcube">RoundCube</msg>

To perform operations we need a script handler that will be called while calling the usrparam function. Describe it

   <handler name="userwebmail.pl" type="cgi">
     <event after="yes">usrparam</event>
   </handler>

Let's consider the script handler.

Get the parameters

use CGI;
my $Q = new CGI;

Open the /usr/local/ispmgr/var/user.webmail file where the user web mail 's settings will be kept:

open DATA, "<var/user.webmail";
my @rows = <DATA>;
close DATA;

An operational directory is always the one where a control panel is installed (in our example /usr/local/ispmgr), so we use the relative path to the "var/user.webmail" file. We recommend using relative paths, because some control panels allow to install into any directory, thus the use of absolute paths may cause problems. Locate the user who is making a request

my $user = $ENV{"REMOTE_USER"};

Check when the edit and record function was called

if ($Q->param("sok")) {

Rewrite the user data, except for the name of the user who is making a request

      open DATA, ">var/user.webmail";
      foreach $row (@rows) {
          my @elems = split / /, $row, 2;
          printf DATA "%s", $row if ($elems[0] ne $user);
      }

Specify the selected web mail into the file

      printf DATA "%s %s\n", $user, $Q->param("webmail");

As no results should be returned, we return an empty XML document

print "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<doc/>\n";

Reading user settings

Find settings of the user who is making a request and add his settings data

      foreach $row (@rows) {
          chomp($row);
          my @elems = split / /, $row, 2;
          if ($elems[0] eq $user) {
              print "<webmail>$elems[1]</webmail>\n";
              last;
          }
      }

Since we selected a drop-down list as an interface control element, we need to specify its possible values, take a list of available web mail interfaces from the file and add this information into the output XML document

      print "<slist name=\"webmail\">\n";
      open WLIST, "<etc/webmail.list";
      my @wlist = <WLIST>;
      close WLIST;
      foreach $webmail (@wlist) {
          my @elems = split / /, $webmail, 2;
          print "<msg>$elems[0]</msg>\n";
      }
      print "</slist>\n";

More information can be found in the article Drop-down lists