MarginalHacks album - Modules Plug-in : utilisation, création... - Documentation

| A l b u m S e v e n - - M o d u l e s P l u g - i n : u t i l i s a t i o n , c r � � a t i o n . . .

### Home
### Themes/Examples
### Languages
### Plugins
### License
### Download
### Documentation English Deutsch Español Français Nederlands Русский Italiano magyar
### Mailing List
### CHANGELOG
### Praises
### Contact
| Table Of Contents Qu'est-ce qu'un module plug-in ? Installation d'un module plug-in et son support Chargement / déchargement des modules plug-in Options des modules plug-in Ecrire des modules plug-in 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]
Created by make_faq from Marginal Hacks

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |