Présentation
Le fichier module.xml contient les informations principales de votre module, comme ses paramètres, ses dépendances, son nom, sa version, les événements auxquels il répond, ...
Ce fichier est nécessaire si vous voulez que Copix considère votre module (sans ce fichier, votre module n'apparaitra par exemple pas dans la liste des modules installables).
Exemples
Minimaliste
<?xml version="1.0"?>
<moduledefinition>
<general>
<default name="nom_repertoire" description="Description du module" />
</general>
</moduledefinition>
Section general
La section générale (general) contient un seul attribut obligatoire qui est l'attribut nommé "default".
Cette section accepte ces attributs
- name qui est le nom du module, il doit reprendre la nom du répertoire dans lequel module.xml se trouve.
- description qui est le nom du module "en clair", compréhensible par l'utilisateur.
- descriptioni18n qui est le nom du module "en clair", compréhensible par l'utilisateur, sous la forme d'une clef i18n (voir CopixI18N).
- longdescription qui est la description longue du module, généralement on explique ici ce que le module fait, en quelques lignes
- longdescriptioni18n qui est l'équivalent en clef i18n de longdescription
- icon icone du module, dans /www/themes/monTheme/img/icons/ (version 3.0.1)
Exemple sans utiliser I18N
<general>
<default name="nom_repertoire" description="Description du module" longdescription="Ce module permet de faire tout un tas de chose plutot pratique, c'est pour ça qu'on l'a fait." />
</general>
Exemple Avec I18N
<general>
<default name="nom" descriptioni18n="nom.clefDescription" longdescriptioni18n="nom.clefLongDescription" />
</general>
Section paramètres
La section parameters vous permet de déclarer des paramètres qui seront administrables via l'écran d'administration et manipulables via CopixConfig.
<parameters>
<parameter name="nom_parametre" caption="Un paramètre" default="1" />
<parameter name="param_text" caption="Texte" type="text" default="Mon texte" maxLength="255" />
<parameter name="param_int" caption="Entier" type="int" default="1" minValue="0" maxValue="100" />
<parameter name="param_bool" caption="Oui / Non" type="bool" default="1" />
<parameter name="param_email" caption="E-mail" type="email" default="monmail@mailer.ext" maxLength="255" />
<parameter name="param_select" caption="Liste déroulante" type="select" default="1" listValues="0=>Ma valeur 0;1=>Ma valeur 1" />
<parameter name="param_multiSelect" caption="Liste déroulante à choix multiple" type="multiSelect" default="1" listValues="0=>Ma valeur 0;1=>Ma valeur 1" />
</parameters>
La déclaration d'un paramètre accepte plusieurs attributs :
- name le nom du paramètre
- caption le libellé du paramètre (obligatoire)
- captioni18n la clef i18n pour le libellé du paramètre (obligatoire si caption n'est pas donné)
- default la valeur par défaut du paramètre à l'initialisation du module.
- type le type du paramètre (text, int, bool, email, select, multiSelect)
- minValue borne minimum de saisie pour le type int
- maxValue borne maximum de saisie pour le type int
- maxLength nombre de caractères maximum pour les types text et email
- listValues liste des valeurs pour les types select et multiSelect (syntaxe : 0=>Texte;1=>Texte)
En savoir plus sur les paramètres.
ATTENTION default correspond à la valeur par défaut qu'aura le paramètre lors de l'installation du module. Une fois le module installé, modifier la valeur de "default" dans le fichier n'aura aucun impact sur l'application. Pour modifier la valeur d'un paramètre, vous devez utiliser le module d'administration, section paramètres.
Groupes de paramètres (Copix 3.0.2 minimum)
Vous pouvez afficher les paramètres sous forme de groupes, pour séparer plusieurs types de paramètres. Les groupes ne servent que lors de l'affichage.
<parameters>
<group captioni18n="auth.group.createUser">
<parameter name="createUser" captioni18n="auth.createUser" default="0" type="bool" />
</group>
<group captioni18n="auth.group.others">
<parameter name="timetolive" captioni18n="auth.remember_time" default="2678400" type="int" />
<parameter name="cryptPassword" captioni18n="auth.cryptPassword" type="select" default="md5" listValues="md5=>MD5;sha1=>SHA1;SHA256=>SHA256" />
</group>
</parameters>
La déclaration d'une node group doit avoir un attribut caption ou captioni18n.
Section dependencies
Cette section vous permet d'indiquer de quels modules dépend votre module courant.
Ceci permet à Copix de vérifier lors de l'installation de votre module que toutes les dépendances sont satisfaites. Si ce n'est pas le cas, Copix tentera d'installer les dépendances avant votre module.
<dependencies>
<dependency name="copixheadings" kind="module"/>
<dependency name="parameters" kind="module"/>
<dependency name="profile" kind="module"/>
<dependency name="gd" kind="extension"/>
<dependency name="mysql_connect" kind="function"/>
<dependency name="PHPUnitClass" kind="class"/>
</dependencies>
- le kind module teste l'existence d'un module et l'install si il n'est pas installé
- le kind extension teste l'installation d'une extension PHP, si elle n'est pas installé le module ne pourra pas etre installé
- le kind function teste l'existence d'une fonction, si elle n'est pas installé le module ne pourra pas etre installé
- le kind class teste l'existence d'une class, si elle n'est pas installé le module ne pourra pas etre installé
Section admin
Cette section vous permet de demander à Copix d'ajouter des liens pour votre module dans la page d'administration (module admin).
Exemple de fichier
<admin>
<link url="admin|install|manageModules" captioni18n="install.button.manageModules" credentials="basic:admin" />
<link url="admin|session|" captioni18n="session.admin" credentials="basic:admin" />
</admin>
Chaque élément link accepte 4 paramètres
- url une url au format Copix (CopixURL)
- captioni18n une clef i18n pour le libellé du lien
- caption le libellé du lien si captioni18n n'est pas fourni
- credentials la chaîne de droit nécessaire pour pouvoir afficher le lien.
(A partir de copix 3.0.1) Si vous avez plusieurs modules qui ont un thème commun (Outils de développement, Outils divers, Administration, etc), vous pouvez créer un "groupe". Tous les modules qui ont le même attribut "groupid" auront leurs liens dans la partie admin dans une section portant le nom de l'attribut "groupcaption" ou "groupcaptioni18n", et non pas dans une section portant le nom du module.
<admin groupid="myGroup" groupcaptioni18n="myGroup.groupName" groupicon="tools.gif">
Attributs possibles pour admin
- groupid identifiant du groupe, qui doit être commun entre les modules d'un même groupe
- groupcaption caption du groupe (doit être présent dans au moins un des modules du groupe)
- groupcaptioni18n caption i18n du groupe (doit être présent dans au moins un des modules du groupe)
- groupicon icon du groupe, retour d'un _resource ('img/icons/' . $groupicon) (doit être présent dans au moins un des modules du groupe)
Section events
La section events permet de déclarer l'ensemble des listeners que votre module déclare ainsi que les évènements auxquels ils réagissent.
<events>
<listeners>
<listener name="NomListener">
<event name="NomEvenement" />
<event name="AutreEvenement" />
</listener>
</listeners>
</events>
En savoir plus sur les évènements.
Section credentials
La section credentials permet de déclarer des droits disponible pour notre module
<credentials>
<credential name="commentaires">
<value name="lecture" level="1">
<value name="ecriture" level="2">
<value name="moderation" level="3">
</credential>
<credential name="connexion" />
</credentials>
Nous déclarons ici plusieurs droits, tout d'abord
- le droit commentaires qui possède 3 valeurs différentes :
- lecture ayant un level de 1
- ecriture ayant un level de 2
- moderation ayant un level de 3
- le droit connexion qui ne possède pas de sous-valeur
Pour plus d'infos sur la gestion des droits par module