La v2 est une évolution majeure qui aura sa propre documentation.
Principe
Les documents liés aux contenus n’ont pas forcément tous la même fonction, il est parfois utile de distinguer le rôle de chaque document : à quoi sert-il ? Quel est son sens ?
Prenons un exemple concret : pour une librairie nous avons un objet éditorial « livre », chaque livre doît être accompagné de sa couverture (le logo), du 4ème de couverture, et d’une série d’extraits.
Le squelette correspondant a besoin d´afficher ces images en des endroits particuliers, il faut donc un moyen de les identifier dans des boucles différentes : c’est possible au moyen des rôles.
Utilisation
La gestion des rôles s´effectue sur place, dans la liste des documents liés aux contenus.
Un même document peut avoir plusieurs rôles.
Le rôle attribué par défaut est le rôle générique « document ».
Gestion des logos
Le plugin fournit 2 rôles supplémentaires : « logo » et « logo de survol ».
Il est donc possible de s’affranchir de la gestion historique des logos et de profiter des avantages des documents : vous pouvez leur donner un titre, un descriptif, des crédits, les réutiliser, les faire pivoter, etc.
Les balises #LOGO_XXX voient leur fonctionnement étendu : si aucun logo « historique » n´est présent, elles vont chercher un document avec le rôle de logo .
Dans la médiathèque, un nouvel onglet permet de visualiser les documents avec le rôle de logo :
NB — Le plugin Logos par rôle va plus loin en remplaçant complètement la gestion des logos par celles des rôles de documents, le formulaire des logos est entièrement remplacé.
NB 2 — La roadmap de la prochaine version de SPIP (3.3) prévoit que les logos soient gérés via la table spip_documents.
Intégration dans les squelettes
Par défaut les boucles DOCUMENTS ressortent tous les rôles, même les logos : il faut les exclure explicitement si besoin.
Il est possible d’utiliser les critères {role} et {par role}.
Exemples :
Filtrer les documents par rôle :
<BOUCLE_docs(DOCUMENTS documents_liens) {id_article} {role = bandeau}>
#LOGO_DOCUMENT
</BOUCLE_docs>Trier les documents par roles puis par titre :
<BOUCLE_docs(DOCUMENTS) {id_article} {par role,titre} >
#LOGO_DOCUMENT
</BOUCLE_docs>Afficher les rôles d´un document :
<BOUCLE_docs(DOCUMENTS) {id_article}>
#TITRE
Rôle(s) :
<BOUCLE_roles(documents_liens){id_document}{objet}{id_objet}{par role}{role!=''}{", "}>[(#ROLE|role{documents})]</BOUCLE_roles>
</BOUCLE_docs>Déclarer de nouveaux rôles
Tout est expliqué dans la documentation de l’API des rôles, mais reprenons les grandes lignes avec quelques exemples.
Les rôles se manipulent au moyen du pipeline declarer_tables_objets_sql.
Les 2 clés roles_titres et roles_objets permettent d’indiquer les chaînes de langues des nouveaux rôles, ainsi que les rôles possibles pour chaque type d’objet éditorial.
Attention, pour être sûr de vous appuyer sur les déclarations par défaut, pensez bien à nécessiter ou utiliser le plugin “roles_documents” dans le XML de votre plugin, afin de passer après dans le pipeline.
La clé roles_objets est un tableau associatif, vous avez donc la possibilité d’ajouter des valeurs à celles existantes, ou bien de remplacer complètement certaines entrées.
Gardez également bien en tête les priorités de l’API des rôles : il y a des rôles déclarés par défaut pour tous les objets, et optionnellement des rôles pour chaque type d’objet, ces derniers sont pris en priorité.
Le plugin ne déclare que les rôles par défaut pour tous les objets, dès que vous ajoutez des rôles pour un type d’objet en particulier, ils prendront le dessus, dans ce cas pensez à inclure le rôle « logo ».
Voici quelques exemples :
1) Compléter les rôles par défaut
On veut ajouter des rôles à tous les objets, tout en conservant ceux déclarés par le plugin : on fait un merge.
function monplugin_declarer_tables_objets_sql($tables){
$tables['spip_documents'] = array_merge_recursive(
$tables['spip_documents'],
array(
'roles_titres' => array(
'alpha' => 'monplugin:role_alpha',
'beta' => 'monplugin:role_beta'
),
'roles_objets' => array(
'*' => array(
'choix' => array('alpha', 'beta'),
),
),
)
);
return $tables;
}2) Remplacer complètement les rôles par défaut
On veut avoir complètement la main sur les rôles, pas de merge.
Dans ce cas, il faut penser à mettre le rôle « logo », et indiquer le choix par défaut.
function monplugin_declarer_tables_objets_sql($tables){
$tables['spip_documents']['roles_titres'] = array(
'alpha' => 'monplugin:role_alpha',
'beta' => 'monplugin:role_beta'
);
$tables['spip_documents']['roles_objets'] = array(
'*' => array(
'choix' => array('logo','alpha', 'beta'),
'defaut' => 'alpha',
),
);
return $tables;
}3) Avec des rôles par types d’objets
Un dernier exemple pour ajouter des rôles aux articles et aux brèves, tout en conservant les rôles par défaut pour les autres types d’objets.
Là on fait un merge pour garder la clé '*', et ajouter 2 clés 'articles' et 'breves'.
Comme dans l’exemple précédent, pour ces 2 objets il faut remettre le rôle « logo » et le choix par défaut.
$tables['spip_documents'] = array_merge_recursive(
$tables['spip_documents'],
array(
'roles_titres' => array(
'alpha' => 'monplugin:role_alpha',
'beta' => 'monplugin:role_beta',
),
'roles_objets' => array(
'articles' => array(
'choix' => array('document', 'logo', 'alpha'),
'defaut' => 'document',
),
'breves' => array(
'choix' => array('document', 'logo', 'beta'),
'defaut' => 'document',
),
),
)
);Limitations
l´API des rôles ne permet pour l´instant pas de limiter le nombre de rôles utilisés pour un objet.
Il est impossible de dire qu´un rôle « logo » ne peut être utilisé qu´une seule fois pour un contenu, par conséquent c´est aux rédacteurs à veiller à ne l´attribuer qu´une fois.
Discussions by date of activity
22 discussions
Hello,
Les logos des objets qui sont publiés (articles, rubriques, sites,.) sont indiqués comme “non publiés” dans la médiathèque.
C’est le cas par exemple avec le logo du site ( exemple : siteon0.png)
Cela n’empêche pas le site de fonctionner mais il est alors facile de supprimer ces docs, et donc de se retrouver sans logo de site !
Merci
dd
Mais ça fait un comportement différent de quand il n’y a pas le plugin et que tu ajoutes ces mêmes documents ?
Reply to this message
Hello,
Avec les plugins et SPIP à jour :
il apparaît que lorsqu’une rubrique est vide mais a un logo de rubrique partagé avec un autre objet publié, alors la rubrique n’est plus considérée comme vide et s’affiche sur le site public (mais sans contenu évidemment).
Effet de bord pas très pratique. Il faut penser à supprimer tous les docs / logos de la rubrique qui ne doit pas s’afficher..
dd
Bonjour,
Avec quelles versions de SPIP / PHP / Roles document ?
Un ticket est dispo ici : https://git.spip.net/spip-contrib-extensions/roles_documents/-/issues/71
Hello,
Je reviens ici tardivement.
Ma config :
SPIP 4.4.2
Rôles de documents 2.1.3
PHP Version 8.2.27
Après quelques tests il apparaît que lorsqu’une rubrique est vide et qu’on lui ajoute un document au format .svg ou .png alors elle reste au statut “brouillon”.
Si on lui ajoute un doc au format .jpg alors elle devient ’publiée".
Testé avec “Imagick” et “convert” comme traitement.
Merci
dd
Reply to this message
Bonjour,
J’ai un message d’erreur qui apparaît...
Warning: Undefined array key “variante” in /var/.... /plugins/auto/roles_documents-2.1.0/roles_documents_pipelines.php on line 40
J’ai effacé le cache mais cela s’affiche...
Autre problème, après avoir désinstaller le plugin.... tous les logos sont détachés des objets spip :-(
Spip 4.3.1 et plugin Roles de Documents 2.1.0
Existe-t-il un moyen de récupérer ces liens vers les logos ?
Reply to this message
Bonjour,
Sur un SPIP 4.2.14
avec le plugin Rôles de documents 2.0.5
Lorsque je veux ajouter un document à un article il y a une zone “Rôle” vide qui ne semble pas avoir de finalité.
<label for="champ_roles">Rôle</label>Je ne sais pas si c’est voulu, ou si j’ai un problème.
Merci
Reply to this message
Bonjour,
Après une mise à jour d’un site en Spip 3.2.19 vers 4.2.12, les documents sont affichés en double dans les pages articles et rubriques, y compris les documents ajoutés après l’update.
Est-ce que vous auriez une piste pour éviter cela svp ?
Ce n’est pas un problème de ce plugin.
Ce comportement se produit si le plugin est actif en même temps que le plugin Massicot qui surcharge le fichier “modeles/document_desc.html” et qui entraine l’affichage en double dans l’espace privé.
Reply to this message
Bonjour,
Est-ce normal que les logos disparaissent lors d’une mise à jour ?
Est-ce que ce plugin va être adapté pour Spip 4.1 ?
Ben... de mémoire, il était plus ou moins question que ce mode de gestion des logos devienne natif mais je ne sais pas ce qu’il en est...
Que quels logos disparaissent ? Il faut être plus précis, des logos “anciens” (logo originaux de SPIP) ? Ou des logos qui étaient faits en spip_documents avec le rôle logo ? Il faut arriver à trouver un cheminement qui permet de reproduire.
Perso je l’utilise en 4.0 et 4.1 et ça marche parfaitement, mais je n’ai jamais fait de migration depuis un 3, c’était des sites neufs. Faudrait tester un cas simple de migration (installer un SPIP 3 quasi vide, juste un ou deux articles avec des logos).
Et faire un ticket s’il faut : https://git.spip.net/spip-contrib-extensions/roles_documents/issues
ok, je viens de produire ce que je pense il voulait dire :
Effectivement, en SPIP 4.1 avec versions compatibles des plugins roles et role_document, dès que j’active les plugins, les logos :
ont en effet tous disparu et ne remontent même plus côté médiathèque
Le tout revient à la normale une fois que tu désactives role_documents
C’est comme s’il n’y avait pas de rétro compatibilité en fait. Soit tu gères tout avec des rôles, soit tu gères tout “à l’ancienne” mais il n’y a pas de demi-mesure ou de cohabitation. Donc pour les anciens sites en effet, ça peut devenir compliqué
La réponse est simple : le plugin n’est pas compatible SPIP 4+ à l’heure actuelle (malgré ce qui est indiqué dans paquet.xml, rastapopoulos, tes doigts !).
La nouvelle gestion des logos de SPIP nécessite pas mal d’adaptations, c’est en cours de route.
Pour les intéressé⋅e⋅s ça sera au point une fois tous les tickets de ce jalon fermés : https://git.spip.net/spip-contrib-extensions/roles_documents/issues?type=all&sort=&state=open&labels=&milestone=516&assignee=0
Wo eh tout est bon en master, c’est une version DEV qui est bien parfaitement destinée à SPIP 4, et qui n’a absolument pas de tag de release dessus. Tout est pile comme ça doit l’être dans le XML :)
Reply to this message
Hello,
Any update for SPIP 4.0,0?
Thank you
Hi, it’s definitely planned but there are some issues to sort out first, as logos and documents have been updated in Spip 4.
There will probably be a new documentation article when the new version is out, as the current one is a bit out of date.
Reply to this message
Bonjour,
Le menu déroulant lorsque l’on clique sur “modifier” dans le cartouche d’un document lié à un objet ne s’affiche pas chez moi (3.3.0-dev).
J’ai aussi tenté une déclaration de nouveaux rôles dans mon plugin objet, mais rien ne se passe et pas d’erreur js dans la console.
Le plugin rôles + rôles documents est-il opérationnel en 3.3.0-dev ?
Faut-il encore se baser dessus où va t’il être intégré au core prochainement ?
Merci pour vos éclairage !
Il ne va pas être intégré au core pour l’instant non. Et non il n’a pas du tout été vraiment testé et adapté pour la version dev de SPIP qui a eu quelques changements importants autour des documents.
Merci pour ton retour très clair.
Je fais donc à contrecœur l’impasse sur cette géniale innovation.
Bon we !
Si jamais la précision est utile : je viens d’essayer le plugin sur une copie d’un site 3.2 mis à jour en 3.3 (dev), l’activation du plugin provoque la suppression du logo de chaque article qui en possédait un. Les logos d’abord identifiés comme tel dans la table documents lors de mise à jour de spip sont ensuite identifiés comme “documents” par le plugin.
Les fichiers sont toujours dans le IMG/logos, mais si je souhaite rétablir la liaison entre l’image “document” (ex-logo) et l’article, elle est bien répertoriée dans la table documents de la base, mais elle n’est pas disponible dans l’interface des Documents de l’espace privé.
Pour le moment, je n’ai pas poussé plus loin l’utilisation du plugin avec spip 3.3 pour voir s’il y avait d’autres incompatibilités.
Bonjour à tous,
J’ai aussi fait le même constat que Christope : disparition des logos associés à divers objets lorsque le plugin est installé, sa désinstallation a résolu le problème.
Pour fonctionner le plugin a de mon côté nécessité la mise en place d’une astuce de Pierrox :
l’ajout d’un bout de css dans prive/style_prive_plugin_xxxx.html :
Sans quoi le sélecteur de rôle n’apparaissait pas.
Manque t’il beaucoup pour le rendre opérationnel avec la sortie de la 3.3 ?
oui il y a des choses non triviales à vérifier pour ne pas être en conflit avec la nouvelle manière de stocker les logos en 3.3
je ne sais pas encore si c’est surtout lors de la migration lancée par le core ou aussi après à l’utilisation, pas eu le temps de regarder
Reply to this message
Bonjour,
Désolée si mon interrogation vous paraît basique, j’ai l’impression d’être abrutie au dernier degré, et mes recherches n’ont fait qu’accentuer le sentiment...
Comment faire pour ajouter de nouveaux rôles ?
La doc ici indique un code .php, mais dans quel fichier le copier, comment, faut-il faire un plugin (et alors comment ? mais ça me semble bien compliqué, il doit y avoir plus simple...) ? Dans le readme.md, il est question de “plugin de squelette”, mais n’ai rien trouvé à ce propos ailleurs...
Et dans la présentation retrouvée dans la gestion des plugins :
Mais je ne vois toujours pas comment faire... Bref, j’y pige rien et serais pas fâchée d’un ’tit coup d’main :-)
Bon, j’ai beau consulter la doc, sur spip.net ou sur programmer.spip.net, faire des tests, toujours un grand mystère... J’ai l’impression de me heurter à une marche, une évidence pour qui sait, mais qui (me) reste inaccessible pour (moi) qui ne sai(s)t pas.
J’ai trouvé une autre solution, mais ça me plairait bien de parvenir à comprendre, si quelqu’un a une piste. Merci...
C’est pourtant tout expliqué, je vois pas comment on pourrait plus : ça dit que c’est dans le pipeline “declarer_tables_objets_sql” et que c’est en modifiant la déclaration de “spip_documents”, et ça montre même comment avec trois exemples avec “array_merge_recursive”.
Après si tu sais pas ce qu’est un pipeline ni comment on s’inscrit dedans… bah ça n’a rien à voir avec ce plugin mais avec SPIP en général, et donc c’est pas là qu’il faut commencer : apprendre à étendre SPIP (ou ses plugins).
Et là aussi toute la doc existe bien :
https://programmer.spip.net/Qu-est-ce-qu-un-pipeline
Bonsoir RastaPopoulos, et merci pour ta réponse.
Je ne dis pas du tout que le plugin est en cause, bien au contraire, j’aimerais pouvoir pleinement l’utiliser ! Et la doc je l’ai vue, lue et relue pourtant... c’est là justement que j’ai l’impression de me heurter à cette fameuse marche. Déclaration dans un plugin : faut-il que j’insère un fichier dans Rôles de documents ? En ajoutant la déclaration du pipeline dans paquet.xml ? est-ce que je ne risque pas de voir ces ajouts écrasés lors d’une mise à jour ? Faut-il alors plutôt créer un clone du plugin (ça me semble hasardeux non ) ?? Hors plugin, je n’arrive pas à piger comment déclarer le pipeline, quoi faire exactement des lignes indiquées
Si je créée un fichier squelettes/mon_skel.php par exemple (en plugin de squelette si j’arrive à recoller les morceaux ?), avec le code proposé, là encore comment déclarer le pipeline ? faut-il créer un paquet.xml ? dans ce cas-là faire plutôt un dossier ? dans squelette ou alors dans plugin ?
J’ai l’impression d’être complètement obtuse sur ce coup-là, c’est frustrant 0_o’
Bonjour lussye,
je pense que c’est normal que tu t’y perdes un peu car il y a certains présupposés avant de grimper la marche et il faut être clair·e pour avoir des réponses de même.
Si tu veux de l’aide il faut que tu dises ce que tu veux faire surtout et à quel endroit tu as un souci.
Marche par marche, et une question à la fois à résoudre, on peut t’aider plus facilement :)
Lussye : pour compléter un peu : non surtout tu ne modifie pas le plugin role de document. TU crée ton propre plugin qui va faire appel aux pipelines expliqués dans cette doc,
Donc pour faire court tu dois maitriser deux choses :
1. La création en general de plugin, et c’est ce vers quoi le lien programme.spip.net peut t’aider
2. Les pipelines propres à Roles de Document, et là dock est ici.
Donc je t’invite vraiment à lire la doc de programmer.spip.net, à la fois sur les plugins et sur les pipelines (théoriquement on peut utiliser des pipelines hors plugins, mais c’est pas conseiller) pour bien comprendre la notion, et ce que cela recouvre, et comment les utiliser.
Merci à vous tous, ça me donne déjà une ligne directrice du quoi explorer et sur quoi me concentrer... ma tête a tendance à un peu trop explorer toutes les supposées possibilités (et elles sont nombreuses avec SPIP, c’est ça qu’est chouette !) en même temps sinon, et face à du non connu quelle que soit la direction, ça finit vite en pelote ^_^
C’est plaisant de grimper les marches une par une, mais des fois certaines me semblent un peu hautes... Prochaine étape donc, création de plugin.
En fait, tout ce dont j’avais besoin, plus précisément, pour répondre à touti, c’est de créer un rôle “couverture”, différent du logo, qui a sa propre utilité évidemment, pour placer en haut de page d’article... (en attendant j’ai fait avec mot-clé, j’avoue, chuuut, répétez pas...)
Reply to this message
Bonjour,
Merci pour cet excellent plugin. Serait-il possible d’en faire bénéficier les logos de points géolocalisés du plugin GIS ?
Bonjour,
C’est déjà le cas quand on va sur la fiche d’un point GIS, le formulaire de logo à gauche propose des documents : exec=gis&id_gis=N
Ou peut-être pensais-tu à autre chose ?
Quand on téléverse un document dans un article, on peut lui assigner le role Logo.
Ce n’est pas le cas dans Gis. On peut téléverser un document (une image) pour qu’il soit le logo d’un point géolocalisé, mais on ne peut pas sélectionner un document de la médiathèque. A la réflexion, on aurait même pas besoin d’assigner le role logo.
Je ne reproduis toujours pas le problème.
Reprenons depus le début :)
Reply to this message
Add a comment
Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :
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.
Follow the comments:
|
