On trouvera ici
- des compléments de documentation
- des exemples de contrôleurs et vues
- Un exemple d’utilisation du datepicker
Utilisation sur des objets non déclarés
Les crayons peuvent être utilisés, dans une boucle sur une table non déclarée à SPIP.
C’est transparent et il n’y a rien à coder au moins lorsque la table a un nom habituel pour SPIP avec un s à la fin du nom de la table. (Il est aussi conseillé en général, mais non nécessaire pour les crayons, que le nom de la clé primaire soit composé de ’id_’ suivi du nom de la table au singulier.)
Fonctions personnalisées de mise à jour
Dans des cas particuliers, il est possible de définir une fonction revision_typobjet ou typobjet_revision pour gérer l’enregistrement des valeurs. Cette fonction reçoit 3 arguments :
- $id : l’identifiant de l’enregistrement à modifier (valeur de la clé primaire)
- $colval : tableau de couples (champ, nouvelle valeur)
- $type : nom de la table, sans le s
Exemple :
function revision_spip_theme($id, $colval, $type) {
sql_updateq($type.'s', $colval, "id_theme=".intval($id));
}Edition par un input ligne ou par un textarea ?
La doc indique que “si un texte crayonnable est un champ MySQL MEDIUMTEXT ou plus long, les crayons affichent un TEXTAREA, et sinon, un INPUT.” mais en fait le code teste AUSSI si il y a des fins de ligne dans la valeur du champ, auquel cas c’est toujours un TEXTAREA.
C’est le code de _plugins_/crayons/action/crayons_html.php qui fait ça et qu’il est possible de surcharger localement pour modifier ce comportement, au niveau de la ligne 97.
Par exemple on peut simplement ajouter la condition suivante au test :
OR (strlen ($valeur[$champ]) > 30)
ça donnerait donc le diff suivant :
@@ -94,7 +94,8 @@
// si la valeur fait plusieurs lignes on doit mettre un textarea
+ // idem si la valeur fait plus de 30 caractères
- // derogation specifique pour descriptif_site de spip_metas
+ // et derogation specifique pour descriptif_site de spip_metas
if (
preg_match(",[\n\r],", $valeur[$champ])
OR (($champ == 'valeur') && ($id == 'descriptif_site'))
+ OR (strlen ($valeur[$champ]) > 30)
OR
// on regarde le type tel que defini dans serial
La partie suivante indique comment spécifier la saisie au moyen de l’API rayons_determine_input_mode_type_ des crayons.
API crayons_determine_input_mode_type pour modifier les saisies devant être utilisées pour chaque champs
Il est possible de modifier le choix que font les crayons concernant le type de saisie pour un champ d’une table.
Pour spécifier quelle saisie employer pour un champ de la table ’spip_trucs’, il faut définir une fonction crayons_determine_input_mode_type_truc_dist (ou crayons_determine_input_mode_type_spip_truc_dist si la table n’est pas déclarée à SPIP).
Dans l’exemple suivant, seul l’argument $champ est testé et seul la saisie du champ ’historique’ est modifiée. Mais il est également possible de tester le $sqltype (déclaration SQL du champ) ou le $type, qui n’est en fait utile que lorsque c’est une fonction plus générique qui est définie.
/**
* @param string $type
* @param string $champ
* @param array $sqltype
* @return string
* Définir quels types de saisie utiliser pour les champs de la table spip_trucs
* lorsque le type choisi par défaut par les crayons ne convient pas.
* La fonction renvoie '' lorsque la saisie par défaut convient bien.
* Ici on change seulement la saisie du champ `historique`
* pour que ça soit une saisie de type `texte` (= `textarea`) au lieu d'un `input text`
*/
function crayons_determine_input_mode_type_truc_dist(string $type, string $champ, array $sqltype) : string {
if ($champ === 'historique') {
return 'texte';
}
return '';
}
Nom servant d’index dans l’environnement reçu par un contrôleur
Le contrôleur reçoit une variable d’environnement avec la valeur de l’index de l’enregistrement édité. Le nom de cette variable est toujours de la forme ’id_table’ lorsque la table s’appelle ’TABLE’ ou ’TABLES’. C’est donc bien l’index de la table si la table suit les conventions de nommage élémentaires de SPIP.
Mais si la table ne suit pas les conventions de nommage de SPIP, l’index reçu n’est pas le bon et il faut donc définir un contrôleur sur mesure. Exemple : si la table est "PLOUF’, l’index reçu a pour nom ’id_plouf’ même si le vrai champ index de la table PLOUF est “mon_idploc_rahlala”. Dans ce dernier cas, il faudra faire le lien dans la boucle avec :
<BOUCLE(PLOUF){mon_idploc_rahlala=#ENV{id_plouf}}>
Exemples d’un contrôleur unique servant à saisir plusieurs champs constitutifs d’une adresse
Ce squelette implémente un contrôleur pour le crayon detailsdeladresse qui permet de modifier les champs des adresses enregistrées dans la table adresses.
Pour activer ce contrôleur
- Il faut le mettre dans le sous-dossier controleurs du dossier squelette.
- Dans le squelette qui affiche l’adresse, il faut encadrer le code qui affiche l’adresse par les balises #EDIT appelant le contrôleur.
Par exemple
<span class="#EDIT{detailsdeladresse}">
#NOM #PRENOM,
#ADRESSE,
#CP #VILLE
#TEL
#EMAIL #SITE
</span>
Ce contrôleur est implémenté par un simple fichier HTML controleurs/adresse_detailsdeladresse.html. Il est donc basique et ne réalise pas de vérifications. Voici le code :
#CACHE{0}
<BOUCLE_adresse(ADRESSES){id_adresse=#ENV{id_adresse}}>
<fieldset style="width:#ENV{largeur}px;#ENV{style}">
<legend>Détails de l'adresse</legend>
<label>Nom</label>
<input class="crayon-active" name="#ENV{name_nom}" value="[(#NOM**|entites_html)]" />
<label>Prénom</label>
<input class="crayon-active" name="#ENV{name_prenom}" value="[(#PRENOM**|entites_html)]" />
<label>Adresse</label>
<textarea class="crayon-active" name="#ENV{name_adresse}" style="height:#ENV{hauteur}|mul{2}px;">
[(#ADRESSE**|entites_html)]</textarea>
<label>CP</label>
<input class="crayon-active" name="#ENV{name_cp}" value="[(#CP**|entites_html)]" />
<label>Ville</label>
<input class="crayon-active" name="#ENV{name_ville}" value="[(#VILLE**|entites_html)]" />
<label>Tel</label>
<input class="crayon-active" name="#ENV{name_tel}" value="[(#TEL**|entites_html)]" />
<label>Email</label>
<input class="crayon-active" name="#ENV{name_email}" value="[(#EMAIL**|entites_html)]" />
<label>Site</label>
<input class="crayon-active" name="#ENV{name_site}" value="[(#SITE**|entites_html)]" />
</fieldset>
</BOUCLE_adresse>Utiliser un datepicker dans un controleur
1. dans le controleur
#CACHE{0}
<BOUCLE_toto(MA_TABLE){id_ma_table}>
<input class="crayon-active date" type="text" name="#ENV{name_madate}" value="[(#MADATE|affdate{d/m/Y})]">
</BOUCLE_toto>
#INCLURE{fond=formulaires/dateur/inc-dateur}2. dans le pipeline : crayons_verifier
function prefix_crayons_verifier($flux){
$date = $flux['args']['content']['madate'];
list($date,$heures) = explode(' ' , $date);
list($jour, $mois, $annee) = explode('/',$date);
$heures = ( $heures ) ? $heures : "00:00:00";
$date = intval($annee) .'-'. $mois .'-'. $jour. ' ' . $heures;
$flux['data']['normaliser']['madate'] = $date;
return $flux;
}ou avec le plugin verifier :
function prefix_crayons_verifier($flux){
$date = $flux['args']['content']['madate'];
$verifier = charger_fonction('verifier', 'inc/');
$verifier($date, 'date', ['normaliser' => 'datetime'], $date);
$flux['data']['normaliser']['madate'] = $date;
return $flux;
}3. La vue
#CACHE{0}
<BOUCLE_toto(MA_TABLE){id_ma_table}>
[(#MADATE|affdate{d/m/Y})]
</BOUCLE_toto>Verifier la saisie sur un champ crayonnable
Crayons propose un pipeline permettant de vérifier la saisie d’un champ.
Par exemple, pour vérifier qu’une référence d’un produit n’existe pas déjà:
function produits_crayons_verifier($flux){
if ( $flux['args']['type'] == 'produit' && $flux['args']['modele'] == 'reference' ) {
$str = $flux['args']['content']['reference'];
$id_produit = $flux['args']['id_objet'];
if ( sql_getfetsel('reference','spip_produits',"reference='$str' AND id_produit!=intval($id_produit)") )
$flux['data']['erreurs']['reference'] = _T('produits:reference_existante');
}
// Voir dans les logs ce qui se passe...
// spip_log($flux, _LOG_DEBUG);
return $flux;
} Il faudrait certainement utiliser sql_quote pour échapper l’argument utilisant $str
Nouveau : Crayons sur les métas
Depuis la version 3.3.0 (via le commit ba7c4d8), on peut définir des contrôleurs et des vues personnalisés pour les crayons sur des métas.
Le crayon de la meta foo/bar, par exemple, est activé dans le squelette via #EDIT{meta-foo/bar}
- On peut alors définir un controleurs/meta_foo_bar.html ou controleurs/meta_foo.html ou controleurs/meta.html (au passage pour le cas non meta on ajoute le controleurs/type pour être cohérent avec les vues).
- Le controleur devra envoyer un POST avec le name #ENV{name_valeur} car les crayons meta attendent toujours un champ valeur
- Pour la vue, idem on peut définir une vues/meta_foo_bar.html ou vues/meta_foo.html ou bien vues/meta.html