Boussole v2, usages avancés

Créer un serveur de boussoles

En premier lieu il faut installer le plugin Boussole sur le site destiné à devenir le site serveur. Par défaut, le plugin Boussole est toujours activé en mode client uniquement car il est assez rare d’avoir besoin du mode serveur : il faut donc activer le mode serveur.

Pour l’activer, il suffit de se rendre dans la page de configuration du plugin Boussole et en utilisant le formulaire ci-dessous, de cliquer sur « oui » et de saisir l’identifiant du serveur.

Il est possible de donner n’importe quel nom au serveur à l’exception de « spip » qui est réservé au serveur boussole.spip.net.

Le serveur étant maintenant prêt à fonctionner il suffit de lui faire héberger une ou plusieurs boussoles qu’il servira sur demande des sites client. Pour ce faire, il faut suivre les instructions des chapitres Créer une Boussole personnelle avec un plugin ou Créer une Boussole personnelle sans utiliser un plugin.

Utiliser un serveur personnel sur un site client

En premier lieu il faut installer le plugin Boussole sur le site client. Par défaut, le plugin Boussole déclare le serveur « spip » - boussole.spip.net - comme disponible pour les sites clients qui veulent afficher la Galaxie SPIP (voir la liste des serveurs accessibles dans l’illustration ci-dessous).

Si un site client veux utiliser un autre serveur, il doit le déclarer explicitement, en se rendant sur la page de gestion de la fonction client et en saisissant l’url du serveur dans le formulaire prévu à cet effet.

Attention, le serveur choisi doit être activé et doit héberger au moins une boussole sinon la déclaration ne sera pas prise en compte.

En outre, à partir de la liste des serveurs accessibles il est possible de retirer l’accès à un serveur déclaré à l’exception du serveur « spip ».

Créer une boussole personnelle avec un plugin

Une boussole est définie par :

• un fichier de description XML ;
• une liste de logos, un pour chaque site et un pour la boussole elle-même,
• un item de langue pour chaque nom, slogan et descriptif des sites, groupes et boussoles.

Pour créer une boussole personnelle en utilisant un plugin il faut donc déjà créer les éléments précédents au sein de ce plugin en suivant les instructions ci-après.

Le fichier de description XML

Le fichier de description XML de la boussole décrit :

• son alias et l’url du site de démonstration de la boussole si il existe (comme boussole.spip.net pour la Galaxie SPIP) ;
• la structure en groupes de sites, sachant que dans cette version le nombre et les identifiants des groupes sont libres ;
• la liste des sites contenus dans chaque groupe, un site étant défini par son alias, son activité et son url.

Ce fichier XML se nomme obligatoirement boussole-${alias_de_la_boussole}.xml et se positionne à la racine du plugin. Ce fichier doit être valide conformément à la DTD qui est définie dans le plugin Boussole.

Un exemple est fourni ci-dessous pour une boussole d’alias « farfelue », fichier boussole-farfelue.xml :

<boussole alias="farfelue" demo="http://mon_url_de_demo/">
	<!-- Premier groupe -->
	<groupe type="g1">
		<site alias="s1" src="http://url_site_1/" actif="oui" />
		<site alias="s2" src="http://url_site_2/" actif="oui" />
		<site alias="s3" src="http://url_site_3/" actif="oui" />
	</groupe>

	<!-- Deuxième groupe -->
	<groupe type="g2">
		<site alias="s4" src="http://url_site_4/" actif="oui" />
		<site alias="s5" src="http://url_site_5/" actif="non" />
	</groupe>
</boussole>

Les logos

Un logo est un fichier image au format PNG. Il est possible de fournir un logo pour chaque site de la boussole et pour la boussole elle-même. Les groupes n’ont pas de logo.

Les fichiers logo sont installés dans le répertoire images/boussole/ et se nomment :

• boussole-${alias_de_la_boussole}.png, pour la boussole,
• site-${alias_de_la_boussole}-${alias_du_site}.png, pour un site.

Il n’y a pas de taille prescrite pour les logos, néanmoins 64px est une taille qui permettra un affichage harmonieux dans tous les modèles fournis. En outre, il est recommandé de prévoir des logos carrés et tous de même taille.

Pour continuer avec l’exemple de la boussole d’alias « farfelue », pour utiliser un logo pour la boussole et ses sites il faudrait déposer dans le répertoire images/boussole/ les fichiers suivants :

• boussole-farfelue.png
• site-farfelue-s1.png
• site-farfelue-s2.png
• site-farfelue-s3.png
• site-farfelue-s4.png
• site-farfelue-s5.png

Les noms, slogans et descriptifs

Les noms, slogans et descriptifs des éléments d’une boussole sont construits de la façon suivante :

• <nom|slogan|descriptif>_boussole_<alias_de_la_boussole>, pour le nom, le slogan ou le descriptif d’une boussole,
• <nom|slogan|descriptif>_groupe_<alias_de_la_boussole>_<alias_du_groupe>, pour le nom, le slogan ou le descriptif d’un groupe,
• <nom|slogan|descriptif>_site_<alias_de_la_boussole>_<alias du site>, pour le nom, le slogan ou le descriptif d’un site.

Ces items de langue doivent être définis dans un fichier PHP déposé naturellement dans le répertoire lang/ et dont le nom est obligatoirement boussole-${alias_de_la_boussole}_${code_de_langue}.png.

Toujours pour l’exemple de la boussole « farfelue », il est nécessaire de déposer le fichier boussole-farfelue_fr.php dans le répertoire lang/ et d’y insérer les items de langue comme suit :

$GLOBALS[$GLOBALS['idx_lang']] = array(
	// D
	'descriptif_boussole_farfelue' => 'La boussole Farfelue regroupe l’ensemble des sites farfelus réalisés avec SPIP.',
	'descriptif_site_farfelue_s1' => 'descriptif s1...',
	'descriptif_site_farfelue_s2' => 'descriptif s2...',
	.../...
	// N
	'nom_boussole_farfelue' => 'Boussole Farfelue',
	'nom_groupe_farfelue_g1' => 'groupe 1',
	'nom_site_farfelue_s1' => 'nom s1',
	'nom_site_farfelue_s2' => 'nom s2',
	.../...
	// S
	'slogan_boussole_farfelue' => 'Visitez nos sites farfelus',
	'slogan_groupe_farfelue_g1' => 'slogan g1',
	'slogan_site_farfelue_s1' => 'slogan s1',
	'slogan_site_farfelue_s2' => 'slogan s2',
	.../...
);

Terminer le plugin

A ce stade la boussole est définie mais il reste encore deux fichiers à créer pour terminer le plugin :

• un fichier pipeline permettant de déclarer la boussole au serveur l’hébergeant,
• et le fichier paquet.xml de description du plugin.

En effet, le plugin de votre boussole personnelle doit utiliser le pipeline nommé declarer_boussoles pour faire connaître la boussole au serveur qui l’hébergera.

Il faut donc créer un fichier PHP nommé par exemple ${prefixe_du_plugin}_pipelines.php à la racine de votre plugin et coder une fonction ${prefixe_du_plugin}_declarer_boussoles() dans laquelle l’index du flux sortant correspond à l’alias de la boussole et la valeur à un tableau associatif composé uniquement du préfixe du plugin.

Dans la continuité de l’exemple de la boussole « farfelue » par le plugin de préfixe « boufarf », le contenu du fichier boufarf_pipelines.php est le suivant :

function bouspip_declarer_boussoles($flux) {
	$flux['farfelue'] = array('prefixe' => 'boufarf');
	return $flux;
}

Enfin comme tout plugin, il est nécessaire de créer un fichier paquet.xml à la racine du plugin. Ce paquet doit contenir les balises habituelles, seules deux informations sont notables :

• la version du plugin, qui sera utilisée pour définir la version de la boussole elle-même ;
• la déclaration du pipeline declarer_boussoles et du fichier PHP associé.

Il est aussi possible de traduire les nom, slogan et description du plugin dans un fichier de langue nommé paquet-${prefixe_du_plugin}_${code_de_langue}.php.

Créer une boussole personnelle sans utiliser un plugin

Il est aussi possible de créer une boussole personnelle sans pour autant utiliser un plugin qui peut parfois rebuter certains spipeurs. Dans ce cas, il faudra installer les fichiers adéquats dans le répertoire de personnalisation d’un site, à savoir, squelettes/.

Une telle boussole est composée :

• d’un fichier XML de description contenant aussi les traductions des noms, slogans et descriptifs ;
• et de logos.

Le fichier de description XML

Le fichier XML contient les mêmes informations de base que celui des boussoles utilisant un plugin et les informations supplémentaires suivantes :

• la version de la boussole, représentée par l’attribut « version » de la balise <boussole> ;
• le nom, le slogan et le descriptif de la boussole, des groupes (uniquement le nom) et des sites sous la forme de balises <multi>.

Ce fichier XML se nomme obligatoirement boussole_traduite-${alias_de_la_boussole}.xml et se positionne à la racine du répertoire squelettes/.

Un exemple de fichier XML issu de la boussole des sites Sarka-SPIP :

Les logos

Les logos de ce type de boussole suivent exactement les mêmes principes que ceux des boussoles utilisant un plugin. Ils doivent être installés dans le répertoire squelettes/images/boussole/.

Déclarer la boussole

Une fois la boussole installée dans le répertoire squelettes/ du site, étant donné qu’il n’est pas possible d’activer le mécanisme de pipeline pour déclarer la boussole au serveur il est nécessaire de la déclarer manuellement. Il faut donc se rendre dans la page de gestion de la fonction serveur et utiliser le formulaire de déclaration en saisissant uniquement l’alias de la boussole comme illustré ci-dessous.

La boussole déclarée sera insérée dans la liste des boussoles manuelles hébergées par le serveur.

Administrer les caches des boussoles hébergées par un site serveur

Afin de fournir efficacement les informations sur les boussoles qu’il héberge, le serveur met en cache ces boussoles. Le cache d’une boussole est un fichier XML, issu du fichier de description d’une boussole et complété par les traductions des noms, slogans et descriptifs (balises <multi>) et par les liens vers les logos.

C’est ce fichier qui est fourni au client sur demande.

Le serveur crée aussi un cache de la liste des boussoles qu’il héberge afin de renvoyer cette information au client quand celui-ci veut afficher la liste des boussoles disponibles (formulaire d’ajout).

La génération de ces fichiers cache se fait périodiquement au travers d’une tâche CRON journalière. Néanmoins, il est possible de piloter manuellement la génération via l’interface privée, proposée uniquement lorsque le mode serveur est actif :

La page d’administration propose la liste des caches, leur date d’actualisation, leur version, leur description ainsi que l’origine de la boussole (plugin ou non). Il est possible de télécharger les caches et aussi de lancer leur actualisation en utilisant le bouton « Actualiser les caches », ce qui peut être utile quand une boussole vient d’être mise à jour et que l’on veut visualiser les modifications immédiatement sans attendre le CRON.

Administrer les boussoles installées sur un site client

Le plugin Boussole peut fonctionner sans administration sur les sites client. La Boussole SPIP est chargée automatiquement et une tâche journalière permet d’acquérir les informations de la boussole SPIP voire des autres boussoles installées.

Néanmoins, il est toujours possible de se rendre dans la page d’administration des boussoles et, soit d’actualiser les boussoles installées en utilisant le bouton « Actualiser les boussoles », soit d’en ajouter via le formulaire d’ajout.

Résumé des pages d’administration du plugin

Synchroniser les données des sites de la boussole

Quand un site référencé appartient à une boussole comme « spip.net » avec la Boussole SPIP, un encart est inclus dans la page du site qui indique cette appartenance :

Un bouton « Synchroniser les données » permet de mettre à jour les données du site référencé avec les informations contenues dans la boussole pour ce même site. Les données textuelles sont chargées dans la langue du site.

Il est possible de réitérer cette opération à tout moment pour intégrer les modifications de la boussole (en particulier, les traductions).

Importer une boussole

Quand une boussole est installée, il est possible d’importer l’ensemble de ses sites comme sites référencés. Dans la page d’accueil des sites, un bouton « Importer les sites d’une boussole » permet de lancer l’opération.

Les données textuelles sont mise à jour dans la langue du site.