Coppermine Photo Gallery v1.5.x: Documentation et manuel

Plugins

Qu'est-ce qu'un plugin ?

A partir de cpg1.4.0, Coppermine est livré avec une API pour les plugins ce qui permet aux auteurs de modifier les caractéristiques de Coppermine sans modifier le code de base, rendant plus facile la mise à jour ; ainsi les modifications n'ont pas à être refaite à chaque fois que vous mettez à jour votre version de Coppermine.

L'API des plugins

L'API des plugins est constituée de plusieurs "points d'insertion (hoocks)" dans le code de base de Coppermine qui permet aux auteurs de plugin d'interagir avec les fonctions primordial de Coppermine, ou d'ajouter des fonctionnalités. Il y a des limites à ce qui peut être fait en utilisant un plugin, puisque le nombre de points d'insertion est limité. En conséquence, tous les changements de comportements de Coppermine qui pourraientt être accomplis par la modification du code de base ne sont pas possibles à réaliser en utilisant l'API de plugin. Toutefois, pour la réalisation des ces modifications de comportements de Coppermine, l'aide d'un plugin est plus élégante et le plus souvent beaucoup plus facile à installer et à exécuter (au moins pour l'utilisateur final) que la modification brut du code de base. L’installation et la configuration d'un plugin ne demande pas à l’administrateur de Coppermine de modifier le code source - il vous suffit de télécharger le plugin, l'installer, le configurer et vous avez terminé. Si le plugin a été codé comme suggéré et est suffisamment évolué, il devrait proposer un écran de configuration qui ne nécessite pas de modification du code source.

Où trouver des plugins ?

Comme indiqué plus haut, l'API des plugins fournit aux développeurs une interface pour faire naitre des améliorations aux fonctionnalités de Coppermine qu'ils peuvent distribuer sur les canaux qu'ils préfèrent. Tous les plugins dont l'équipe de développement de Coppermine est tenue au courant (et qui sont libre en vertu d'une licence appropriée) sont disponibles sur le site officiel de Coppermine.

En outre, de nombreux plugins dont les développeurs de Coppermine sont tenus au courant ou qu'ils ont créé eux-mêmes sont stockées sur le référentiel Subversion (SVN) (→ Qu'est-ce que Subversion ?). Avec Subversion, les développeurs peuvent travailler sur le code des plugins en équipe, où chaque membre de l'équipe peut contribuer. En fait, Subversion est destiné à s'assurer qu'aucune des modifications et des améliorations apportées ne se perdent accidentellement. Donc, si vous voulez la version la plus aboutie, la plus récente d'un plugin, vous êtes invités à consulter le référentiel Subversion. Il faut cependant comprendre que l'utilisation de Subversion, ne sera pas pris en charge sur le forum d'aide de Coppermine, donc il ne faut pas poser des questions ici au sujet de SVN. Si vous décidez d'utiliser la version SVN d'un plugin, assurez-vous d'avoir lu la section Vérification des plugins.

Plugins livrés avec Coppermine

Coppermine est livré avec des plugins qui sont destinés à illustrer ce à quoi les plugins peuvent être utilisés. Ces plugins sont désactivés par défaut, de sorte que vous (en tant qu'administrateur) devez les activer délibérément (en utilisant le gestionnaire de plugin) si vous voulez les utiliser.

Les plugins qui sont livrés avec le package Coppermine ne sont pas couverts par le même niveau de support que les composants de base que sont livrés avec. Il n'y a aucune garantie que ces plugins en particulier resteront dans le pack des versions futures.

Vous pouvez trouver plus conseil sur les plugins dans le forum d'aide de Coppermine "cpg1.5 plugin contributions" à la fois par les développeurs de Coppermine et les contributions des utilisateurs.

• Cible du lien (link_target)

  Modifie la manière dont les liens externes sont ouverts: lorsque ce plugin est activé, tous les liens qui contiennent l'attribut rel="external" seront ouverts dans une nouvelle fenêtre (au lien de la même). Cela à le même effet que l'utilisation de l'attribut target="_blank", mais il ne rendra pas votre sortie HTML invalide.
  Ce plugin à surtout un impact sur le lien "Powered by Coppermine" au bas de la galerie. Il est fortement recommandé de ne plus utiliser l'attribut déprécié "target", comme expliqué dans l'article Nouvelle fenêtre dans un monde conforme aux standarts (New-Window Links in a Standards-Compliant World) par Kevin Yank.
  L'équipe de développement de Coppermine ne recommande pas l'utilisation de ce plugin: ouvrir un lien dans une nouvelle fenêtre signifie imposer un fonctionnement à vos visiteurs. Ils sont pratiquement tous en mesure d'ouvrir un lien dans un nouvel onglet ou dans une nouvelle fenêtre: vous devriez les laisser libre de leur décision si ils veulent quitter votre page.
  Nous suggérons de réfléchir à deux fois avant d'activer ce petit plugin: vous risuqez de perdre des visiteurs si vous les forcez à ouvrir un lien dans une nouvelle fenêtre, et vous risquez de perturber les débutants.
  Ce plugin a été ajouté a cpg1.5.x pour arrêter les demandes des utilisateurs qui continuent à vouloir ouvrir les liens externes dans une nouvelle fenêtre. L'équipe de développement n'est pas favorable à l'ouverture des liens externes dans une nouvelle fenêtre, mais nous sommes au courant que certains la souhaitent malheureusement. Utilisez ce plugin en connaissance de cause si vous le voulez vraiment.

• Qui est en ligne ? (onlinestats)

  Affiche un bloc sur chaque page de la galerie qui montre les utilisateurs et les invités effectivement en ligne. Le résultat ressemble à peu près à ceci:

  Qui est en ligne ?

  Il y a 42 utilisateurs enregistrés. Le dernier membre inscrit est foobar. Au total il y a 12 visiteurs en ligne: 3 utilisateurs enregistrés et 9 invités. La plupart des utilisateurs en ligne: 2 le 27/08/08 à 19:44. Les utilisateurs enregistrés qui ont été en ligne pendant les 10 dernières minutes: Bill, Linus, Steve.

  La sortie est un élément de page similaire à la liste de catégories ou des albums, vous pouvez donc déplacer ce bloc en utilisant l'option de configuration Contenu de la page principale. Une fois le plugin installé, le bloc "qui est en ligne" n'est pas tout de suite visible: vous devez d'abbord l'activer en ajoutant la chaine onlinestats (séparé par un slash) dans le paramètre mentionné plus hseparated with a slash) to the above mentioned setting "The content of the main page", so if that config option contained before catlist/alblist/random,2/lastup,2 vous devirez avoir maintenant catlist/alblist/random,2/lastup,2/onlinestats pour afficher le bloc de ce plugin sur la page index de la galerie.

• OpenSearch (opensearch)

  Une adaptation de OpenSearch pour Coppermine. Si il est activé, les visiteurs peuvent ajouter votre Galerie à leur barre de recherche du navigateur.
  Le plugin ajoute la balise META correspondant à l'en-tête de vos pages Coppermine et la création du fichier XML nécessaire qui décrit votre galerie, en ce fondant sur ce que vous avez spécifié pour "Nom de la galerie" et "Déscription de la galerie" dans la configuration de Coppermine.

• Sample Plugin (sample)

  Ceci est un exemple de plugin. Il ne fait rien de particulièrement utile - il n'est là que pour montrer ce que les plugins peuvent faire et comment les coder. Lorsqu'il est activé, il affichera un exemple de texte en rouge. Rappelez-vous que ce texte sera affiché à tous les visiteurs de votre galerie, quel que soit le niveau de privilège du visiteur, donc si vous avez activé ce plugin par curiosité, n'oubliez pas de le désactiver une fois que vous avez vu ce qu'il fait.

• User Gallery Alphabetic Tabbing (usergal_alphatabs)

  Ce qu'il fait: ce plugin affiche des onglets de A à Z en haut de la galeries des utilisateurs (user gallery) sur lesquels les visiteurs peuvent cliquer pour aller directement à une page qui affiche toutes les galeries des utilisateurs dont le nom commence par cette lettre. Plugin seulement recommandé pour être utilisé si vous avez un nombre très important de galeries d'utilisateur.

• Visible HookPoints (visiblehookpoints)

  Outil pour les développeurs de plugins afin de localiser les points d'entrée des plugins (plugin hooks) et les tables d'informations. N'activez pas ce plugin si vous ne voulez pas commencer à développer votre propre plugin.
  Dans certains cas, la sortie d'un point d'insertion n'est pas la même que celle de son affichage par le biais de la commande "echo". Un bon exemple est le "pied de page de la galerie (gallery_footer)"; il est executé très tôt et son ordret d'affichage est avant la déclaration du doctype, alors que le point d'insertion de la sortie actuelle est juste avant le texte "powered by" en bas du document.
  • Le premier marqueur est placé dans le code HTML au point d'insertion "echo".
  • Si le point d'insertion est un tableau alors le marqueur est associé à "_ARRAY"
  • Si le point d'insertion n'est pas un tableau, il a "_HTML" aassocié, et le marqueur est ajouté à la variable filtrée sans autre association
  • Dans tous les cas une var_dump de la variable filtrée est affiché dans la sortie HTML comme un commentaire HTML juste après chaque point d'affichage
  Il y a maintenant un affichage des statistiques montrant combient de fois chaque point d'insertion a été appelé. Il y a aussi une chronologie du moment où chaque point d'insertion a été exécuté par rapport au démarrage du script.

• SEF_URLS plugin

  Ce plugin active "Les URLs optimisé pour les moteurs de recherche " - Il est expérimental et doit âtre utilisé avec précausions.
  Le plugin SEF_URLs a été enlevé du pack pour cpg1.5.x à cause des problèmes connus qui fait que le plugin n'est pas prêt à êtr eutilisé en production. Il peut être obtenu depuis la page officielle de Coppermine - regardez le sujet d'annonce "SEF_URLs plugin for cpg1.5.x". Merci de noter que ce plugin n'offre pas de support d'aide, donc, ne posez pas de questions le concernant.

Le gestionnaire de plugin

Le gestionnaire de plugin est le lieu central d'où vous téléchargez, installez, configurez et supprimez des plugins. Il peut être accessible de deux manières:

• Utilisation du menu de Coppermine

  Connectez-vous en tant qu'administrateur, accédez au panneau de configuration de Coppermine, développez la section "paramètres généraux", puis cliquer sur "administrer les plugins" à côté de "Activer les plugins" (assurez-vous que vous avez coché "Activer les plugins") si vous prévoyez utiliser des plugins.

• Accéder directement au gestionnaire de plugin

  Assurez-vous que vous êtes connecté en tant qu'administrateur, puis entrez directement l'URL du gestionnaire de plugin dans la barre d'adresse de votre navigateur, par exemple, http://votresite.fr/votre_dossier_coppermine/pluginmgr.php

Le gestionnaire de plugin organise les plugins que vous avez dans votre répertoire de Coppermine. Il est important de comprendre la différence entre le téléchargement et l’installation de plugins. Lorsque vous copiez un plugin dans le dossier plugins de Coppermine (en utilisant le bouton Télécharger dans le gestionnaire de plugin ou via FTP), vous avez simplement transféré les fichiers du plugin. Le plugin n'est pas encore installé. Lorsque vous installez un plugin, Coppermine démarre une routine d'installation pour configurer le plugin et activez le plugin de sorte qu'il sera exécuté lorsque des personnes utilisent votre galerie. Pour montrer clairement quels sont les plugins qui sont en cours d'exécution et ceux qui ne le sont pas, le gestionnaire de plugin est séparé en trois sections (voir capture d'écran ci-dessous):

• Un cadre global qui active / désactive l'utilisation des plugins (partie supérieure, peut être changé dans la page de configuration)
• les plugins qui sont installés et en cours d'exécutions (section du milieu)
• Les plugins qui existent dans le dossier plugins du disque dur de votre serveur, mais qui n'ont pas été installés et ne sont donc pas en cours d'exécution dans votre galerie Coppermine (section inférieure)

Par défaut, Coppermine est livré avec quelques exemples de code ou de plugins (aucun d'entre eux ne sont activés par défaut), des plugins supplémentaires peuvent être trouvées dans la section correspondante du forum de Coppermine.

Téléchargement d'un plugin

Sauf si vous avez votre propre code de plugin, ils sont généralement déjà packagés, compressé dans un fichier zip. Il y a deux manières de télécharger un plugin:

• Méthode 1: Utilisation de l'interface de téléchargement dans le gestionnaire de plugin de Coppermine

  • Télécharger le plugin dont vous avez besoin sur internet (habituellement le site de Coppermine) sur votre disque dur local
  • Cliquez sur le bouton "Parcourir" dans le gestionnaire de plugin
  • Accédez au fichier ZIP du plugin que vous venez de téléchargé sur le disque dur de votre PC local
  • Cliquez sur "Télécharger"
  Il s'agit de la solution la plus élégante et la plus facile - il suffit d'utiliser le contrôle de téléchargement sur la page du gestionnaire de plugin et le fichier archive que vous avez téléchargé s’extraira de l'archive et ce stockera sur le serveur dans le dossier approprié. Il y a deux pré-requis:
  • PHP qui est en cours d'exécution sur votre serveur web à besoin de supporter zip - tous les serveurs Web n’ont pas activé le support zip.
  • Le script a besoin des autorisations d'écritures dans le dossier plugins.
  Si vous omettez ces deux pré-requis, cette méthode simple (interface de téléchargement) ne fonctionnera pas (vous obtiendrez des messages d'erreurs lorsque vous essayerez, ou le plugin ne va simplement pas fonctionner sans même un message d'erreur). Si tel est le cas pour vous, il est recommandé de ne pas mettre le fatras dans la configuration du serveur (sauf si vous êtes un expert et que vous administriez le serveur), mais juste d'utiliser la seconde méthode de téléchargement du cas de figure ci-dessous.

• Méthode 2: Téléchargement des fichiers du plugin dézippé en utilisant votre logiciel FTP

  • Télécharger le plugin dont vous avez besoin à partir d'internet vers votre disque dur local (même démarche que ci-dessus)
  • Décompressez le fichier zip dans un dossier sur votre disque dur (en préservant la structure du dossier du plugin)
  • Utilisez votre logiciel FTP pour télécharger les fichiers du plugin décompressés dans le dossier plugins de votre installation de Coppermine sur votre serveur, en conservant la structure de l'archive zip.
    Par exemple: si le plugin contenu dans le dossier "foobar", contient les fichiers réels du plugin, vous téléchargez tout le dossier "foobar" et tout son contenu dans le dossier plugins. La structure du dossier résultant sur votre serveur devrait être quelque chose comme /votre_dossier_coppermine/plugins/foobar/

Après avoir téléchargé les fichiers (vous pouvez avoir besoin de rafraîchir la page du gestionnaire de plugin), le plugin vous venez de transférer s’affiche dans la liste "Plugins non-installés". Si c'est le cas, vous pouvez continuer l'étape suivante et installer le plugin.

Installation d'un plugin

L'installation d'un plugin est assez simple - il suffit de cliquer l'icône à côté du plugin. L'installation permettra au plugin de s’exécuter lorsque Coppermine sera en cours d'exécution (selon l'objet du plugin). Quelques plugins sont livrés avec une page de configuration qui sera exécutée juste après l'installation - si tel est le cas, le configurer en conséquence.

Un contrôle de routine tente de déterminer si un plugin a été conçu pour votre version de Coppermine.

• Si la vérification réussit, l'icône cochéé d'installation du plugin s'affiche: .
  Le plugin a été conçu pour votre version de Coppermine et devrait donc fonctionner comme prévu. Vous pouvez installer ce plugin en cliquant sur l'icône.
• Si la vérification échoue, c'est à dire si la routine de vérification détermine qu'un plugin n'était certainement pas pas destiné à votre version de Coppermine, l'icône annuler () s'affichera à côté du plugin. Vous ne pouvez pas cliquer sur cette icône, et par la suite vous ne pourrez pas installer le plugin.
• Si le code du plugin n'a pas été conçu avec la routine de vérification à l'esprit (ce qui sera le cas pour tous les plugins conçus / disponible avant le 24/01/2010), il ne sera pas possible pour le script de déterminer si le plugin a été conçu pour une version particulière. L'icône dans gestionnaire de plugin sans être coché () sera affichée à côté de ces plugins. Vous pouvez cliquer sur de telles icônes pour démarrer l'installation, mais on vous avertira en premier lieu sur les dangers concernant l'installation de plugins qui n'ont pas été conçus pour votre version de Coppermine).
  Détails

  Echec de la détermination de la version

  Peu de temps avant la sortie de cpg1.5.x comme "release candidate" (en cpg1.5.3) une fonctionnalité a été ajoutée au gestionnaire de plugin qui tente de déterminer pour chaque plugin s’il a été conçu pour être utilisé avec votre version de Coppermine. Cette fonctionnalité a été ajoutée comme une précaution supplémentaire: l'installation d'un plugin qui n'a pas été conçu pour votre version de Coppermine peut corrompre votre galerie entière. Un paramètre correspondant a été ajouté au cahier des charges pour un plugin: les concepteurs de plugin sont invités à préciser dans leur code pour quelle version de Coppermine leur plugin est supposé travailler.

  • Si vous êtes un concepteur de plugin, lisez les détails dans Ecrire un plugin pour Coppermine → Fichiers de base → configuration.php → $plugin_cpg_version.

  • Si vous êtes juste un utilisateur et non un auteur de plugin, vous n'avez pas besoin de lire tous ces détails - vous devez juste être conscient des mécanismes utilisés: il n'y a aucune garantie que l'auteur du plugin ait ajouté la version de Coppermine comme paramètres de base des exigences au code du plugin. Si ce morceau de données n'a pas été ajouté cela ne signifie pas que le plugin est mal écrit ou quelque chose comme ça: lorsque vous tentez d'installer un tel plugin, vous obtenez un message qui dit Impossible de déterminer les exigences pour la version ce plugin. C’est généralement un indicateur que le plugin n'a pas été conçu pour votre version de Coppermine et pourrait donc planter votre galerie. Continuez malgré tout (non recommandé) ?. S'il vous plaît veuillez comprendre que ce message ne signifie pas que le plugin lui-même est en faute. Il signifie que vous en tant qu'administrateur de la galerie devez faire en sorte de vérifier que le plugin que vous êtes sur le point d'installer a été effectivement conçu pour la version de Coppermine que vous utilisez. Pour ce faire, consultez le fichier "readme" qui pourrait être contenu dans le packge du plugin et regardez l'annonce du plugin.

  S'il vous plaît ne posez pas de questions sur le forum d'aide de Coppermine du genre "je suis mis en garde comme quoi la version du plugin ne peut être déterminée. Dois je continuer à l’installer ou pas ?": Vous devriez être en mesure de voir par vous-même si les versions correspondent. Si c en'est pas le cas ou si vous ne pouvez pas déterminer la version, installez le plugin à vos propres risques. Le message, dit exactement que la version ne peut être déterminée, c'est tout. Il ne dit pas "de ne pas utiliser le plugin". Il dit seulement "Hé, je ne suis pas sûr si le plugin, que vous êtes sur le point d'installer correspond à cette version de Coppermine". Le message signifie simplement que vous (en tant qu’être humain) devez vérifier ce que la machine ne peut pas. Ainsi, vous vérifiez: quelle version du plugin essayez-vous d'installer ? Si le plugin a été conçu pour votre version de Coppermine, tout va très bien et vous pouvez aller de l'avant en installant le plugin, même si l'avertissement apparaît.

  Normalement, le nombre de plugins qui ne contiennent pas l’exigence du paramètre de version de Coppermine devrait diminuer à l'avenir.

Configuration de plugin

Certains plugins peuvent être configurés pendant l'installation, d'autres peuvent avoir une page de configuration séparée qui peut être consultée à tout moment. Cela dépend de la façon dont l'auteur à écrit le plugin, nous ne pouvons pas donner de recommandations au sein de cette documentation. Certains plugins peuvent même avoir besoin d'être configuré avant d'être transféré en faite (en particulier avec les plugins en version alpha ou bêta - ceux-ci peuvent être publiés sans une page de configuration et vous obliger à modifier le code du plugin pour le configurer). En cas de doute, jetez un œil dans les archives plugin décompressé sur votre disque dur - en général, les plugins qui vous demandent de modifier ou de configurer quoi que ce soit sont livrés avec un fichier README qui vous explique comment faire.

Désinstallation d'un plugin

L’exécution d'un plugin peut-être consommateur de ressources ou ne pas fonctionner comme prévu, de sorte que vous pourriez vouloir désinstaller un plugin à un certain moment (peut-être parce que vous l'avez juste essayé et qu’il ne fonctionne pas comme prévu pour vous). Il est recommandé de ne pas seulement supprimer le sous-dossier du plugin en utilisant votre logiciel FTP (parce que le plugin peut avoir appliqué des changements dans la base de données qui doivent être effacés). Au lieu de cela, vous devez aller dans le gestionnaire de plugin, et cliquez sur l'icône . Le plugin devrait alors se désinstaller et retourner dans la liste des "Plugins non-installés". Il n’est pas dangereux de laisser la source d'un plugin inutile sur le serveur, donc il ne devrait pas être nécessaire de supprimer les droits d’un plugin après la désinstallation, mais vous pouvez aussi bien le supprimer, surtout si vous êtes à court d'espace web et que le plugin demande beaucoup d'espace.

Pour supprimer définitivement un plugin inactif du dossier plugin de votre serveur, cliquez sur l'icône à côté du plugin qui est dans la liste "Plugins non-installés". Si le script ne parvient pas à supprimer un plugin de cette manière (par manque de permissions pour le faire sur le fichier / niveau de dossier), vous pouvez utiliser votre logiciel FTP pour supprimer le sous le sous-dossier d’un plugin en particulier à l'intérieur du dossier "plugins" de Coppermine (suppression manuelle). Comme pour toutes les opérations de suppression, vous devriez faire une sauvegarde locale avant de supprimer si vous n'êtes pas absolument sûr de ce que vous faites.

L'écriture des plugins

Il y a peu de documentation disponible par les auteurs de plugins, de sorte que la meilleure méthode pour apprendre comment fonctionnent un plugin c’est en regardant le code source. Examinez le code des plugins qui sont fournis avec Coppermine, ou jetez un œil à certains qui sont disponibles en téléchargement depuis la page du forum des contributions de plugin sur le site de Coppermine.

Si vous avez créerun plugin, nous vous demandons de le partager avec la communauté de Coppermine en l'affichant sur le forum approprié (ce n'est bien sûr pas obligatoire, mais nous vous serions reconnaissants de voir votre contribution). Nous serions heureux de contribuer à la documentation de l'API du plugin et à référencer la liste des points d'insertion du plugin, ainsi que d'autres documents connexes.

Bien qu'il ne soit pas obligatoire (techniquement parlant) d'ajouter des instructions à un plugin, il est recommandé d'inclure un fichier readme avec votre plugin qui explique ce qu'il fait et comment l'utiliser.

Nous demandons également aux auteurs de plugins ainsi de garder à l'esprit i18n tout le monde ne sera pas à l’aise en utilisant la langue que vous avez utilisée. Par conséquent, c'est toujours une bonne idée de garder à l'esprit les traductions possibles lorsque vous concevez votre plugin.

S'il vous plaît référez vous à la section rédaction de plugin pour plus de détails.