Prise en charge d’un objet par le plugin Grappes

Un petit tutoriel ou résumé expliquant comment ajouter la prise en charge d’un objet au plugin Grappes.

Le plugin Grappe propose de créer des groupes d’objets, il peut être utilisé aussi bien pour créer des Carousels, des widgets de liste de documents ou articles, des sélections d’articles a mettre a la une, etc, remplaçant avantageusement ET de manière élégante le système des mot-clefs techniques. Le rédacteur ou webmestre y gagnant en terme de simplicité d’utilisation et de gestion :

  • Plus de mots techniques numérotés (carousel1, carousel2 ...)
  • Des classements crayonables (en attendant un plugin dédié a cette fonction)
  • l’association directement depuis la vue de l’objet ou depuis la grappe

L’exemple qui suit est basé sur un plugin : vitrines, déclarant un objet VITRINE.

En bref, pour pouvoir associer notre objet vitrine nous devons :

  • En premier lieu : ajouter notre objet aux possibilités de liaisons du plugin Grappe.
  • Créer un squelette d’affichage/vue des objets associés à la grappe
  • Créer un sélecteur générique, qui permettra grâce a jqueryUi autocomplete, de chercher et trouver nos objets d’une manière efficace, rapide et agréable.

Ajouter l’objet aux liaisons du plugin Grappe

En premier lieu, on ajoute au paquet.xml :

<necessite nom="grappes" />

Plus d’infos sur la rédaction du paquet.xml

Depuis SPIP3 on peut, de manière générique en utilisant l’API objet, ajouter des liaisons entre objets. Il faut pour cela déclarer la table liaison puis utiliser la saisie choisir_objets dans son formulaire de configuration.
Cf API - editer_liens

Le plugin Grappe, bien qu’utilisant l’API objet, propose un pipeline spécifique pour que les plugins puissent y ajouter leurs liaisons. Ceci a l’avantage que dès l’activation de notre plugin la liaison sera effective, sans aucune autre configuration.

Si vous ne savez pas ce qu’est un pipeline, voyez : Programmmez avec Spip 3 : Les pipelines

-  Ajouter au paquet xml du plugin (ex : vitrines), en utilisant la pipeline grappes_objet_lies

<pipeline nom="grappes_objets_lies" inclure="vitrines_pipelines.php" />

Ici rien de bien compliqué, on nomme le point d’entrée/pipeline que l’on souhaite utiliser, et dans quel fichier on a placé notre fonction.

-  Dans le fichier vitrines_pipelines, ajouter l’association

Le commentaire du développeur du plugin est suffisamment explicite et on l’en remercie au passage :

/**
 * Insertion dans le pipeline grappes_objets_lies (Plugin Grappes)
 * Définis le tableau des objets pouvant être liés aux grappes, la clé est le type d'objet (au pluriel),
 * la valeur, le label affiché dans le formulaire d'édition de grappe
 * @param array $array
 * 	Le tableau du pipeline
 * @return array $array
 * 	Le tableau complété
 */
function vitrines_grappes_objets_lies($array){
	$array['vitrines'] = _T('vitrines:vitrines');
	return $array;
}

A noter : Pour fonctionner, l’ajout à la pipeline doit toujours être préfixé par le prefix de votre plugin (juste pour ceux qui copient-collent sauvagement ...).

On pourrait aussi, par exemple, y déclarer plus d’une association d’objet, sans toucher aux plugins qui sont concernés. Par exemple, ajouter un objet GIS, servant a faire des grappes de points géo-localisés (au hasard ...).

Lister les objets associés a la Grappe

Comme l’explique la documentation de l’API editer_liens dans la section Interface d’édition, il faut encore un squelette de vue permettant de lister nos liaisons et le squelette d’association, qui dans le plugin Grappes est gérée par le plugin Sélecteur générique.

Nous créons donc la liste d’affichage des Vitrines associées à la Grappe dans prive/objets/liste/grappes-vitrines_lies.html

#SET{selection,#ENV{objet}|objet_type|lister_objets_lies{grappe,#ID_GRAPPE,grappe}}
<B_liste>
#ANCRE_PAGINATION
<div class="liste-objets liste-objets-lies vitrines">
<table class='spip liste'>
	[<caption><strong class="caption">(#ENV*{titre,#GRAND_TOTAL|singulier_ou_pluriel{info_1_article,info_nb_articles}})</strong></caption>]
	<tbody>
	<BOUCLE_liste(VITRINES){id_vitrine IN #GET{selection}}{pagination 10}{recherche ?}{statut?}{tout}>
		<tr class="[(#COMPTEUR_BOUCLE|alterner{row_odd,row_even})]">
			<td class='statut'>[(#STATUT|puce_statut{article,#ID_ARTICLE,#ID_RUBRIQUE})]</td>
[(#REM) Prise en charge du RANG Crayonable]
<td class="rang">
                            <BOUCLE_affRang(spip_grappes_liens){id_objet=#ID_VITRINE}>
                                       <span class="#EDIT{rang}">#RANG</span> 
                            </BOUCLE_affRang>
                        </td>
			<td class='titre principale'>#TITRE</td>
			<td class='id'><a href="[(#ID_ARTICLE|generer_url_entite{article})]"><:grappes:voir:></a></td>
			[(#ENV{editable})
			<td class='action'>[(#BOUTON_ACTION{<:grappes:delier:> [(#CHEMIN_IMAGE{supprimer-12.png}|balise_img{'X'})],#URL_ACTION_AUTEUR{lier_objets,delier/grappe/#ID_GRAPPE/vitrine/#ID_VITRINE,#SELF},ajax})]</td>
		]</tr>
	</BOUCLE_liste>
	</tbody>
</table>
[<p class="pagination">(#PAGINATION{prive})</p>]
</div>
</B_liste>
<div class="liste-objets liste-objets-lies vitrines caption-wrap"><strong class="caption"><:info_aucune_vitrine:></strong></div>
<//B_liste>

A noter :

  • Ce squelette est juste une adaptation de la vue qui liste les articles, disponible dans le plugin Grappes Cf Grappes/prive/objets/listes.
  • À la différence, ce squelette ajoute le #RANG, et vous permettra d’éditer le classement de nos VITRINES, si vous activez les crayons dans l’espace privé.

Prise en charge du sélecteur générique

Comme mentionné précédemment, c’est le plugin Sélecteur générique qui va s’occuper de gérer notre vue d’association.
Voir la documentation du plugin Sélecteur générique. Cette documentation explique brièvement comment créer un Selecteur générique.

Les sélecteurs utilisant Jquery.ui.autocomplete, les données doivent être retournées au format JSON, qui est le format de description utilisé par javascript pour les données de type objet, array ou listes.
Chaque fois que l’internaute effectuera une saisie dans le champ input de recherche, on enverra une requête qui sera retournée en JSON et affichée.

Créer un dossier selecteurs/ à la racine de votre squelette et dedans le fichier grappes_vitrines.html

Comme pour tous les squelettes renvoyant des données dans un format autre que html , on commence donc par déclarer un #HEADER.
De plus on désactivee le CACHE...

#HTTP_HEADER{Content-Type: text/plain; charset=#CHARSET}
#CACHE{0}
#SET{resultats, #LISTE}
<BOUCLE_s(VITRINES){titre LIKE %(#ENV{q})%}{0,20}{par multi titre}>
[(#SET{resultats, [(#GET{resultats}|push{[(#ARRAY{label,[(#TITRE|textebrut)],value,[(#TITRE|textebrut)],id,#ID_VITRINE})]})]})]
</BOUCLE_s>
[(#GET{resultats}|json_encode)]
#FILTRE{trim}

A noter :

  • Pour fonctionner sélecteur générique utilise les url réécrites pour l’accès a l’API, vous devez donc avoir mis en place un .htaccess à la racine de votre site, ou à la racine de votre mutualisation. Comme expliqué dans la doc du plugin :

    Important : Le .htaccess du site doit être activé, car l’appel des données se fait via le url réécrite en /selecteur.api.

    En résumé : si votre serveur de développement n’est pas correctement configuré : commencez par là.

  • Pour tester le fonctionnement et débuguer, l’utilisation de Firebug sera appréciée : l’onglet console permet de voir si une requête est bien envoyée (GET) à chaque saisie, et un clic sur la requête permet de voir l’objet JSON retourné et ce qu’il contient (404 par exemple, si le .htaccess est inopérant).
  • Le format JSON, comme le YAML, est très sensible aux espaces qui trainent, d’où le #FILTRE{trim} dans le code exemple. En cas de mauvais fonctionnement, vérifiez bien les données retournées.

Discussion

Aucune discussion

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