# Format des modules app

Dans ce paragraphe nous allons détailler les éléments constitutifs d'un module app et mettre en œuvre ces éléments pour construire un module d'exemple que nous nommerons anakeen-foo.

# Format d'un fichier `app`

Un fichier app de module est une archive TAR compressée par GZIP avec pour extension .app.

L'archive contient les éléments suivants :

content.tar.gz (requis) :

Une archive ( TAR compressé GZIP) contenant les fichiers à déployer dans le contexte.
Les chemins des fichiers contenus dans l'archive doivent être relatifs à la racine du contexte et êtres conformes à l'arborescence attendue sur le serveur.
Cette archive est décompressée dans la racine du contexte sous l'identité de l'utilisateur configuré lors de l'installation de Anakeen Platform.

info.xml (requis) :

Un fichier au format XML conforme au schéma XML https://platform.anakeen.com/4/schemas/app/1.0 décrivant le module et les opérations à exécuter pour son installation, mise-à-jour, etc.

Voir fichierinfo.xml pour la description de ce fichier.

LICENSE (optionnel):

Un fichier contenant le texte de la licence du module au format texte brut (text/plain).

Si ce fichier est présent et que la propriété license du module est valuée dans le fichier fichier info.xml, alors le contenu de ce fichier est présenté à l'utilisateur pour que ce dernier valide la licence du module.

Restrictions sur le nom de l'archive :

Le nom de l'archive ne doit pas contenir les caractères # (dièse), ? (point d'interrogation), % (symbole pourcent).

# Fichier `info.xml`

Le fichier info.xml permet de décrire le module Anakeen Control en fournissant en particulier :

le nom du module,
la version du module,
une description,
une liste de dépendances avec d'autres modules Anakeen Control,
un ensemble d'actions de pre-install, post-install,
un ensemble de paramètres,

# Exemple de fichier de `info.xml`

<?xml version="1.0"?>
<module xmlns="https://platform.anakeen.com/4/schemas/app/1.0" name="anakeen-foo" version="1.2.3"  >
  <description>Anakeen foo</description>

  <requires>
    <module name="module-baz" version="1.0.x"  />
  </requires>

  <parameters>
    <param name="foo_dir" label="Directory of FOO" type="text" default="/var/foo" needed="Y" />
    <param name="foo_color" label="Color of FOO" type="enum" values="red|green|blue" default="green" needed="N" />
  </parameters>

  <pre-install>
    <check type="syscommand" command="zip" />
    <check type="phpfunction" function="pg_connect">
      <help>You might need to install a php-pg package.</help>
    </check>
    <check type="file" file="/var/foo" predicate="is_dir" />
  </pre-install>

  <post-install>
        <process command="./ank.php --script=importConfiguration --file=./vendor/Foo/SmartStructures/Test/test.structure.xml"/>
        <process command="./ank.php --script=importConfiguration --file=./vendor/Foo/SmartStructures/Test/test.security.xml"/>
  </post-install>

  <post-upgrade>
        <process command="./ank.php --script=importConfiguration --file=./vendor/Foo/SmartStructures/Test/test.structure.xml"/>
  </post-upgrade>

  <reconfigure>
    <process command="FOO/reconfigure_foo" />
  </reconfigure>

</module>

# Fichier `build.xml`

Le fichier build.xml est un fichier XML qui contient la description du processus de construction de l'application.

Comme tout document XML, le fichier débute par un prologue :

<?xml version="1.0">

L'élément principal de l'arborescence du document est le module représenté par le tag <module> qui est donc le tag racine du document.

A l'intérieur du module, il faut définir les éléments qui le composent :

source:

Le chemin vers le répertoire source du module.
po-config:

Ce tag permet de décrire l'ensemble des fichiers à partir desquels il faut extraire des PO. Type autorisé : po-struct, po-enum, po-mustache, po-php, po-js, po-vuejs, po-cvdoc et po-workflow. Chaque tag doit avoir un attribut source contenant un glob permettant d'identifier les fichiers. Il est possible d'ajouter l'attribut ignore dans ce cas les fichiers identifiés par le glob sont ignorés. De plus, les tags po-mustache, po-php, po-js, po-vuejs, po-cvdoc, po-workflow peuvent avoir un attribut target permettant de définir dans quel fichier sont mis les PO extraits.
stub-config:

Ce tag permet de décrire l'ensemble des fichiers sources pour la génération des fichiers bouchons. Type autorisé : stub-struct. Chaque tag doit avoir un attribut source contenant un glob permettant d'identifier les fichiers. Il est possible d'ajouter l'attribut ignore dans ce cas les fichiers identifiés par le glob sont ignorés.
check-config:

Ce tag permet de décrire l'ensemble des fichiers sources qui sont validés à la construction du paquet et à la commande check. Chaque tag doit avoir un attribut source contenant un glob permettant d'identifier les fichiers. Il est possible d'ajouter l'attribut ignore dans ce cas les fichiers identifiés par le glob sont ignorés.

# Exemple de fichier `build.xml`

<?xml version="1.0" ?>
<module:config xmlns:module="https://platform.anakeen.com/4/schemas/module/1.0">
    <module:source path="src" />
    <module:po-config>
        <module:po-js source="src/vendor/Anakeen/**/*js" target="ADMIN_TEST"/>
    </module:po-config>
    <module:stub-config>
        <module:stub-struct source="src/vendor/Anakeen/AdminTest/SmartStructures/**/*.xml"/>
    </module:stub-config>
    <module:check-config>
        <module:config-xml source="src/**/*.xml"/>
    </module:check-config>
</module:config>

# Fichier `.anakeen-cli.xml`

Le fichier .anakeen-cli.xml est un fichier XML qui contient la description des informations de déploiement pour la commande anakeen-cli deploy.
Ce fichier est composé des éléments suivants :

config

L'attribut xmlns aura comme valeur l'URL pointant vers le fichier .xsd associé à .anakeen-cli.xml

Le voici : https://platform.anakeen.com/4/schemas/cli/1.0
contextConfig (Configuration du serveur local)
Informations liées au contexte :
- /config/contextConfig/contextUrl : URL du contexte.
- /config/contextConfig/contextUsername : Login du compte administrateur.
- /config/contextConfig/contextPassword : Mot de passe du compte administrateur.
controlConfig (Configuration d'accès à anakeen control)
Informations liées à anakeen-control
- /config/controlConfig/controlUrl : URL de control.
- /config/controlConfig/controlUsername : Login du compte administrateur.
- /config/controlConfig/controlPassword : Mot de passe du compte administrateur.

# Exemple de fichier `anakeen-cli.xml`

<config xmlns="https://platform.anakeen.com/4/schemas/cli/1.0">
    <contextConfig>
        <contextUrl>http://mon-adresse:8080</contextUrl>
        <contextUsername>toto</contextUsername>
        <contextPassword>tata</contextPassword>
    </contextConfig>
    <controlConfig>
        <controlUrl>http://mon-adresse:8080/control/</controlUrl>
        <controlUsername>toto</controlUsername>
        <controlPassword>titi</controlPassword>
    </controlConfig>
</config>

# Description d'un module

La définition d'un module doit être conforme à la description XML https://platform.anakeen.com/4/schemas/app/1.0 .

# Préambule Module

La racine du fichier info.xml est un tag <module> avec les attributs suivants :

name :

Le nom du module. Restrictions sur le nom du module : Le nom du module ne doit pas contenir les caractères : ' (apostrophe)`.
version :

la version du module (sous la forme N.N.N) La comparaison des versions entre deux modules est faite avec semver.
basecomponent (optionnel) :

Y ou N, permet de spécifier si le module est un module de base. Dans ce cas, son installation sera obligatoire. Valeur par défaut : N
license (optionnel) :

license du module : nom/label de la licence du module (ex. http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License).
Si un fichier LICENSE (contenant le texte de la licence au format text/plain) est présent à la racine de l'archive .app, alors une fenêtre est ouverte avec le contenu de ce fichier LICENSE lorsque le module est installé pour la première fois afin que l'utilisateur accepte la licence.
vendor (optionnel) :

fournisseur du module (ex. ACME Corp.).
changelog (optionnel) :

URL d'une page contenant le changelog du module.

Exemple :

<?xml version="1.0"?>
<module
    xmlns="https://platform.anakeen.com/4/schemas/app/1.0"
    name="anakeen-foo"
    version="1.2.3"
    license="GPLV2"
    vendor="ACME Corp."
    changelog="https://modules.example.net/changelog/anakeen-foo/1.2.3"
>

[…]

</module>

# Description

Le module peut fournir une description textuelle pour expliciter le rôle du module.

Exemple :

    <description>This module allows *Anakeen Control* to connect to FOO</description>

# Dépendances

Les dépendances permettent d'exprimer qu'un module requiert d'autres modules Anakeen Control avec éventuellement une contrainte sur leur version, ou une version spécifique de l'installeur.

Les dépendances sont exprimés à l'aide du tag <requires>.

# Dépendances avec des modules

La dépendance avec un module est exprimée avec un élément <module> qui comporte les attributs suivants :

name :

Le nom du module Anakeen Platform requis
version :

La version (semver) attendue pour le module requis

Exemple :

<requires>
  <module name="module-bar" version="2.0.x"  />
  <module name="module-baz" version="1.3.x"  />
</requires>

Dans cet exemple, le module requiert le module module-bar en version >= 2.0 et < 3.0 et le module module-baz en version >=1.3.0 et < 1.4.0.

# Dépendance avec l'installeur

Le module peut aussi exprimer une dépendance sur la version de l'installeur Anakeen Control.

Dans ce cas, le tag <requires> peut contenir un élément <installer> avec les attributs suivants :

version :
La version de l'installeur que requiert le module

Exemple :

<requires>
  <installer version="2.x"  />
  <module name="module-bar" version="2.0.x"  />
  <module name="module-baz" version="1.3.x"  />
</requires>

Dans cet exemple, le module requiert un installer avec une version >= 2.0 et < 3.0

# Paramètres d'installation/upgrade

Un module peut demander lors de son installation (ou upgrade) l'entrée de certains paramètres d'installation ou d'upgrade.

Les paramètres d'installation/upgrade nécessaires au module sont spécifiés avec un élément <parameters> contenant des éléments <param>.

La valeur du paramètre peut ensuite être lue par un programme lancé lors de l'install/upgrade via le mécanisme de process décrit ci-dessous.

Note : ces paramètres de module n'ont pas de lien avec les paramètres applicatif ou de Smart Structure de Anakeen Platform. Par contre, un <process/> spécifique peut être déclaré et utilisé pour enregistrer un paramètre de module comme valeur d'un paramètre applicatif et de Smart Structure en utilisant par exemple le programme program/set_param .

Les éléments <param> ont les attributs suivants :

name :

Le nom du paramètre.
label :

Le label textuel pour présenter le paramètre.
type :

text ou enum, permet de spécifier le type de donné attendu.
default (optionnel) :

La valeur par défaut présentée à l'utilisateur lors de la saisie des paramètres.
Valeur par défaut : "" (chaîne vide).
needed (optionnel) :

Y (pour yes) ou N (pour no), permet de spécifier si la saisie du paramètre est obligatoire ou optionnelle.
Valeur par défaut : N.
values :

Lorsque type=“enum”, l'attribut values permet de spécifier une liste de choix finis, séparés par le caractère | (pipe), à partir de laquelle l'utilisateur sélectionnera une valeur (e.g. X|FOO|BAR).
volatile (optionnel) :

Y (pour yes) ou N (pour no), permet de spécifier si la valeur entrée doit être supprimée après l'installation ou upgrade.
Cela permet d'indiquer que la valeur n'est pas mémorisée, et donc qu'elle sera demandée avec sa valeur par défaut à chaque upgrade du module par exemple.
Valeur par défaut : N.
oninstall (optionnel) :

Permet de spécifier la visibilité du paramètre lors d'une installation du module (R pour lecture seule, W pour lecture/écriture, H pour caché).
Valeur par défaut : W.
onedit (optionnel) :

Permet de spécifier la visibilité du paramètre lors de l'édition des paramètres depuis la liste des modules installés.
Valeur par défaut : R.
onupgrade (optionnel) :

Permet de spécifier si le paramètre est redemandé lors des upgrades du module.
Valeur par défaut : H.

Exemple :

<parameters>
  <param name="foo_dir" label="Directory of FOO" type="text" default="/var/foo" needed="Y" />
  <param name="foo_color" label="Color of FOO" type="enum" values="red|green|blue" default="green" needed="N" />
</parameters>

# Opération d'install/upgrade/archive/restore/delete et phases

Lors de l'opération d'installation ou d'upgrade d'un module, ou d'archivage/restauration/suppression d'un contexte, un ensemble de phases contenant des process sont déroulés.

Les phases sur lesquelles vous pouvez spécifier vos process sont identifiées en couleur dans le diagramme ci-dessous.

Workflow install/upgrade d'un module

Chaque opération (install, upgrade, etc.) comporte des phases qui sont exécutés à un moment du traitement du module

L'opération d'installation comporte ainsi deux phases sur lesquelles vous pouvez spécifier vos process : une phase avant l'installation des fichiers du module (phase pre-install), et une phase après l'installation des fichiers du module (phase post-install).

De la même manière, lors de l'upgrade : une phase avant la suppression des anciens fichiers du module et l'installation des nouveaux fichiers du module (phase pre-upgrade), et une phase après l'installation des nouveaux fichiers du module (phase post-upgrade).

Chaque phase (pre-install, post-install], etc.) spécifie un ensemble de process (éléments <check>, <process> ou <download>) qui sont exécutés et qui retournent un status d'échec ou de réussite.

Une phase est validée lorsque tous ses sous-éléments process ont retourné un statut de réussite.

Si une phase n'est pas validée, alors les messages d'erreurs rencontrés sont présentés à l'utilisateur , et celui-ci peut rejouer le process après avoir éventuellement corrigé le problème, ou bien il peut choisir d'ignorer les messages d'erreurs et poursuivre le déroulé de la phase.

Les process possibles dans les phases sont des éléments :

<check>
<process>
<download>

Chaque proccess peut fournir un élément <label> présenté comme titre dans la liste des process de la phase, et un <help> qui sera présenté à l'utilisateur lorsque l'action échoue.

En l'absence de <label> et de <help> un message générique est composé pour identifier le process.

# Phase `pre-install`

Les process de <pre-install> s'exécutent avant l'installation des fichiers du module sur le système de fichier.

Exemple :

<pre-install>
  <check type="phpfunction" function="pspell_new">
    <label>Vérification du support de pspell par PHP.</label>
    <help>Il faut peut-être installer php5-pspell avec aspell et aspell-fr</help>
  </check>
  <check type="syscommand" command="convert" />
</pre-install>

Les process de <pre-install> serviront généralement à vérifier la présence de certains éléments et à bloquer l'installation si ces éléments ne sont pas présents/corrects.

# Phase `post-install`

Les process de <post-install> s'exécutent après l'installation des fichiers du module sur le système de fichier.

Exemple :

<post-install>
  <process command="programs/record_application FOO">
    <label lang="en">Record FOO application in database</label>
  </process>
  <process command="programs/update_catalog">
    <label lang="en">Generate localization catalog</label>
  </process>
</post-install>

Les process de <post-install> serviront généralement à configurer le module qui vient d'être installé. Une erreur dans la phase de post-install laissera les fichiers installés en place, mais le paquet sera marqué en erreur de post-install dans l'interface.

# Phase `pre-upgrade`

Les process de <pre-upgrade> s'exécutent avant l'installation des nouveaux fichiers du module sur le système de fichiers.

Exemple :

<pre-upgrade>
  <check type="phpfunction" function="pspell_new">
    <help>Il faut peut-être installer php5-pspell avec apspell et aspell-fr</help>
  </check>
  <check type="syscommand" command="convert" />
</pre-upgrade>

Les process de <pre-upgrade> serviront généralement à vérifier la présence de certains éléments et bloquer l'upgrade si ces éléments ne sont pas présents/corrects.

# Phase `post-upgrade`

Les process de <post-upgrade> s'exécutent après l'installation des nouveaux fichiers du module sur le système de fichier.

Exemple :

<post-upgrade>
  <process command="programs/pre_migration FOO">
    <label>Pre-migration scripts</label>
  </process>
  <process command="programs/record_application FOO">
    <label>Update application record in database</label>
  </process>
  <process command="programs/post_migration FOO">
    <label>Post-migration scripts</label>
  </process>
  <process command="programs/update_catalog">
    <label>Re-generate localization catalog</label>
  </process>
</post-upgrade>

Les process de <post-upgrade> serviront généralement à configurer le module qui vient d'être installé, lancer les scripts de migration, etc. Une erreur dans la phase de post-upgrade laissera les fichiers installés en place, mais le paquet sera marqué en erreur de post-upgrade dans l'interface.