Table Of Contents

1. Qu'est-ce qu'un module plug-in ?
2. Installation d'un module plug-in et son support
3. Chargement / déchargement des modules plug-in
4. Options des modules plug-in
5. Ecrire des modules plug-in
6. Traduit par:

1:   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 façon de créer des
légendes EXIF ou quelque chose d'aussi compliqué que créer un album à partir
d'une base de données d'images plutôt que d'utiliser une hiérarchie dans un
système de fichiers.


2:   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 précédente version d'album qui ne dispose pas de modules plug-in
(pré v3.10), vous aurez besoin de faire une fois :

% album -configure

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 répertoires
par défaut des modules plug-in. album cherchera les modules plug-in dans un
certain nombre d'endroits. Ceux par défaut sont :

  /etc/album/plugins/
  /usr/share/album/plugins/
  $HOME/.album/plugins/

En réalité, ces répertoires 'plug-in' sont ceux trouvés dans les endroits
spécifiés par l'option '--data_path' dont les noms par défaut sont :

  /etc/album/
  /usr/share/album/
  $HOME/.album/

Vous pouvez spécifier un nouveau répertoire avec l'option '--data_path' et
ajouter un répertoire 'plugins' à ce niveau ou utiliser l'option
'--plugin_path'.

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

/etc/album/plugins/utils/mv.alp

alors vous l'appellerez ainsi :  utils/mv


3:   Chargement / déchargement des modules plug-in

Pour lister tous les modules plug-in actuellement installés, taper :

% album -list_plugins

Pour montrer des informations relatives à des modules spécifiques (en
utilisant 'utils/mv' comme exemple) :

% album -plugin_info utils/mv

Les modules plug-in seront sauvés dans le fichier de configuration pour un
album donné ainsi vous n'avez pas besoin de les respécifier à chaque fois, à
l'exclusion des modules plug-in qui s'exécutent une seule fois comme par
exemple 'utils/mv' ('mv' = 'move' : correspond à un déplacement de fichiers
donc ne peut être exécutée qu'une seule fois pour un jeu de fichiers donné).

Vous pouvez utiliser les options -no_plugin et -clear_plugin pour désactiver
les modules plug-in qui ont été sauvés dans le fichier de configuration de
l'album courant. De la même façon que les
options standard d'album, -no_plugin désactivera un module plug-in
spécifique alors que -clear_plugin désactivera l'ensemble des modules
plug-in. Toutes les options attachées à ces modules seront également
effacées.


4:   Options des modules plug-in

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

% album -plugin_usage utils/mv

Cependant, quand vous spécifiez une option pour un module plug-in, vous devez
indiquer à album à quel module plug-in l'option correspond. A la place de la
syntaxe utilisée pour les options standards d'album :

% album -une_option

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

% album -un_plugin:une_option

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

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

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 déjà chargé et ayant le
même nom :

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

Evidemment, les autres types d'options (chaînes de caractères, nombres et
tableaux) sont acceptés et utilisent la même convention. Ces options sont
sauvegardées dans le fichier de configuration de l'album de la même façon 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 déjà 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 spécifiez les options (autrement, album ne
saura pas à qui appartient l'option raccourcie).

Par exemple, considérons un module plug-in imaginaire :

% album -plugin un/exemple/vignetteGen Photos/Espagne

Après ça, supposons que nous voulons utiliser la variable booléenne "rapide" du
module vignetteGen.
Ceci ne fonctionnera pas :

% album -vignetteGen:rapide Photos/Espagne

Mais l'une de ces solutions fonctionnera :

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


5:   Ecrire des modules plug-in

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

Il y a de telles fonctions pour la plupart des fonctionnalités d'album et le
code du module plug-in peut souvent soit remplacer soit compléter le code
d'album. Davantage de ces fonctions pourraient être rajoutées dans les futures
versions d'album si besoin.

Vous pouvez afficher la liste de toutes ces fonctions autorisées par album :

% album -list_hooks

Et vous pouvez obtenir des informations spécifiques pour chacune de ces
fonctions :

% album -hook_info <hook_name>

Nous pouvons utiliser album pour générer à notre place un cadre pour nos
modules plug-in :

% album -create_plugin

Pour effectuer cette tâche, 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 déjà é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 album.
Par exemple, pour enregistrer le code pour la fonction 'hook'
clean_name, notre module plug-in appelle :

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

Ainsi, quand album appelle la fonction clean_name, il appellera
également la sous-routine appelée my_clean de notre module
plug-in (sous-routine que nous devons fournir).

Pour écrire cette sous-routine my_clean, regardons les
informations de la fonction 'hook' clean_name :

  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 légendes.
  Retourne: le nom nettoyé


Les arguments que la sous-routine my_clean reçoit sont spécifiés
sur la première ligne. Supposons qu'on veuille convertir tous les noms en
majuscules. Nous devrions utiliser :


sub my_clean {
  my ($opt, $hookname, $name, $iscaption) = @_;
  return uc($name);
}

Voici une explication sur les arguments :

$opt        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 $data est fourni.
$hookname   Dans notre cas, ce sera 'clean_name'. Ceci nous permet
	    d'enregistrer la même sous-routine pour gérer différentes
	    fonctions 'hooks'.
$name       Ceci est le nom que nous allons nettoyer.
$iscaption  Ceci nous indique si le nom provient d'un fichier de
	    légendes.
	    Pour comprendre n'importe quelles options après la variable
	    $hookname, 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
$name fournie, nous appelons la routine perl de mise en majuscule et
nous retournons son résultat. Le code est ainsi terminé mais nous avons besoin
maintenant de créer 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 génére 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 créons alors une vignette que nous retournons. Quand album
récupérera une vignette, alors il utilisera celle-ci et sautera l'exécution
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 éléments suivants :


1) Fournir une routine de démarrage appelée 'start_plugin'. Celle-ci
   fera sûrement l'enregistrement des fonctions 'hooks' et spécifiera les
   options en ligne de commande pour le module.


2) La routine 'start_plugin' doit retourne la table de hachage
   des informations du module, laquelle table a besoin d'avoir les clés
   suivantes définies :
   author      => Le nom de l'auteur
   href        => Une adresse internet (ou une adresse électronique) de
   l'auteur
   version     => Le numéro de version du module plug-in
   description => Un texte de description du module plug-in

3) Terminer le code du module en retournant '1' (similaire à un module perl).

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


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;


Finalement, nous avons besoin de le sauvegarder quelque part. Les modules
plug-in étant organisés dans une hiérarchie de répertoires pour modules
plug-in, nous pourrions le sauver dans un répertoire de module comme :

  captions/formatting/NAME.alp

En fait, si vous regardez dans examples/formatting/NAME.alp, vous
trouverez qu'il y a déjà un module plug-in qui fait essentiellement la même
chose.

Si vous souhaitez que votre module accepte des options en ligne de commande,
utilisez 'add_option'. Ceci doit être réalisé dans le code de la
routine  'start_plugin'. Quelques exemples :

  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");

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 début
du code d'album et dans les modules plug-in qui utilisent 'add_option').

Pour lire une option qu'un utilisateur pourrait avoir utilisée, nous utilisons
la fonction option() :

  my $fast = album::option($opt, "fast");

Si l'utilisateur fournit une mauvaise valeur pour une option, vous pouvez
appeler la fonction usage() :

  album::usage("-colors array can only include values [red, green, blue]");

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 façon
conditionnelle. Pour avoir un example, regardez le module plug-in
plugins/extra/rss.alp.

Vous pouvez également appeler n'importe quelle routines trouvées dans le script
album en utilisant l'espace de nommage album::. Soyez sûr de ce que vous
faites. Quelques routines utiles :


  album::add_head($opt,$data, "<meta name='ajoute_ceci' content='à <head>'>");
  album::add_header($opt,$data, "<p>Ceci est ajouté à l'en-tête de l'album");
  album::add_footer($opt,$data, "<p>Ceci est ajouté au pied de page de l'album");


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 réalisant une tache
similaire et en travaillant à partir de ça. Des outils de développement pour
les modules plug-in pourraient être créer à l'avenir.

Une fois de plus, album peut vous aider à créer un environnement pour vos
modules plug-in :

% album -create_plugin

6:   Traduit par:

Jean-Marc [jean-marc.bouche AT 9online.fr]