Rendre une saisie analysable par Formidable

Dans la présente documentation, toute valeur entre chevrons devra être remplacée par une valeur réelle.

Par exemple si j’écris <nom_de_la_saisie>.html et que votre saisie s’appelle toto, alors vous devrez écrire toto.html (sans les chevrons donc).

Principe général

Il faut créer un squelette <nom_de_la_saisie>.html dans le dossier saisies-analyses de votre plugin.

Ce squelette reçoit en environnement plusieurs informations :

• l’ensemble des options de la saisie directement à la racine ;
• sous _saisie, la description intégrale de la saisie ;
• sous valeurs, l’ensemble des réponses au formulaire pour le champ concernée, sous forme de tableau ;
• sous reponses_total le nombre total de réponse.

Charge ensuite au squelette d’analyser ses informations pour produire les données statistiques.

Celles-ci doivent être renvoyées sous forme de lignes de tableaux html contenant chacune deux cellules.

• l’élément tr porte la classe “tr_liste” ;
• le premier td indique la valeur statistiques (exemple “Choix numéro 1”) et porte la classe choix ;
• le second td indique l’effectif associé à cette valeur (exemple “3” si trois réponses portent le “Choix numéro 1”) et porte la classe stat.

Exemple

Pour la saisie radio, livrée avec le plugin saisies, formidable contient un fichier saisies-analyses/radio.html comportant les lignes suivantes.

#SET{stats,#ARRAY}
<BOUCLE_reponses(DATA){source tableau, #ENV{valeurs}}>
	[(#VALEUR|oui)
		#SET_MERGE{stats, #ARRAY{choix-#VALEUR, #GET{stats}|table_valeur{choix-#VALEUR}|sinon{0}|plus{1}}}
	]
</BOUCLE_reponses>

[(#REM) data peut être une chaine qu'on sait décomposer ]
#SET{data, #ENV*{data,#ENV*{datas}}}
#SET{data, #GET{data}|saisies_chaine2tableau|saisies_aplatir_tableau}
<BOUCLE_data(DATA){source tableau, #GET{data}}>
[(#SET{nb,[(#GET{stats}|table_valeur{choix-#CLE}|sinon{0})]})]
<tr class="tr_liste">
	<td class="choix">#VALEUR</td>
	<td class="stat"[ title="(#GET{nb}|titre_nb_reponses|attribut_html)"]>#GET{nb}</td>
</tr>
</BOUCLE_data>

#SET{diff, #ENV{reponses_total}|moins{#ENV{valeurs}|count}}
[(#GET{diff}|>{0}|oui)
<tr class="tr_liste">
	<td class="choix"><:saisies:vue_sans_reponse:></td>
	<td class="stat"[ title="(#GET{diff}|titre_nb_reponses|attribut_html)"]>#GET{diff}</td>
</tr>
]

Explication :

• la boucle reponses analyse #ENV{valeurs} d’un point de vue statistiques, et calcul les effectifs, stockés dans un tableau SPIP/PHP (#ARRAY) ;
• la boucle data passe en revue tous les choix possible de la saisie, et affiche les effectifs :
  • #VALEUR correspond à la valeur humaine ;
  • #GET{nb} est rempli avec l’effectif calculé plus haut dans _reponses (ou à défaut 0).
• les dernières lignes calculent l’effectif des réponses aux formulaires ne contenant pas de réponse pour le champ précis.

Mutualiser

Tout cela est un peu fastidieux. Or dans 99% des cas, l’analyse statistique que l’on veut faire se limite à associer des effectifs avec des valeurs.

Dit autrement : la plupart du temps, notre saisie personnalisée est une forme avancée d’une saisie de base. On peut donc utiliser intelligemment des <INCLURE> pour déléguer le calcul à notre saisie de base, en se contentant de passer simplement un tableau data propre à notre saisie personnalisée.

Prenons l’exemple de la saisie liste_diffusion du plugin Liste de diffusion. Fondamentalement, il s’agit de proposer en radio ou checkbox ou select un choix entre plusieurs listes de diffusion.

On a donc un fichier saisies/liste_diffusion.html contenant les lignes suivantes (j’ai supprimé les commentaires de doc au début).

[(#REM) Normaliser les valeurs et récupérer les listes ]

#SET{options,#ARRAY{
	status, #ENV{statut,open},
	id,     #ENV{identifiant}
}}
#SET{data,#ARRAY}
[(#ENV{autoriser_aucune}|oui)
	[(#SET{data,#ARRAY{saisie_liste_diffusion_autoriser_aucune_veut_pas,<:mailsubscriber:aucune_liste:>}})]
]
<BOUCLE_data(DATA){source table, #GET{options}|mailsubscribers_listes}>
#SET{data, #GET{data}|array_merge{#ARRAY{#ID,#ENV{titre_prive_uniquement}|?{#TITRE,#TITRE_PUBLIC}|sinon{#TITRE}}}}
</BOUCLE_data>

#SET{defaut,#ENV{defaut}|saisies_chaine2tableau}
[(#ENV{type_choix}|!={checkbox}|oui)
	#SET{defaut,#GET{defaut}|implode{','}}
]
[(#REM) On réutilise la saisie checkbox, sauf si on demande un autre type
Si on passe un paramètre dossier, il peut servir (remappage de saisies-analyses notamment)
]
<INCLURE{fond=#ENV{dossier,saisies}/#ENV{type_choix,checkbox}, data=#GET{data}, env, defaut=#GET{defaut}} />

Ce squelette :

• remplit un tableau( #SET{data}) avec l’ensemble des listes paramétrées lors de la configuration de la saisie (la boucle data et ce qui précède) ;
• ajuste la valeur par défaut dans le cas où l’on veut avoir des cases à cocher plutôt que des boutons radios ;
• fait une inclusion en recherchant dans le dossier saisies ou bien saisies-vues ou bien saisies-analyses selon la valeur passée à dossier dans le #ENV ;
• cette inclusion correspond au type de choix proposé à l’internaute (#ENV{type_choix}), c’est à dire, à l’heure actuelle : checkbox/radio/selection ;
• lui passe comme paramètre data le tableau calculé plus haut, passe les autres éléments d’environnement et la nouvelle version de defaut.

Autrement dit centralise le calcul des data et renvoie, en fonction de ce qui a été passé en paramètre, vers l’un des squelettes suivant :

• saisies/radio
• saisies/checkbox
• saisies/selection
• saisies-vues/radio
• saisies-vues/checkbox
• saisies-vues/selection
• saisies-analyses/radio
• saisies-analyses/checkbox
• saisies-analyses/selection

Si bien que saisies-analyses/liste_diffusion.html se limite à une ligne :

<INCLURE{fond=saisies/listes_diffusion, env, dossier=saisies-analyses} />

Ainsi, tout le calcul des statistiques est delegué aux outils livrés avec Formidable.