FiltreAgendaMemo2

Tutorial

Attention : dans tout ce paragraphe, le terme date se rapporte à une date qui comprend l’heure

Pour réaliser un agenda simple avec SPIP il vous faut :
-  1. des évènements : n’importe quel article ou brève SPIP fera l’affaire. Nous prendrons donc des ARTICLES dans cet exemple, mais n’importe quel objet SPIP qui contient une DATE ferait l’affaire. Vous pouvez bien sur choisir de ne voir que les articles d’une rubrique, ou seulement les articles correspondant à un mot-clef… A vous de faire des boucles autour de la boucle qui fait l’agenda. On utilise la date de l’article comme fin de l’événement et la date de redaction antérieure comme date de début de l’événement.

-  2. une boucle sur ces évènements.

Pour réaliser cette boucle, on va utiliser le critère agenda2. Il suffit de fournir à ce critère une date, sous la forme d’une année (en 4 chiffres comme 1987) d’un mois (en deux chiffres comme 02) et d’un jour (en deux chiffres comme 09) et de lui demander de sélectionner les évènements (ici, les ARTICLES) sur le mois, le jour ou la semaine qui vous intéresse. Vous pouvez récupérer ces chiffres depuis l’environnement (url d’appel) ou autrement.
En tête de critère agenda2, il vous faut mettre les dates de début et de fin de vos évènement. J’ai choisi de les ranger dans date_redac (date de début) et dans date (date de fin).

Cela s’utilise comme suit (voir les fichiers jour.html, semaine.html, mois.html dans le dossier « dist » de SPIP) :

<BOUCLE_mois(ARTICLES) {agenda2 date_redac, date, mois,#ENV{annee}, #ENV{mois}}><!--  une boucle sur un mois -->
...
</BOUCLE_mois>

<BOUCLE_jour(ARTICLES)  {agenda2 date_redac, date, jour,#ENV{annee}, #ENV{mois}, #ENV{jour}}> <!-- sur un jour -->
....
</BOUCLE_jour>

<BOUCLE_semaine(ARTICLES) {agenda2 date_redac, date, semaine, #ENV{annee}, #ENV{mois}, #ENV{jour}}> <!-- sur la semaine du jour désigné -->
...
</BOUCLE_semaine>

La boucle étant faite, le critère agenda2 va donner tous les évènements correspondants à la période donnée. Ce critère agenda2 devrait (sauf bug...) gérer tous les cas de « fourchette ». Donc si un événement commence avant le début de votre période, mais finit pendant ou après votre période, il sera repéré par agenda2 (Dans le cas contraire, c’est un bug, signalez-le moi !).

Nous allons alors ranger ces évènements dans un calendrier, ce qui sera fait par le filtre agenda_memo2. A noter que ce filtre, dans la boucle, n’écrira rien à l’écran : il se borne à ranger les évènements dans un tableau interne a SPIP.

On applique le filtre agenda_memo2 sur une balise de type DATE qui indique la date de début avec 5 arguments suplémentaires :

1. une DATE de fin
2. un descriptif (qui s’affichera lorsque la souris passera sur l’événement du calendrier),
3. un titre (qui sera le texte de l’événement dans le calendrier),
4. une URL (celle sur laquelle sera envoyé l’utilisateur quand il cliquera sur le titre dans le calendrier),
5. un nom de CSS.

Le nom de CSS permet de fixer l’aspect du calendrier, et aussi d’avoir plusieurs calendriers par page : chaque nom de CSS collecte les évènements dans un tableau (donc un calendrier) à part, que l’on peut rappeler ensuite. La feuille calendrier.css fournit 28 styles différents de calendriers, qu’il est loisible de modifier ou d’étendre.

Dans notre exemple cela donne, pour un jour :

<BOUCLE_jour(ARTICLES)  {agenda2 date_redac, date, jour,#ENV{annee}, #ENV{mois}, #ENV{jour}}> <!-- sur un jour -->
(#DATE|agenda_memo2{#DATE_REDAC,#DESCRIPTIF, #TITRE, #URL_ARTICLE, 'calendrier-couleur1'})
</BOUCLE_jour>

comme la boucle est une boucle d’articles, ce sont les descriptifs, titre et URL de l’article qui sont passés au filtre agenda_memo. Vous pouvez passer n’importe quelle valeur (si vous décidez, par exemple de faire un agenda de brèves ou de rubriques…)

Une fois la boucle terminée, rien n’est à l’écran, mais le calendrier est prêt.

-  3. On peut maintenant afficher le calendrier à l’écran, ce qui se fait en appelant le filtre agenda_affiche2.
Cet appel permet de restituer les évènements entrés à l’étape 2, lors de l’appel dans la boucle. On applique le filtre |agenda_affiche2 sur une balise indiquant un nombre supposé être le nombre d’événements trouvés par le critère agenda(#TOTAL_BOUCLE en générale) et en lui passant 3 paramètres :

1. un texte brut (qui s’affiche s’il n’y a rien dans le calendrier)
2. un type de calendrier à dessiner (jour, mois ou semaine). Des types de calendrier peuvent être ajoutés par les programmeurs php.
3. des noms de CSS déja passés à agenda_memo2 à l’étape précédente,

dans notre exemple cela donnera :

[(#TOTAL_BOUCLE| agenda_affiche2{'rien a dessiner', 'calendrier-couleur2', 'jour'})]

C’est cette instruction-là qui donnera à l’écran le calendrier souhaité.

-  4. la version complète du code (pour un jour).
Vous trouverez tout le code sur spip-contrib.

<BOUCLE_semaine(ARTICLES)
    {agenda2 DATE_REDAC,date, semaine, #ENV{annee}, #ENV{mois}, #ENV{jour}}>[
(#DATE| agenda_memo2{#DATE_REDAC,#DESCRIPTIF, #TITRE, #URL_ARTICLE, 'calendrier-couleur5'})
#TITRE
]</BOUCLE_semaine>
[(#TOTAL_BOUCLE|agenda_affiche2|{'rien','calendrier-couleur5', 'semaine'})]
</B_semaine>