source: spip-zone/_plugins_/logos_roles/trunk/README.md @ 103433

Last change on this file since 103433 was 103433, checked in by bystrano@…, 3 years ago

afficher les logos stockés sous forme de documents dans la médiathèque

File size: 5.9 KB
Line 
1
2Logos par rôles
3===============
4
5Ce plugin modifie le système de logos de SPIP pour le rendre plus flexible et permettre de donner plus de contrôle aux rédacteurs.
6
7Un problème récurent avec les logos de SPIP, c'est qu'on veut les afficher à des endroits différents du site, en général dans plusieurs format différents.
8On peut par exemple afficher le logo d'un article sous la forme d'un petit carré dans les listes d'articles, mais aussi en grand format sur la page d'accueil.
9Les rédacteurs doivent alors trouver des images qui fonctionnent dans les deux formats, ce qui s'avère souvent impossible.
10
11On peut alors détourner les logos de survol, mais c'est vite limité.
12Parce que ça n'offre qu'un seul logo alternatif par objet éditorial, mais aussi parce que les rédacteurs ne voient pas le logo dans le bon format dans l'espace privé, ce qui oblige à des allers-retours.
13
14En utilisant ce plugin, on peut définir autant de types de logos qu'on le souhaite, qui peuvent alors être gérés indépendamment par les rédacteurs.
15On pourra alors utiliser une image différente pour la page d'accueil et pour les listes.
16
17Le plugin [Massicot](https://contrib.spip.net/Massicot) complète très bien ce plugin, et permet alors de définir des recadrages différents pour les différents types de logos.
18On peut aussi utiliser les formats prédéfinis pour le recadrage.
19
20
21Fonctionnement
22--------------
23
24Ce plugin s'appuie sur le plugin « Rôles de documents », et ré-implémente l'API des logos en se servant des rôles.
25Cela permet d'assurer une bonne rétro-compatibilité tout en permettant d'étendre le mécanisme des logos beaucoup plus facilement.
26
27L'idée est de se baser sur les rôles de documents dont le nom commence par `logo` pour définir les types de logos disponibles.
28Les rôles définis par le plugin « Rôles de documents » nous donnent les rôles habituels de spip : `logo` et `logo_survol`, mais on peut aussi ajouter d'autres rôles de logos via la méthode décrite dans [la documentation du plugin Rôles](http://contrib.spip.net/Des-roles-sur-des-liens).
29
30Pour simplifier les choses, on propose d'ajouter les nouveaux types de logos avec le pipeline `roles_logos` :
31
32
33        function prefix_plugin_roles_logos($logos) {
34
35                $logos['logo_bandeau'] = array(
36                        'label' => 'Bandeau du site',
37                        'objets' => array('site'),
38                        'dimensions' => array(
39                                'largeur' => 1200,
40                                'hauteur' => 300,
41                        ),
42                );
43
44                $logos['logo_extrait'] = array(
45                        'label' => 'Extraits pour les listes',
46                        'objets' => array('articles', 'rubriques'),
47                        'dimensions' => array(
48                                'largeur' => 800,
49                                'hauteur' => 500,
50                        ),
51                );
52
53                $logos['logo_slideshow'] = array(
54                        'label' => 'Slideshow page d'accueil',
55                        'objets' => array('articles', 'rubriques'),
56                );
57
58                return $logos;
59        }
60
61
62En se basant sur cette liste de rôles, le plugin se charge automatiquement de :
63
64- Déclarer les rôles de documents qui correspondent, en les liant aux bons objets.
65- Surcharger le formulaire d'édition des logos, pour permettre de gérer les différents types de logos.
66- Créer les balises pour afficher ces logos dans les squelettes. Avec l'exemple ci-dessus, on pourra alors appeler la balise `#LOGO_ARTICLE_EXTRAIT`, qui reverra le bon logo.
67
68### Paramètres des rôles de logo ###
69
70Les logos que l'on définit dans le pipeline `logos_roles` nécessitent au moins deux paramètres :
71
72- __label :__ Le nom du type de logo tel qu'il doit s'afficher dans l'espace privé. Peut être une chaîne de langue.
73- __objets :__ Une liste des types d'objets pour lesquels ce type de logo doit être actif.
74
75On peut aussi utiliser un paramètre __dimensions__ qui doit être un tableau avec les clés `largeur` et `hauteur`.
76Ce paramètre permet de forcer les dimensions d'un logo, la balise `#LOGO_` correspondante recadre alors automatiquement le logo.
77Cette fonction est particulièrement utile quand on utilise le plugin massicot, qui propose alors directement le bon format pour chaque type de logo.
78
79
80### Modification des boucles `DOCUMENTS` ###
81
82Pour des raisons de rétro-compatibilité, les boucles `DOCUMENTS` ne montrent pas les logos.
83Les logos n'apparaissent que si l'on utilise le critère `{role}` dans la boucle.
84
85
86Surcharges du core
87------------------
88
89On surcharge plusieurs fichiers du core :
90
91### Modification du formulaire `EDITER_LOGO` ###
92
93Ce formulaire se comporte plus ou moins comme l'ancien, avec quelques améliorations :
94
95- Il utilise les nouvelles APIs.
96- On ajoute automatiquement des champs d'upload fonctionnels pour tous les rôles de logos définis.
97- Permet d'éditer le document correspondant.
98- Ajoute un pipeline qui permet d'ajouter des liens d'actions en-dessous des aperçus de logo : `logo_desc_actions`.
99
100### Modification de `inc/chercher_logo.php` ###
101
102La façon habituelle d'appeler cette fonction donne les résultats habituels, on garde une totale rétro-compatibilité.
103Mais l'on peut aussi passer un rôle au paramètre `$mode`, et dans ce cas la fonction trouve un éventuel document associé à l'objet avec ce rôle.
104
105S'il existe un logo enregistré avec l'ancienne API, on le retourne en priorité.
106
107### Modification de `action/editer_logo.php` ###
108
109Ici aussi, on essaie de garder une totale rétro-compatibilité, mais en permettant d'utiliser un rôle dans le troisième paramètre.
110
111Les logos enregistrés avec l'ancienne API sont convertis à la nouvelle automatiquement.
112
113
114Reste à faire
115-------------
116
117### Migration des logos existants ###
118
119Comme les logos enregistrés avec l'ancienne API fonctionnent toujours avec la nouvelle, il n'y pas d'urgence à migrer, la cohabitation se fait bien.
120En l'état actuel, on peut passer un logo enregistré avec l'ancienne API à la nouvelle API en le ré-uploadant dans le formulaire d'édition des logos.
121Mais à terme il serait bien de migrer les logos historiques vers le système de rôles (?).
122
123Comme ça représente potentiellement beaucoup de logos, il faut être prudent.
124On pourrait se servir d'un cron qui le ferait petit à petit, et/ou une commande spip-cli ?
Note: See TracBrowser for help on using the repository browser.