Extensions (VDSmanager)

De ISPWiki.

Le mécanisme d'extensions (plugins) permet de créer ses propres modules dans le panneau de configuration. Ce document décrit l'exemple de la création d'un module qui traitera la liste des lignes dans le fichier /etc/myconfig. Vous pourrez créer vous-même vos propres extensions du panneau de configuration en suivant cet exemple.

La création d'une extension comprend deux étapes. La première étape est la création d'un document XML qui décrira toutes les fonctions traitées par cette extension et tous les éléments nécessaires de l'interface pour que votre module soit accessible dans le panneau de configuration. La deuxième étape est le développement d'un programme ou d'un script qui traitera les données au cours de fonctionnement d'une extension, c'est à dire réaliser des fonctions.

Sommaire

Création d'un document XML

Le document XML qui décrit l'interface de votre extension du panneau de configuration doit être situé dans le répertoire /usr/local/ispmgr/etc et être nommé vdsmgr_mod_xxx.xml, au lieu de xxx vous pouvez spécifier n'importe quel nom, par exemple, myconfig (vdsmgr_mod_myconfig.xml). Le document doit être obligatoirement codé en UTF-8 et présenté de la façon suivante:

<?xml version="1.0" encoding="UTF-8"?> <mgrdata> description des fonctions de cette extension description des éléments du menu description des tableaux et des formulaires description des messages </mgrdata>

Description des fonctions de cette extension

Ce paragraphe du document XML décrit le nom d'un programme ou d'un script qui réalisera les fonctions, la mode d'interaction du programme avec le panneau de configuration et l'ensemble de fonctions fournies par cette extension. Ce paragraphe doit être présenté de la façon suivante:

<handler name="programme" type="type"> <func>fonction1</func> <func>fonction2</func> ... </handler>

Dans l'attributname veuillez spécifier le nom de programme qui réalise des fonctions, par exemple myconfig.pl. Dans l'attribut type veuillez spécifier la mode d'interaction du panneau de configuration avec votre programme. Deux modes sont possibles actuellement:

  • cgi - le programme a l'interface CGI, c'est à dire le programme reçoit des données à partir des variables d'environnement et/ou de l'entrée standard (POST).
  • xml - le programme reçoit un document XML à partir de l'entrée standard, ce document décrit les données transmises par le panneau de configuration.

Puis vous devez spécifier quelles fonctions seront fournies par votre extension. Il existe trois types de fonctions:

  • Liste des éléments - un tableau comportant la barre d'outils.
  • Propriétés d'un élément - un formulaire pour la création d'un nouvel élément ou pour la modification d'un élément existant. Vous pouvez également vous servir de ce formulaire si votre module n'est pas destiné à traiter plusieurs éléments mais permet de configurer un ensemble de propriétés.
  • Manipulation - ce type de fonctions ne prévoit pas ses propres éléments de l'interface, mais représente une manipulation avec un ou plusieurs éléments de la liste.

Les noms de fonctions peuvent être composés de lettres latines, de chiffres et de points, ils doivent être uniques. La liste des fonctions existantes est disponible dans le fichier /usr/local/ispmgr/etc/vdsmgr.xml.

Description des éléments du menu

Pour accéder à votre extension, vous devez créer des éléments correspondants du menu du panneau de configuration: vous devez ajouter ce bloc dans votre document XML:

<mainmenu level="niveau d'accès"> <node name="nom de catégorie"> <node name="fonction1"/> <node name="fonction2"/> </node> </mainmenu>

Premièrement vous devez décider sur quel niveau d'accès vous souhaitez avoir votre extension. Actuellement, il existe les niveaux d'accès suivants:

  • 7 - administrateur de VDSmanager.
  • 6 - revendeur des serveurs dédiés virtuels.
  • 5 - propriétaire du serveur dédié virtuel .

Veuillez spécifier le chiffre qui correspond au niveau d'accès dans l'attribut level. Si vous désirez que le module soit accessible sur plusieurs niveaux, veuillez ajouter le bloc mainmenu pour chacun d'eux.

A la place de nom de catégorié spécifiez le nom qui est indiqué dans l'attribut name du noeud node pour la catégorie correspondante du menu de navigation décrit dans le fichier /usr/local/ispmgr/etc/vdsmgr_menu.xml. Si vous souhaitez autoriser accès à votre extension à tous les propriétaires des serveurs dédiés virtuels et ajouter l'item correspondant dans la rubrique "Outils" du menu de navigation, vous devez trouver la rubrique <mainmenu level="5"> et la rubrique <node name="tool">. A la place de nom de catégorie il faut spécifier la valeur tool.

Ensuite il est nécessaire d'ajouter un ou plusieurs éléments de menu dans la rubrique correspondante du menu de navigation: vous devez ajouter les noeuds node et spécifier dans l'attribut name le nom d'une fonction qui sera appelée par le clic sur l'item correspondant du menu.

Description des tableaux et des formulaires

Vous devez décrire l'interface pour les fonctions fournies par votre extension. Notre module test permet de visualiser des enregistrements existants dans le fichier /etc/myconfig, et de créer des nouveaux enregistrements ou modifier ceux existants. La possibilité de suppression doit aussi être prévue mais cette fonction est associée à "manipulation" et n'a pas besoin d'une interface.

Alors, pour réaliser la liste des enregistrements, il est nécessaire d'ajouter ce bloc dans le document XML:

<metadata name="fonction1" type="list" key="nom_de_champ"> <toolbar> <toolbtn func="fonction2" type="new" img="t-new.gif" name="new"/> <toolbtn func="fonction2" type="edit" img="t-edit.gif" name="edit" default="yes"/> <toolbtn func="fonction3" type="group" img="t-delete.gif" name="delete"/> </toolbar> <coldata> <col sort="alpha" sorted="yes" name="nom_de_champ" type="data"/> </coldata> </metadata>

Cela signifie que nous souhaitons ajouter l'interface à notre fonction "fonction1" de type liste (type="list"), où l'élément-clé est "nom_ de_champ". L'élément-clé unique est nécessaire pour identifier un enregistrement dans la liste. C'est cette valeur qui sera transmise aux fonctions traitant les éléments de la liste tels que l'affichage des propriétés d'un élément, la suppression etc.

Puis nous avons la description du panneau de configuration qui comprend trois boutons: créer (name="new"), éditer (name="edit") et supprimer (name="delete") un élément. Vous pouvez spécifier une manipulation qui s'effectuera (lorsque vous double cliquerez sur l'enregistrement) par l'ajout de l'attribut default="yes" dans le noeud qui décrit cet élément du panneau de configuration. Dans notre cas la fonction de modification d'un enregistrement sera appelée par double clic. Le même nom de fonction est spécifié dans l'attribut func dans deux premiers boutons. Cela provient de ce qu'une seule fonction réalisera la création, l'affichage et la modification des enregistrements. Le type de fonction est déterminé par l'attribut type:

  • new - la création d'un nouvel élément.
  • edit - la modification d'un élément existant.
  • group - la manipulation avec le groupe d'éléments.
  • editlist - la liste emboîtée associée à un des éléments de la liste courante.
  • list - la liste emboîtée qui n'est associée à aucun élément de la liste courante.

Puis vous devez spécifier le bloc coldata, dans lequel il faut ajouter le nombre nécessaire de noeuds col, l'un pour chaque colonne du tableau. Dans notre cas le tableau est composé d'une seule colonne qui affichera le champ "nom_de_champ", que la fonction de création de la liste retournera pour chaque élément. Vous devez spécifier le type d'enregistrements dans la colonne. Il existe trois types actuellement:

  • data - cette colonne affichera les données sur chaque élément qui ont été transmises dans le champ avec le nom spécifié dans l'attribut name (dans notre cas c'est "nom_de_champ").
  • msg - ce type peut être utile si vous avez un ensemble fini de valeurs retournées dans le champ avec le nom qui est spécifié dans l'attribut name, par exemple le statut d'enregistrement (activé, désactivé, etc) et si vous souhaitez que ces valeurs soient affichées différement, selon les langues du panneau de configuration. Dans ce cas les valeurs retournées dans ce champ doivent être composées de lettres latines, de chiffres, de points et de caractères "_".
  • indicator - cette colonne affichera les indicateurs de consommation de telle ou telle ressource, par exemple d'espace disque ou de trafic. Dans ce cas vous devez ajouter le noeud XML avec le nom de cette colonne de la liste pour chaque élément pour lequel vous désirez afficher un indicateur, et ajouter dans ce noeud deux attributs: used="chiffre" et limit="chiffre".

Si vous désirez trier les données dans une colonne vous devez ajouter l'attribut sort,dans lequel il faut spécifier l'une des valeurs suivantes qui dépend du type de données dans cette colonne:

  • alpha - des lignes de lettres latines et de chiffres.
  • digit - des chiffres.
  • indicator - des indicateurs (par exemple espace disque, trafic, etc).
  • ip - des adresses IP.
  • prop - un ensemble des propriétés (par exemple, activé/désactivé).

Si vous désirez que les enregistrements du tableau se trient automatiquement par une des colonnes lors de la connexion au module, vous devez ajouter l'attribut sorted="yes"

Si vous voulez que les statistiques basées sur les données enregistrées dans les colonnes soient affichées, vous devez ajouter l'attribut stat="yes".

Puis vous devez ajouter la description de l'interface pour le formulaire de création et de modification d'un enregistrement, en ajoutant ce bloc dans le document XML:

<metadata name="fonction2" type="form"> <form> <field name="сообщение"> <input type="text" name="nom_de_champ"/> </field> </form> </metadata>

Cela signifie que nous souhaitons ajouter un formulaire (type="form") pour appeler la fonction "fonction2". Pour chaque élément de gestion vous devez ajouter un bloc field, composé d'un titre du champ et d'un élément de gestion proprement dit. Le titre pour ce champ est spécifié à l'aide de l'attribut name="сообщение". De plus il est nécessaire d'ajouter un noeud correspondant dans le bloc de messages pour cette fonction. Les règles de création des messages seront présentées plus tard. Puis vous devez ajouter un élément de gestion:

  • input - le champ de saisie. Il existe quelques types de champs de saisie qui sont spécifiés dans l'attribut type:
    • text - un champ de saisie à une ligne.
    • password - un champ destiné à saisir un mot de passe, qui affiche des astérisques lors de la saisie des caractères.
    • checkbox - une case à cocher.
  • textarea - un champ de saisie à plusieurs lignes.
  • select - une liste déroulante.

A l'aide de l'attribut name il faut spécifier le nom de propriété d'une fonction qui est associé à cet élément de gestion. Si vous désirez spécifier certaine valeur par défaut pour un élément de gestion, vous pouvez utiliser l'attribut value="valeur_par_défaut".

Il existe aussi des attributs supplémentaires pour les champs field'. Si vous désirez que le champ soit caché par défaut et gérer sa visibilité à l'aide de javascript, vous devez ajouter l'attribut hidden="yes". Si votre élément de gestion est '

, t si ce champ de texte est destiné à saisir plusieurs valeurs, vous pouvez ajouter l'attribut zoom="5". Près de ce champ de texte vous aurez un bouton qui permet d'agrandir le champ texte selon le nombre de lignes spécifiées dans l'attribut donné ce qui permet à son tour d'entrer les données à la ligne.

Description des messages

Les messages de VDSmanager sont tous les textes que vous voyez dans la panneau de configuration et qui ne sont pas associés aux données reçues grâce à l'execution des fonctions. Les messages se distinguent par les langues de l'interface. Vous devez insérer ce bloc pour chaque langue:

<lang name="langue"> messages du menu de navigation messages du menu de navigation </lang>

Vous devez spécifier l'une des valeurs suivantes:

  • de - allemand
  • en - anglais
  • es - espagnol
  • fr - français
  • ru - russe

La langue principale de l'interface est l'anglais. Si vous avez choisi une autre langue et le message dont vous avez besoin n'est pas trouvé, vous aurez le message analogue en anglais.

Ensuite il est nécessaire d'ajouter dans ce bloc les messages pour tous les items du menu que vous avez créé dans la [#menu description des éléments du menu]. Vous devez ajouter le bloc de ce type:

<messages name="desktop"> <msg name="menu_fonction1">message1</msg> <msg name="menu_fonction2">message2</msg> </messages>

C'est à dire pour chaque item du menu comme il faut ajouter un message du type message1. Au lieu de message1 spécifiez le texte de l'item du menu codé en UTF-8.

Tous les autres messages se distinguent par les fonctions, donc pour chaque fonction fournie par votre extension d'ISPmanager il faut ajouter le bloc de ce type dans le document XML:

<messages name="fonction1"> <msg name="nom_de_message">message</msg> ... </messages>

Il existe des types standards de messages pour les modules d'ISPmanager (ces noms doivent être spécifiés au lieu de nom_de_message):

  • title - un titre d'un module (d'une liste ou d'un formulaire).
  • title_new - un titre du formulaire de création d'un nouvel élément.
  • hint_default - un descriptif d'un module

Tous les autres messages se divisent en types suivants:

  • titres des colonnes de la liste -à la place du nom de message vous devez spécifier les valeurs qui sont spécifiées à leur tour dans l'attribut name du noeud col.
  • valeurs pour colonnes de type msg - à la place du nom de message vous devez spécifier une valeur qui peut être transmise dans une propriété correspondante de l'élément retourné par la fonction. Si les valeurs sont nombreuses, vous devez créer un message à part pour chacune d'elles.
  • titres des champs de formulaire - à la place du nom de message il faut spécifier les valeurs qui sont spécifiées à leur tour dans l'attribut name du noeud field.
  • valeurs pour éléments de gestion de type select - à la place du nom de message vous devez spécifier une valeur qui peut être transmise dans cette liste. Si la valeur correspondante n'est pas trouvée, la valeur retournée par la fonction sera affichée elle-même. Si les valeurs peuvent être nombreuses, il convient de créer un message à part pour chacune d'elles.
  • descriptifs des champs de formulaire - à la place de nom de message vous devez spécifier les valeurs qui sont spésifiées à leur tour dans l'attribut name du noeud field avec le préfixe hint_, par exemple, hint_username.
  • descriptifs des boutons du panneau de configuration - à la place de nom de message vous devez spécifier les valeurs qui sont spécifiées à leur tour dans l'attribut name du noeud toolbtn avec le préfixe hint_, par exemple, hint_new.
  • messages javascript - ce sont tous les messages utilisés en javascript. Des messages javascript standards sont, par exemple, les messages de confirmation de la suppression d'un élément. Dans ce cas à la place de nom de message vous devez spécifier msg_функция1_delete, où à la place de "fonction1" il faut spécifier le nom de fonction de l'extension.

Il est important de souligner encore une fois que tous les messages doivent être codés en UTF-8. Sinon le document XML ne pourra pas être chargé et VDSmanager ne se lancera pas.

Voici l'exemple du document XML vdsmgr_mod_myconf.xml

<?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"> Module test</msg> </messages> <messages name="myconf"> <msg name="title"> Module test </msg> <msg name="item"> Elément de myconf</msg> <msg name="msg_myconf_delete">Supprimer élément </msg> <msg name="hint_new"> Nouvel élement </msg> <msg name="hint_edit"> Modifier élément </msg> <msg name="hint_delete"> Supprimer élément </msg> </messages> <messages name="myconf.edit"> <msg name="title"> Modifier élément </msg> <msg name="title_new"> Nouvel élément </msg> <msg name="item"> Valeur </msg> <msg name="hint_item"> Valeur élément de myconf</msg> </messages> </lang> </mgrdata>

Développement d'un programme

Après la préparation du document XML qui décrit l'interface de l'extension, il est nécessaire d'écrire un programme ou un script qui traitera les données pour l'extension. Ce programme doit être situé dans le répertoire /usr/local/ispmgr/addon, appartenir à l'utilisateur root et contenir des droits d'accès 700. Le nom de programme doit correspondre à la valeur spécifiée dans l'attribut name du noeud handler du document XML.

Le résultat du fonctionnement du programme sera présenté par le document XML au [api#output format de sortie des résultats de l'exécution des fonctions].

Pour connaître le nom de l'utilisateur qui a appelé une fonction d'ISPmanager, lançant l'exécution de votre programme, vous pouvez utiliser la variable d'environnement REMOTE_USER. Avec cela vous pouvez être sûr que cet utilisateur est autorisé.

Voici l'exemple du programme CGI myconf.pl, écrit en 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/>"; }

Si vous utilisez le programme en mode xml, il reçoit des données XML à partir de l'entrée standard, ces données peuvent contenir les blocs de description de l'interface pour la création des listes et des formulaires que vous avez décrit dans votre document XML. Vous pouvez corriger les données à l'aide de ce programme dans le but de modifier l'ensemble de colonnes de la liste, les champs des formulaires ou les boutons dans la barre d'outils. Votre programme doit aussi ajouter les noeuds XML nécessaires avec les données au [api#output format de sortie des résultats de l'exécution des fonctions ] dans ce document et le retourner sur la sortie standard.

Cet article vous a-t-il été utile? Oui | Non
Affichages
Outils personnels