Plug-ins (VDSmanager)

From ISPWiki

(Redirected from Extensions (VDSmanager))

Plug-ins allow you to add modules into the control panel. This article describes how to create a module that will work with the list of random lines in the /etc/myconfig file. Using the example given below can may create a plug-in you need. Follow the instructions below to add your plug-in.

First step

Create an XML-document that will describe all the functions that this plug-in is supposed to process, and all the interface elements for the module to be displayed in the control panel.

Second step

Write a program or a script that will implement the function.

Creating an XML-document

Locate the XML document with the required extension interface description in the /usr/local/ispmgr/etc folder and name the file vdsmgr_mod_xxx.xml (choose any name you like instead of xxx, such as myconfig: vdsmgr_mod_myconfig.xml). The document should have UTF-8 encoding. See example below:

<?xml version="1.0" encoding="UTF-8"?> <mgrdata> plug-in functions description menu elements description forms and tables description messages description </mgrdata>

Describing the plug-in functions

This part of the XML-document determines the name of the program or script that implements functions, type of the interaction of the program and control panel, and the functions this plug-in provides. Example:

<handler name="program" type="type"> <func>function1</func> <func>function2</func> ... </handler>

Provide the program name for the name attribute, e.g. myconfig.pl. The type attribute is the control panel and your program type. Currently there are two possible types:

cgi means that the program has the CGI interface.
xml means that the program receives an XML document with the control panel receives the XML from STDIN.

Then you need to provide the functions that your plug-in is supposed to perform. The functions are as follows:

List of elements - is a table with the toolbar.
Element properties - you can use this form for adding a new element or edit an existing one. You can also use it, if you are going to use the module for setting specific parameters, rather than for working with multiple elements.
Action - does not have interface elements. This is an operation on the elements from the list.

The name of the function may contain the Latin alphabet letters, digits, dots. It must be unique. You can get a list of available functions with the command /usr/local/ispmgr/etc/vdsmgr.xml.

Describing menu elements

To access your plug-in, you need to create corresponding items in the control panel menu. Add the following block into your XML-document.

<mainmenu level="access level"> <node name="category name"> <node name="function1"/> <node name="function2"/> </node> </mainmenu>

Select a desired access level for your plug-in:

7 - VDSmanager administrator.
6 - reseller of the virtual private servers.
5 - owner of the virtual private servers.

Specify one of the above digits in the level attribute. If you want to make the module accessible on several levels, add the mainmenu block for each level.

As the category name specify the name from the name attribute of the node, corresponding to the category of navigation menu described in the /usr/local/ispmgr/etc/vdsmgr.xml. For example, you do not want to allow access to plug-in for all the VPS owners and set a special module in the "Tools" module of the navigation menu. To do so, find the <node name="tool">. section and a corresponding section node name="tool".

Add one or several menu elements into the corresponding section of the navigation menu. Add nodes and as the name attribute specify the name of the function to be called when clicking the corresponding icon.

Describing tables and forms

You need to describe the interface for the functions provided by this plug-in. Our test module needs to allow you to view existing records in the /etc/myconfig file, add new and edit existing records. Also, it needs to have the deletion function. Note, that the interface is not required for this function.

Write the following block into the XML-document to implement the records' list:

<metadata name="function1" type="list" key="field_name"> <toolbar> <toolbtn func="function2" type="new" img="t-new.gif" name="new"/> <toolbtn func="function2" type="edit" img="t-edit.gif" name="edit" default="yes"/> <toolbtn func="function3" type="group" img="t-delete.gif" name="delete"/> </toolbar> <coldata> <col sort="alpha" sorted="yes" name="field_name" type="data"/> </coldata> </metadata>

This means that we want to add the list-type (type="list") interface to our "function1", where the key element is "field_name" . A unique key element is required for identifying a record in the list. This value will be transferred to the functions working with such list elements as view element parameters, delete, etc.

Then describe the control panel that contains three icons: new (name="new"), edit (name="edit") and delete (name="delete"). You can specify the action to be performed when someone is double-clicking the record by adding the default="yes" attribute into required node. In our example double-clicking the record will call the edit function. One and the same function name is specified as the func attribute in two first control panel icons because one function will perform both creation and viewing, as well as editing of the record parameters. A function type is determined by the type attribute:

new - create a new element.
edit - edit an existing element.
group - perform operation over a group of elements.
editlist - child list associated with one of the current list elements.
list - child list which is not associated with any of the elements of the current list.

There is a block called coldata. You need to add the appropriate number of col nodes, one for each table column. In our example, the table consists of the only column where the field "field_name" will be displayed. The values are returned by the function for the list creation for each element. You need to specify the type of the column values. The following types are currently supported:

data - displays information about every element that is passed into the field which name is specified in name attribute (we have "field_name").
msg - this type can be used if you have a set of values returned into the field which name is specified in the name attribute, such as record status (active, disabled), and you want these values to be displayed differently according to the control panel languages. Therefore, the values must consist of the Latin alphabet letters, digits, dots and "_".

indicator - displays information (indicator) about resources usage, such as traffic or disk space. You need to add the XML-node with the name of this column for each element you want the indicator to be displayed. Then you should add two attributes to this node: used="number" and limit="number".

If you want to sort the data in the column, add the sorted="yes" attribute that will provide one of the following values:

alpha - lines composed of the Latin alphabet letters and digits.
digit - digits.
indicator - indicators (such as, traffic or disk space).
ip - IP-addresses.
prop - properties (for example, active\disabled).

If you want the elements of the table to be sorted automatically when entering the module, add the sorted="yes" attribute.

If you want to use the data from one or several columns for statistical information, add the stat="yes" attribute.

Then add description of the form for a new element creation and editing an existing element. To do that, add the following block to the XML-document:

<metadata name="function2" type="form"> <form> <field name="message"> <input type="text" name="field_name"/> </field> </form> </metadata>

This means that we add the form (type="form") for the "function2" function. Each control element needs to be described in the separate field block which consists of the title and the control element itself. The field title is specified in name attribute (in our example it has the value "message"). It is necessary to add the corresponding node to the message block of the function. The information on how to create messages blocks is given below. Then add the control element. The following types are supported::

input - input field. There are several types of input fields taht are specified in type attribute.
- text - line field.
- password - password field; when typing in a password all the characters are replaced with asterisks.
- checkbox - check box.
textarea - multi-line input field.
select - drop-down list.

Use the name attribute to specify the name of the function parameter which is associated with a certain control element. If you want to specify a default value of the control element, use the value attribute (value="default_value").

You may also use additional attributes for fields. If you want the field to be hidden by default and manage its visibility with javascript, add the hidden="yes" attribute. If you use <input type="text"/> as the control element, and several elements are supposed to be entered, you can add the zoom="5" attribute. Next to the text field an additional button will display. Clicking that button will enlarge the field by the number of lines specified in the attribute.

Describing messages

The control panel's messages is the text that you can see in the control panel. It is not associated with data obtained from the functions execution. The messages are divided into groups according to interface languages. You need to add the following block for each interface language:

<lang name="language"> navigation menu messages funstion messages </lang>

Use one of the following messages as a language:

de - German
en - English
es - Spanish
fr - French
ru - Russian

The default interface language is English. If another language is used and a required message in that language can not be found, the message in English will be used.

Then you need to add messages for all the menu items created in the "Describing elements" menu. Add the following block:

<messages name="desktop"> <msg name="menu_function1">message1</msg> <msg name="menu_function2">message2</msg> </messages>

That is for each menu item like <node name="function1"/> we have to add the message <msg name="menu_function1">message1</msg>.. Replace the "message1" with real name of the menu item in UTF-8 encoding.

All other messages are divided by functions, that's why for each function provided by your plug-in you need to add the following block into the XML-document:

<messages name="function1"> <msg name="message_name">message</msg> ... </messages>

The following standard messages for modules are available (use them instead of "message_name"):

title - module heading (list or form).
title_new - heading of the creation or edit form.
hint_default - hint for the module function.

All other messages are divided into the following types:

list columns names: specify the value from the name attribute of the col node.
values for a msg column: specify the value which can be passed in the element parameter returned by the function. In case of several values, add a separate message for each of them.
names for the form fields: specify the value from the name attribute of the field node.
values for select type control elements: specify the value which will be passed in this list. If the appropriate message is not found, then the value returned by the function will be displayed. In case of several values, add a separate message for each of them.
hints for the form fields: specify the value from the name attribute of the field node with hint_, for example hint_username.
hints for the toolbar icons: specify the value from the name attribute of the node toolbtn with the hint_ prefix, for example, hint_new.
javascript messages: all messages used in javascript scenarios. Standard messages of this type are various confirmation messages, for example those used when removing element. Use msg_function1_delete, where function1 is the name of the function provided by this plug-in.

All the message should be presented in UTF-8 encoding. Otherwise the XML-document won't load and VDSmanager won't start.

Example of the vdsmgr_mod_myconf.xml XML-document

<?xml version="1.0" encoding="UTF-8"?> <mgrdata> <handler name="myconf.pl" type="cgi"> <func>myconf</func> <func>myconf.edit</func> <func>myconf.delete</func> </handler> <metadata name="myconf" type="list" key="item"> <toolbar> <toolbtn func="myconf.edit" type="new" img="t-new.gif" name="new"/> <toolbtn func="myconf.edit" type="edit" img="t-edit.gif" name="edit" default="yes"/> <toolbtn func="myconf.delete" type="group" img="t-delete.gif" name="delete"/> </toolbar> <coldata> <col sort="alpha" sorted="yes" name="item" type="data"/> </coldata> </metadata> <metadata name="myconf.edit" type="form"> <form> <field name="item"> <input type="text" name="item"/> </field> </form> </metadata> <mainmenu level="7"> <node name="tool"> <node name="myconf"/> </node> </mainmenu> <lang name="en"> <messages name="desktop"> <msg name="menu_myconf">Test module</msg> </messages> <messages name="myconf"> <msg name="title">Test module</msg> <msg name="item">Item from myconf</msg> <msg name="msg_myconf_delete">Delete item </msg> <msg name="hint_new">New item</msg> <msg name="hint_edit">Edit item</msg> <msg name="hint_delete">Delete item</msg> </messages> <messages name="myconf.edit"> <msg name="title">Edit item</msg> <msg name="title_new">New item</msg> <msg name="item">Item value</msg> <msg name="hint_item">The value of the item from myconf</msg> </messages> </lang> <lang name="ru"> <messages name="desktop"> <msg name="menu_myconf">Test module</msg> </messages> <messages name="myconf"> <msg name="title">Test module</msg> <msg name="item">Element from myconf</msg> <msg name="msg_myconf_delete">Delete element </msg> <msg name="hint_new">New element</msg> <msg name="hint_edit">Edit element</msg> <msg name="hint_delete">Delete element</msg> </messages> <messages name="myconf.edit"> <msg name="title">Edit element</msg> <msg name="title_new">New element</msg> <msg name="item">Value</msg> <msg name="hint_item">Element value from myconf</msg> </messages> </lang> </mgrdata>

Writing a program

Once you have created the XML-document with interface description, you need to write a program or script that will process the data for plug-in. Locate the program in the /usr/local/ispmgr/addon file; it must belong to root and have the access privileges 700. The program name must match the value specified in the name attribute of the XML-document handler node.

The result is supposed to be an XML document represented in the function result output format.

To find out the user who has called the function, you can use the REMOTE_USER environment variable. Make sure that this user has been authorized.

The following is the example of the CGI-program myconf.pl written in Perl:

#!/usr/bin/perl use CGI qw/:standard/; = new CGI; = ->param(func); print "<doc>"; if( eq "myconf" ){ } elsif( eq "myconf.delete" ){ } elsif( eq "myconf.edit" ){ if( ->param( "sok" ) ){ if( ->param( "elid" ) ){ } else{ } print "<ok/>"; } else{ } } print "</doc>"; exit 0; sub List { if( open( IN, "/etc/myconf" ) ){ while( <IN> ){ chomp; print "<elem><item></item></elem>"; } close( IN ); } } sub Get { = ->param( "elid" ); print "<elid></elid><item></item>" if( ); } sub Set { = ->param( "elid" ); = ->param( "item" ); if( open( IN, "/etc/myconf" ) ){ if( open( OUT, ">/etc/myconf.new" ) ){ for( <IN> ){ chomp; if( eq ){ print OUT "\n"; = 1; } else { print OUT "\n"; } } close( OUT ); } close( IN ); } if( ){ rename( "/etc/myconf.new", "/etc/myconf" ); print "<ok/>"; } else { print "<error>Item hasn`t been updated</error>"; } } sub New { = ->param( "elid" ); = ->param( "item" ); if( open( ADD, ">>/etc/myconf" ) ){ print ADD "\n"; close( ADD ); print "<ok/>"; } else { print "<error>Item hasn`t been added</error>"; } } sub Delete { = ->param( "elid" ); if( open( IN, "/etc/myconf" ) ){ if( open( OUT, ">/etc/myconf.new" ) ){ for( <IN> ){ chomp; print OUT "\n" if( ne ); } close( OUT ); } close( IN ); } rename( "/etc/myconf.new", "/etc/myconf" ); print "<ok/>"; }

If you use the program in the xml mode it receives a XML from the standard input that can contain blocks of the interface description for lists and forms that you specified in your XML-document. You can modify this data with your program in order to change the set of list columns, form fields or toolbar icons. Also, your program needs to add the XML-nodes containing data in the function result output format and send it to the standard output.

Was this helpful? Yes | No