[dev] Les données du Couteau Suisse

Voici comment offrir aux outils la possibilité de stocker des données précalculées afin d’augmenter la vitesse du traitement des pages lors de l’exécution du plugin.

Introduction

Chaque outil du Couteau Suisse peut stocker des données grâce au cadre offert par le plugin. Ce stockage est utile pour booster les performances et précompiler par exemple un tableau dont le résultat final sera utilisé plus tard lors de l’exécution. C’est notamment le moment d’interpréter la valeur d’une variable entrée par l’utilisateur — comme une liste de mots, un choix spécifique, etc. —, préparer des boutons pour la barre typo, préparer une aide ou un raccourci, etc.

Lire les données

Pour lire une donnée stockée par un outil au moment de l’exécution du site, la fonction à connaitre est :     cs_lire_data_outil($outil, $casier=false)

Chaque outil a la possibilité de stocker puis de lire un (par défaut) ou plusieurs «casiers». Si la variable $casier n’est pas renseignée, alors l’outil n’a besoin que d’un seul casier principal. Un casier est un peu comme une étiquette que l’on peut apposer (ou non) sur une donnée particulière que l’on désire séparer d’une autre.

Les outils utilisant ce mécanisme sont aujourd’hui :
Chatons, Smileys, Décoration, Filets de Séparation, Tout en couleurs, Corrections automatiques, Exposants typographiques, Jolis Coins, Lutte contre le SPAM.

Voici en guise d’exemple la fonction de remplacement utilisée par les Chatons. Notez qu’elle devient très simple et très rapide grâce au stockage en amont de toutes les données à rechercher puis à remplacer :

function cs_rempl_chatons($texte) {
	if (strpos($texte, ':')===false) return $texte;
	$chatons = cs_lire_data_outil('chatons');
	return str_replace($chatons[0], $chatons[1], $texte);
}

Dans l’exemple suivant, les raccourcis préalablement calculés et disponibles pour reconnaître les smileys sont listés dans cette fonction. Notez le casier spécifique ’racc’ qui est appelé ici :

// liste des nouveaux raccourcis ajoutes par l'outil
// si cette fonction n'existe pas, le plugin cherche alors  _T('couteauprive:un_outil:aide');
function smileys_raccourcis() {
	$racc = cs_lire_data_outil('smileys', 'racc');
	return _T('couteauprive:smileys:aide', 
		array('liste' => '<b>' . join('</b>, <b>', $racc) . '</b>')
	);
}

Stocker les données

Aucune fonction a proprement parler n’existe pour stocker des données à l’instar de la lecture, le mécanisme est un peu différent.

Pour qu’un outil puisse stocker des données, il faut qu’il possède une fonction monoutil_installe_dist() (notez le suffixe “_installe_dist” ajouté à l’id de l’outil en question) qui calcule puis renvoie les données à stocker. Le stockage des données se produit uniquement lors de l’installation de l’outil, c’est à dire lorsque l’une des conditions suivantes se produit :
-  La page d’admin du Couteau Suisse est affichée
-  Un ou plusieurs outils sont activés ou désactivés
-  Une valeur est changée manuellement dans la configuration d’un outil
-  L’URL de la page est affublée du paramêtre «cs=calcul»
-  Le fichier tmp/couteau-suisse/mes_options.php n’est pas trouvé

Notes :
-  Il est préférable que la fonction monoutil_installe_dist() soit présente dans le module outils/monoutil.php.
-  Le format retourné par cette fonction est obligatoirement un tableau de données.

Différents formats d’utilisation :

1. Un casier principal unique (la fonction d’installation renvoie un tableau sans nom) :

// Format utilisé pour un casier unique :
return array($mes_donnees);
 
// que l'on peut lire ainsi :
$mes_donnees = cs_lire_data_outil('monoutil');

2. Un casier principal (tableau sans nom) et un casier secondaire (tableau nommé casier_secondaire) :

// Format utilisé pour un casier principal et un casier secondaire nommé :
return array(
	$mes_donnees_principales, 
	'casier_secondaire' => $mes_donnees_secondaires,
);
 
// que l'on peut lire ainsi :
$mes_donnees_principales = cs_lire_data_outil('monoutil');
$mes_donnees_secondaires = cs_lire_data_outil('monoutil', 'casier_secondaire');

3. Deux casiers différents nommés casier1 et casier2 :

// Format utilisé pour deux casiers différents :
return array(
	'casier1' => $mes_donnees_1, 
	'casier2' => $mes_donnees_2,
);
 
// que l'on peut lire ainsi :
$mes_donnees_1 = cs_lire_data_outil('monoutil', 'casier1');
$mes_donnees_2 = cs_lire_data_outil('monoutil', 'casier2');

Surcharge de la fonction d’installation

La fonction d’installation d’un outil est surchargeable (toutes dernières versions du Couteau Suisse) : la fonction monoutil_installe(), si elle existe, devient prioritaire sur la fonction native monoutil_installe_dist().

Vous pouvez donc personnaliser l’installation des outils natifs fournis dans le plugin en remplaçant ou modifiant les données stockées. Bien que recommandé, l’appel à la fonction surchargée reste facultatif. Cette fonction de surcharge doit être visible au moment de l’installation de l’outil, le mieux étant de la placer dans /config/mes_options.php.

Exemple de complément à l’outil «Exposants Typographiques» où le symbole des degrés est remplacé par un petit «o» en exposant :

function typo_exposants_installe() {
         $data = typo_exposants_installe_dist();
         $data['fr'][0][] = '/°|&(?:#176|deg);/';
         $data['fr'][1][] = _TYPO_class . 'o</sup>';
         return $data;
 }

Exemple de mot ajouté à l’outil «Lutte contre le SPAM» de façon fixe et non modifiable par l’utilisateur :

 function spam_installe() {
         $data = spam_installe_dist();
         $data[0][0][] = 'averybadword';
         return $data;
 }

Exemple d’un smiley icon_kiss.gif ajouté au jeu déjà existant :

function smileys_installe() {
	$tab = smileys_installe_dist();
	compile_smiley($tab, ':-*', 'icon_kiss', 'gif');
	return $tab;
 }

Note : afin de connaître l’id des outils actuellement fournis avec le Couteau Suisse, rendez-vous sur cette page : [dev] Les autorisations du Couteau Suisse.

Où sont les données ?

Les données stockées par les outils actifs sont compilées par le plugin sous forme de différentes fonctions que vous trouverez dans le fichier tmp/couteau-suisse/mes_outils.php.

Le nom des fonctions est calculé ainsi :
-  ’cs_’ . $outil pour le casier principal
-  ’cs_’ . $outil . ’_’ . $casier pour un casier spécifique.

Le format des données renvoyées est propre à chaque outil, il n’y a pas de règle, à vous de lire le code pour comprendre la structure que vous cherchez à modifier. En cas de problème, le forum ci-dessous est fait pour vous ! N’hésitez pas à proposer vos trouvailles et solutions, elle profiterons à d’autres.

updated on 2 October 2019

Discussion

2 discussions

  • Bonjour Pat,

    Les quelques lames utilisées parmi d’autres :
    -Découper un texte en pages et/ou en onglets
    -Des blocs dépliables
    -Décorer ou colorer vos textes
    -etc

    En fait c’est quand on active le plugin couteau suisse, il reste bloqué sur une fonction exec
    dont extraits :
    “exec=charger_plugin&action=actionner arg=&hash=xxxx....
    redirect=http%3A%2F%2Fwww.monsite.fr%2Fecrire%2F%3Fexec%3Dadmin_plugin

    il semblerait que cela dysfonctionne avec l’administration des plugins dans mon spip3.54.4 sous Escal 3 :
    “/?exec=admin_plugin”

    Et cela s’est passé après plusieurs autres mises à jour d’autres plugins qui se sont bien déroulées. Avec le couteau suisse, c’est l’écran total blanc bloqué!

    Impossible de revenir dans l’administration de spip.}

    Et l’accès aau site public semble bloqué

    Seule solution trouvée à ce jour, enlever le plugin couteau suisse.

    Avez-vous une autre solution
    merci de votre aide.

    Reply to this message

  • 2

    Bonjour,

    Gros problèmes, depuis ce 23 sept 2012, après une mise à jour SPIP3.05
    et dans les plugins la mise à jour du couteau suisse 1.8.98.
    Cà coince, et n’affiche plus rien, semble bloqué!
    Quand je supprime le couteau suisse ,aucun problème.
    Sauf que les onglets et séparations de pages dans mes articles ne sont plus opérants.

    J’ai bien essayé , de remettre la version 1.8.78 du couteau suisse, mais impossible de faire fonctionner.

    Avez-vous une solution ?

    Merci

    Le Jaseur Boreal
    http://www.lettonie-francija.fr

    • Bonjour

      Tu utilises pas svp en spip 3 ?

    • Bonjour, je viens de tester le dernier SPIP et le dernier CS sans souci apparent. Quelles lames avais-tu activées ? quelles sont les pages bloquantes ?

    Reply to this message

Comment on this article

Who are you?
  • [Log in]

To show your avatar with your message, register it first on gravatar.com (free et painless) and don’t forget to indicate your Email addresse here.

Enter your comment here

This form accepts SPIP shortcuts {{bold}} {italic} -*list [text->url] <quote> <code> and HTML code <q> <del> <ins>. To create paragraphs, just leave empty lines.

Add a document

Follow the comments: RSS 2.0 | Atom