Modules Plug-in : utilisation, cration...

<span lang="fr">
ITEM: Qu'est-ce qu'un module plug-in ?

Les modules plug-in sont des bouts de code qui vous permettent de modifier le
comportement d'album. Ils peuvent tre aussi simples que la faon de crer des
lgendes EXIF ou quelque chose d'aussi compliqu que crer un album partir
d'une base de donnes d'images plutt que d'utiliser une hirarchie dans un
systme de fichiers.


ITEM: Installation d'un module plug-in et son support

Il y a un certain nombre de modules plug-in disponibles avec l'installation
standard d'album. Si vous souhaitez mettre  jour album avec les modules
plug-in d'une prcdente version d'album qui ne dispose pas de modules plug-in
(pr v3.10), vous aurez besoin de faire une fois :

<code>% album -configure</code>

Vous n'aurez pas besoin de refaire cette commande lors des futures mises 
jour d'album.

Cette commande installera les modules plug-in actuels dans un des rpertoires
par dfaut des modules plug-in. album cherchera les modules plug-in dans un
certain nombre d'endroits. Ceux par dfaut sont :
<tt>
  /etc/album/plugins/
  /usr/share/album/plugins/
  $HOME/.album/plugins/
</tt>
En ralit, ces rpertoires 'plug-in' sont ceux trouvs dans les endroits
spcifis par l'option '--data_path' dont les noms par dfaut sont :
<tt>
  /etc/album/
  /usr/share/album/
  $HOME/.album/
</tt>
Vous pouvez spcifier un nouveau rpertoire avec l'option '--data_path' et
ajouter un rpertoire 'plugins'  ce niveau ou utiliser l'option
'--plugin_path'.

Les modules plug-in se terminent en gnral par l'extension ".alp" mais vous
n'avez pas besoin de spcifier cette extension lorsque vous les utilisez. Par
exemple, si vous avez un module install ici :

<tt>/etc/album/plugins/utils/mv.alp</tt>

alors vous l'appellerez ainsi :  <tt>utils/mv</tt>


ITEM: Chargement / dchargement des modules plug-in

Pour lister tous les modules plug-in actuellement installs, taper :

<code>% album -list_plugins</code>

Pour montrer des informations relatives  des modules spcifiques (en
utilisant 'utils/mv' comme exemple) :

<code>% album -plugin_info utils/mv</code>

Les modules plug-in seront sauvs dans le fichier de configuration pour un
album donn ainsi vous n'avez pas besoin de les respcifier  chaque fois, 
l'exclusion des modules plug-in qui s'excutent une seule fois comme par
exemple 'utils/mv' ('mv' = 'move' : correspond  un dplacement de fichiers
donc ne peut tre excute qu'une seule fois pour un jeu de fichiers donn).

Vous pouvez utiliser les options -no_plugin et -clear_plugin pour dsactiver
les modules plug-in qui ont t sauvs dans le fichier de configuration de
l'album courant. De la mme faon que <a href="Section_3.html#Options">les
options standard d'album</a>, -no_plugin dsactivera un module plug-in
spcifique alors que -clear_plugin dsactivera l'ensemble des modules
plug-in. Toutes les options attaches  ces modules seront galement
effaces.


ITEM: Options des modules plug-in

Quelques modules plug-in acceptent des options en ligne de commande. Pour
visualiser comment les utiliser, taper :

<code>% album -plugin_usage utils/mv</code>

Cependant, quand vous spcifiez une option pour un module plug-in, vous devez
indiquer  album  quel module plug-in l'option correspond. A la place de la
syntaxe utilise pour les options standards d'album :

<code>% album -une_option</code>

vous devez prfixer l'option avec le nom du module plug-in suivi de
deux-points :

<code>% album -un_plugin:une_option</code>

Par exemple, vous pouvez spcifier le nom de l'index cr par le module
plug-in 'utils/capindex'.

<code>% album -plugin utils/capindex  -utils/capindex:index blah.html</code>

C'est peu pratique. Vous pouvez raccourcir le nom du module plug-in tant qu'il
ne rentre pas en conflit avec un autre module plug-in dj charg et ayant le
mme nom :

<code>% album -plugin utils/capindex  -capindex:index blah.html</code>

Evidemment, les autres types d'options (chanes de caractres, nombres et
tableaux) sont accepts et utilisent la mme convention. Ces options sont
sauvegardes dans le fichier de configuration de l'album de la mme faon que
les options standard.

Avertissement : comme mentionn, une fois que nous utilisons un module plug-in
sur un album, il est sauvegard dans le fichier de configuration. Si vous
voulez ajouter d'autres options  un album dj configur pour utiliser un
module plug-in, vous devez soit mentionner le module plug-in ou soit utiliser
le nom complet du module quand vous spcifiez les options (autrement, album ne
saura pas  qui appartient l'option raccourcie).

Par exemple, considrons un module plug-in imaginaire :

<code>% album -plugin un/exemple/vignetteGen Photos/Espagne</code>

Aprs a, supposons que nous voulons utiliser la variable boolenne "rapide" du
module vignetteGen.
Ceci <b>ne</b> fonctionnera <b>pas</b> :

<code>% album -vignetteGen:rapide Photos/Espagne</code>

Mais l'une de ces solutions fonctionnera :

<code>% album -plugin un/exemple/vignetteGen -vignetteGen:rapide blah.html Photos/Espagne</code>
<code>% album -un/exemple/vignetteGen:rapide Photos/Espagne</code>


ITEM: Ecrire des modules plug-in

Les modules plug-in sont de petits modules crits en perl qui s'appellent via
des fonctions particulires ('hooks') du code d'album.

Il y a de telles fonctions pour la plupart des fonctionnalits d'album et le
code du module plug-in peut souvent soit remplacer soit complter le code
d'album. Davantage de ces fonctions pourraient tre rajoutes dans les futures
versions d'album si besoin.

Vous pouvez afficher la liste de toutes ces fonctions autorises par album :

<code>% album -list_hooks</code>

Et vous pouvez obtenir des informations spcifiques pour chacune de ces
fonctions :

<code>% album -hook_info &lt;hook_name&gt;</code>

Nous pouvons utiliser album pour gnrer  notre place un cadre pour nos
modules plug-in :

<code>% album -create_plugin</code>

Pour effectuer cette tche, vous avez besoin de comprendre les fonctions
'hooks' dans album et les options d'album.

Nous pouvons aussi crire un module plug-in  la main. Pour cela, utiliser comme
base de travail un module plug-in dj crit facilite le travail.

Dans notre module plug-in, nous enregistrons notre fonction 'hook' en appelant
la fonction album::hook(). Pour appeler des fonctions dans le code d'album,
nous utilisons l'espace de nommage <code>album</code>.
Par exemple, pour enregistrer le code pour la fonction 'hook'
<code>clean_name</code>, notre module plug-in appelle :

<code>album::hook($opt,'clean_name',\&my_clean);</code>

Ainsi, quand album appelle la fonction <code>clean_name</code>, il appellera
galement la sous-routine appele <code>my_clean</code> de notre module
plug-in (sous-routine que nous devons fournir).

Pour crire cette sous-routine <code>my_clean</code>, regardons les
informations de la fonction 'hook' clean_name :
<tt>
  Args: ($opt, 'clean_name',  $name, $iscaption)
  Description: Nettoyer un nom de fichier pour affichage.
    Le nom est soit un nom de fichier soit il provient d'un fichier de lgendes.
  Retourne: le nom nettoy
</tt>

Les arguments que la sous-routine <code>my_clean</code> reoit sont spcifis
sur la premire ligne. Supposons qu'on veuille convertir tous les noms en
majuscules. Nous devrions utiliser :

<tt>
sub my_clean {
  my ($opt, $hookname, $name, $iscaption) = @_;
  return uc($name);
}
</tt>
Voici une explication sur les arguments :

<b>$opt</b>        Ceci est le descripteur de toutes les options d'album.
	    Nous ne nous en servons pas ici. Vous pourrez en avoir parfois
	    besoin si vous appelez les fonctions internes d'album. Ceci est
	    galement valable si l'argument <b>$data</b> est fourni.
<b>$hookname</b>   Dans notre cas, ce sera 'clean_name'. Ceci nous permet
	    d'enregistrer la mme sous-routine pour grer diffrentes
	    fonctions 'hooks'.
<b>$name</b>       Ceci est le nom que nous allons nettoyer.
<b>$iscaption</b>  Ceci nous indique si le nom provient d'un fichier de
	    lgendes.
	    Pour comprendre n'importe quelles options aprs la variable
	    <b>$hookname</b>, vous aurez peut-tre besoin de jeter un oeil sur
	    le code correspondant dans album.

Dans notre cas, nous avons seulement besoin d'utiliser la variable
<b>$name</b> fournie, nous appelons la routine perl de mise en majuscule et
nous retournons son rsultat. Le code est ainsi termin mais nous avons besoin
maintenant de crer un environnement pour notre module plug-in.

Des fonctions 'hooks' vous permettent de remplacer le code d'album. Par
exemple, vous pourriez crire du code pour un module plug-in qui gnre des
vignettes pour les fichiers au format pdf (utiliser l'outil 'convert' est un
desmoyens de le faire). Nous pouvons enregistrer du code pour la fonction
'hook' relative aux vignettes et simplement retourner 'undef' si nous ne
sommes pas en train de regarder un fichier pdf. Mais quand nous voyons un
fichier pdf, nous crons alors une vignette que nous retournons. Quand album
rcuprera une vignette, alors il utilisera celle-ci et sautera l'excution
de son propre code relatif aux vignettes.

Maintenant, terminons d'crire notre module plug-in de mise en majuscules. Un
module plug-in doit comporter les lments suivants :


<b>1)</b> Fournir une routine de dmarrage appele 'start_plugin'. Celle-ci
   fera srement l'enregistrement des fonctions 'hooks' et spcifiera les
   options en ligne de commande pour le module.


<b>2)</b> La routine 'start_plugin' <b>doit</b> retourne la table de hachage
   des informations du module, laquelle table a besoin d'avoir les cls
   suivantes dfinies :
   <i>author</i>      => Le nom de l'auteur
   <i>href</i>        => Une adresse internet (ou une adresse lectronique) de
   l'auteur
   <i>version</i>     => Le numro de version du module plug-in
   <i>description</i> => Un texte de description du module plug-in

<b>3)</b> Terminer le code du module en retournant '1' (similaire  un module perl).

Voici notre exemple de code plug-in <code>clean_name</code> dans son module
complet :

<hr>
sub start_plugin {
  my ($opt) = @_;

  album::hook($opt,'clean_name',\&my_clean);

  return {
    author => 'David Ljung Madison',
    href => 'http://MarginalHacks.com/',
    version => '1.0',
    description => "Conversion des noms des images en majuscules",
  };
}

sub my_clean {
  return uc($name);
}

1;
<hr>

Finalement, nous avons besoin de le sauvegarder quelque part. Les modules
plug-in tant organiss dans une hirarchie de rpertoires pour modules
plug-in, nous pourrions le sauver dans un rpertoire de module comme :

  <tt>captions/formatting/NAME.alp</tt>

En fait, si vous regardez dans <tt>examples/formatting/NAME.alp</tt>, vous
trouverez qu'il y a dj un module plug-in qui fait essentiellement la mme
chose.

Si vous souhaitez que votre module accepte des options en ligne de commande,
utilisez 'add_option'. Ceci <b>doit</b> tre ralis dans le code de la
routine  'start_plugin'. Quelques exemples :
<tt>
  album::add_option(1,"fast",album::OPTION_BOOL, usage=>"Fais le rapidement");
  album::add_option(1,"name", album::OPTION_STR, usage=>"Votre nom");
  album::add_option(1,"colors",album::OPTION_ARR, usage=>"Liste des couleurs");
</tt>
Pour de plus amples informations, regardez le code de la routine 'add_option'
dans album et jetez un oeil dans les autres routines qui l'utilisent (au dbut
du code d'album et dans les modules plug-in qui utilisent 'add_option').

Pour lire une option qu'un utilisateur pourrait avoir utilise, nous utilisons
la fonction option() :
<tt>
  my $fast = album::option($opt, "fast");
</tt>
Si l'utilisateur fournit une mauvaise valeur pour une option, vous pouvez
appeler la fonction usage() :
<tt>
  album::usage("-colors array can only include values [red, green, blue]");
</tt>
Si votre module plug-in a besoin de charger des modules perl qui ne font pas
partie de la distribution standard de Perl, faites-le de faon
conditionnelle. Pour avoir un example, regardez le module plug-in
plugins/extra/rss.alp.

Vous pouvez galement appeler n'importe quelle routines trouves dans le script
album en utilisant l'espace de nommage album::. Soyez sr de ce que vous
faites. Quelques routines utiles :

<tt>
  album::add_head($opt,$data, "&lt;meta name='ajoute_ceci' content=' &lt;head&gt;'&gt;");
  album::add_header($opt,$data, "&lt;p&gt;Ceci est ajout  l'en-tte de l'album");
  album::add_footer($opt,$data, "&lt;p&gt;Ceci est ajout au pied de page de l'album");
</tt>

Le meilleur moyen de savoir comment crire des modules plug-in est de regarder
d'autres modules plug-in, si possible en en copiant un ralisant une tache
similaire et en travaillant  partir de a. Des outils de dveloppement pour
les modules plug-in pourraient tre crer  l'avenir.

Une fois de plus, album peut vous aider  crer un environnement pour vos
modules plug-in :

<code>% album -create_plugin</code>

ITEM: Traduit par:

Jean-Marc [jean-marc.bouche AT 9online.fr]
</span>
