Utiliser la médiathèque dans vos plugins « objet »

Attention, cette contribution est EN CHANTIER : elle n’est peut-être pas fonctionnelle.

Ceci est une « contribution pédagogique », qui montre par l’exemple comment développer une nouvelle fonctionnalité pour SPIP.

Certains plugins ajoutant de nouveaux objets utilisent le core de spip pour gérer l’ajout de documents. Médiathèque étant une API de gestion de documents voici quelques astuces pour l’utiliser au mieux sans s’embêter..

/ !\ Avertissement / !\

On documente ici des points d’entrées qui sont suceptibles d’être modifiés lorsque la médiathèque sera intégrée au core pour la prochaine mise à jour majeure de SPIP.
Mais a priori, on pourra toujours le faire, peut-être d’une manière différente, voilà tout. Je tacherai de mettre à jour cette documentation si c’est le cas.

Pré-requis

La 1re chose à faire, c’est de dire à votre plugin qu’il doit utiliser la médiathèque :

  • Soit votre plugin peut fonctionner "en mode dégradé (ie, pas de gestion de documents), vous pouvez indiquez la directive dans votre plugin.xml [1] :
    <utilise id="medias" version='[1.5;]'/>
  • Soit c’est essentiel, et votre plugin ne doit pas s’installer sans elle :
    <necessite id="medias" version='[1.5;]'/>

Ensuite, pour disposer de la gestion de documents dans votre page d’édition, le plus simple est de nommer votre exec d’edition NomDeVotreObjets_edit.php

Par exemple, avec l’objet patate, il faudra l’appeler patates_edit.php dans le dossier exec de votre plugin. Donc attention au « s », qui permet à spip de déduire le nom de votre objet. Il est toutefois possible d’utiliser un autre nom d’objet si vous déclarez la correspondance entre le nom d’objet et sa table SQL via le pipeline declarer_tables_objets_surnoms.

Par exemple, si votre objet s’appelle hibou, il est probable que sa table sql s’appellera hiboux et non pas hibous. Il suffira alors d’utiliser ce pipeline pour que la mediathèque de la sorte :

      function hiboux_declarer_tables_objets_surnoms($surnoms) {
          $surnoms['hibou'] = 'hiboux';
          return $surnoms;
      }

Ainsi, vous pourrez nommer votre page hiboux_edit et médiathèque (ou plutôt la fonction objet_type($table) de spip qu’utilise médiathèque pour obtenir le nom de l’objet) pourra gérer ça très bien.

Un pipeline, une variable dispo dans le contexte global et c’est bon !

Afficher la gestion de documents

Votre plugin devra appeler le pipeline affiche_gauche, et... C’est presque tout. En une ligne supplémentaire, soit pour l’objet patate :

$GLOBALS['medias_exec_colonne_document'][] = 'patates_edit';

Votre plugin délègue la gestion des documents à la médiathèque. Génial non ?

Détecter les documents à lier à l’objet

Spip dispose d’une superbe fonction, marquer_doublons_docs, qui permet de repérer dans un texte ou un chapo les documents qui sont appelés par l’objet via et les liés à l’objet s’il n’y sont pas déjà.
Il suffit d’appeler le pipeline post_edition dans votre plugin, et c’est bon ! Sauf que si votre champ s’appelle descriptif, ça ne fonctionne pas... Eh bien, pour ça aussi, la médiathèque gère pour vous !
Bien sûr, si vous voulez nommer votre champ autrement que chapo ou texte, ça ne fonctionnera pas. Alors, la médiathèque a pensé à vous une fois de plus. En ajoutant :

$GLOBALS['medias_liste_champs'][] = 'descriptif';

La fonction sera chargée également pour les champs descriptif (et ce, quelque soit l’objet). A personnaliser selon les noms de vos champs, mais pour plus de simplicité, utiliser donc chapo et / ou texte !

Récapitulatif

Soit un plugin patates, avec un champ descriptif, qui veut gérer impeccablement les documents : le plugin.xml comporte en plus des autres instructions (si votre fichier de pipeline s’appelle patates_pipeline.php et qu’il se trouve à la racine du plugin et qu’il n’utilise pas déjà les pipelines ci-dessous) :

	<pipeline>
		<nom>post_edition</nom>
		<inclure>patates_pipelines.php</inclure>
	</pipeline>
	<pipeline>
		<nom>affiche_gauche</nom>
		<inclure>patates_pipelines.php</inclure>
	</pipeline>
<necessite id="medias" version='[1.5;]'/>

Votre fichier patates_pipelines.php comportera :

$GLOBALS['medias_exec_colonne_document'][] = ' patates_edit';
$GLOBALS['medias_liste_champs'][] = 'descriptif';
function  patate_post_edition($flux){}
function patate_affiche_gauche($flux){}

Ceci est parfaitement applicable sur pas mal de plugins d’objet. Je l’ai utilisé pour ma part sur Agenda2, et ça m’a bien rendu service ! Vous pouvez voir comment sur la zone dans ce petit plugin qui ajoute en plus des documents la gestion des logos sur les évènements d’Agenda2 docs_logos_agenda2. Pour le moment, il ne les gère qu’une fois qu’ils ont un id_evenement, donc après un premier enregistrement.

Notes

[1c’est à partir de la version 1.3.5 de mediathèque que ce qui va suivre fonctionne, toutefois le plugin mediathèque ayant changé de préfix (anciennement gestdoc, nouvellement medias) nous prendrons la version « medias » soit la 1.5 !

Discussion

Une discussion

  • Avec SPIP 3.0.0-alpha, pour un plugin avec le prefixe monobjet :

    • dans monobjet_autoriser.php, inserer une fonction :
      function autoriser_monobjet_joindredocument_dist($faire, $type, $id, $qui, $opt) {
    • dans la page privé de l’objet (prive/squelettes/contenu/monobjet.html), ajouter :
      #PIPELINE{afficher_complement_objet,
          #ARRAY{args,#ARRAY{
              type,monobjet,
              id,#ID_MONOBJET},
          data,'<div class="nettoyeur"></div>'}}

    Et c’est tout : on a accès a l’ajout de documents sur monobjet.

    Attention, pour que ca soit bien propre, dans la fonction de nettoyage de la base de donnée en cas de désinstallation du plugin monobjet, ne pas oublier d’effacer les lignes dans spip_documents_liens :

    function monobjet_vider_tables($nom_meta_base_version) {
        sql_delete(
            'spip_documents_liens', 
            'objet='.sql_quote('monobjet')
        );

    Et sinon, depuis l’espace public on peut utiliser

    • #FORMULAIRE_JOINDRE_DOCUMENT
    • [(#INCLURE{fond=inclure/documents_monobjet,id_monobjet})], en prenant bien soin de creer le fichier de portfolio inclure/documents_monobjet

    Répondre à ce message

Ajouter un commentaire

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparaît.

Merci d’avance pour les personnes qui vous aideront !

Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.

Qui êtes-vous ?
[Se connecter]

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom