Un sommaire pour vos articles

Une fonctionnalité du Couteau Suisse qui repère les intertitres des textes de vos articles ou de vos rubriques, et permet même plusieurs niveaux, puis en fabrique automatiquement un sommaire.

Introduction

Les articles de votre site sont parfois un peu longs et vous vous êtes probablement déjà posé la question de savoir comment insérer un sommaire au début d’un texte — à l’instar de cette page — histoire d’en faciliter la lecture et la navigation...

Voici notre solution : utilisez simplement dans vos articles le raccourci SPIP des intertitres ({{{Mon intertitre}}}). Le plugin va ensuite ajouter automatiquement un cadre de navigation en tête d’article en réunissant les différents intertitres affublés d’un lien cliquable vers le paragraphe concerné. Ce cadre peut ressembler à ceci :

En ce qui concerne les intertitres, une petite icône permet de revenir au sommaire. Cette ancre peut ressemble à ceci :

Pour obtenir ce résultat, il suffit simplement de taper ce qui suit dans votre article :

               {{{Conclusion}}}
 
               Quelques mots, pas plus !

Ce système vous offre donc un facile va-et-vient entre les paragraphes du texte et le sommaire.

Installation

Cet outil est une fonctionnalité du plugin « Le Couteau Suisse » que vous pouvez trouver ici : Le Couteau Suisse.

Pour avoir accès au sommaire automatique, il vous faut donc avoir installé ce plugin en suivant la procédure normale d’installation des plugins SPIP.

Ensuite, veuillez activer l’outil « Sommaire en début d’article » en vous rendant sur la page d’administration du plugin en espace privé (Bouton Configuration, et onglet "Le Couteau Suisse").

Dépendances

Les styles CSS du sommaire et des différents liens sont insérés grâce à la balise #INSERT_HEAD qui doit absolumet être présente (en un seul exemplaire) dans le header de vos squelettes (entre les balises <head> et </head> des fichiers HTML). Si vous ne trouvez pas cette balise dans vos codes et que le sommaire n’apparait pas avec l’apparence voulue, alors l’outil « Balise #INSERT_HEAD » du Couteau Suisse permet d’insérer automatiquement cette balise sans manipulation de votre part.

Configuration

Par défaut, le sommaire ne retient que les intertitres de premier niveau [1] : balises HTML <h3> ou raccourcis SPIP {{{...}}}. Or, il est possible de prendre en compte des niveaux supplémentaires en renseignant le paramètre « Profondeur retenue ». Les balises <h4> ou <h5> pourront alors être insérées dans le sommaire. Si vous avez installé un plugin typographique afin d’éviter d’utiliser les balises HTML <hN> en dur, les intertitres de niveaux supérieurs peuvent se noter de différentes façons. Exemples : {2{...}2}, {{{**...}}}, {{{**...}}},etc.

Le Couteau Suisse a choisi de retenir nativement la syntaxe {{{**...}}} de mortimer. Ces nouveaux raccourcis (intertitres hiérarchisés, ou sous-titres) seront donc automatiquement traités, même en l’absence de plugin tiers :
-  Intertitre de niveau 1 : {{{Intertitre}}} ou {{{*Intertitre}}}
-  Intertitre de niveau 2 : {{{**Intertitre}}}
-  Intertitre de niveau 3 : {{{***Intertitre}}}
-  etc.

Exemple de sommaire ayant deux niveaux d’intertitres :

Par défaut, le sommaire est constitué des 30 premiers caractères de vos intertitres afin d’éviter tout débordement inesthétique de texte. Sur la page de configuration du plugin (Bouton Configuration, et onglet « Le Couteau Suisse »), vous pouvez modifier ce paramètre à votre guise. La fonction utilisée est simplement la fonction couper() de SPIP, qui ajoute des points de suite à la place du texte supprimé. Voici l’aperçu d’un sommaire où deux intertitres sont tronqués :

Vous pouvez également fixer le comportement du plugin concernant la création du sommaire :
-  Systématique pour chaque article. Cependant, une balise « [!sommaire] » placée n’importe où à l’intérieur du texte de l’article créera une exception afin de pouvoir bénéficier des intertitres sans qu’un sommaire ne soit créé dans un article en particulier. .
-  A l’inverse : uniquement pour les articles contenant la balise « 

 ».
Ces raccourcis, bien sûr, ne seront pas affichés à l’écran.

Changements d’aspect et surcharges

Pas de fond

Par défaut, le sommaire utilise une image de fond que vous pouvez voir ci-dessus. Un second aspect du sommaire est possible si vous insérez le raccourci « [!fond] » n’importe où dans le texte. Le sommaire aura donc un aspect similaire à cet exemple :

Les surcharges de fichiers

Techniquement, le plugin utilise :
-  un modèle SPIP : plugins/couteau_suisse/fonds/sommaire.html
-  une feuille de styles : plugins/couteau_suisse/outils/sommaire.css.html

Ces deux fichiers peuvent facilement être surchargés dans votre squelette en les recopiant dans :
-  mon_squelette/fonds/sommaire.html
-  mon_squelette/outils/sommaire.css.html

En étudiant les deux fichiers surchargeables cités ci-dessus, vous pourrez remarquer les différentes classes CSS. Il vous sera alors facile de paramétrer ces classes dans vos fichiers de squelette si par exemple vous souhaitez changer de couleur de fond, de marge ou de style de bordure...

Voici le code de sommaire.html :

<div class="cs_sommaire cs_sommaire_[(#ENV*{fond_css})]_fond" id="outil_sommaire">
  <div class="cs_sommaire_inner">
    <div class="cs_sommaire_titre_[(#ENV*{fond_css})]_fond">&nbsp; <:couteau:sommaire_titre:> &nbsp;</div>
    <ul>
      [(#ENV*{sommaire})]
    </ul>
  </div>
</div>

Si l’aspect du sommaire qui vous est proposé ici ne vous plait vraiment pas, alors faites une surcharge directement dans votre squelette en créant votre propre fichier « mon_squelette/fonds/sommaire.html ». Le sommaire d’origine sera donc ignoré, au profit de votre propre sommaire. Cette façon de faire peut également s’appliquer au fichier des styles.

Si l’envie vous venait de changer simplement le titre du sommaire, alors changez simplement la chaîne de titre de votre fichier mon_squelette/fonds/sommaire.html. Un exemple qui bénéficie de toutes les traductions de SPIP :

[(#REM) "Navigation rapide" et toutes ses traductions ]
<div class="cs_sommaire_titre"><:icone_brouteur:></div>

Le sommaire est aujourd’hui dé/repliable et par défaut, le visiteur trouve un sommaire déplié (visible en totalité). Pour obtenir un sommaire replié lorsque le visiteur découvre la page pour la première fois (seul le titre apparaît), il suffit de surcharger le fichier fonds/sommaire.html en ajoutant les deux classes suivantes :
-  cs_sommaire_replie sur <div class="cs_sommaire_titre_[(#ENV*{fond_css})]_fond">
-  cs_sommaire_invisible sur <ul>

Ce qui donne :

<div class="cs_sommaire cs_sommaire_[(#ENV*{fond_css})]_fond" id="outil_sommaire">
  <div class="cs_sommaire_inner">
    <div class="cs_sommaire_titre_[(#ENV*{fond_css})]_fond cs_sommaire_replie">&nbsp; <:couteau:sommaire_titre:> &nbsp;</div>
    <ul class="cs_sommaire_invisible">
      [(#ENV*{sommaire})]
    </ul>
  </div>
</div>

Attention, le sommaire sera systématiquement replié lorsque le visiteur arrive sur la page pour la première fois. Mais s’il quitte la page le sommaire déplié, alors un cookie posé sur sa machine permettra de déplier le sommaire s’il revient sur la page... Euh, suis-je clair ?

Les liens de retour au sommaire

Lors de la construction du sommaire, le plugin ajoute par défaut à chaque intertitre de la page, un lien de retour au sommaire qui permet au lecteur de revenir facilement en haut de la page. Vous avez maintenant la possibilité (version récente du Couteau Suisse) de modifier ce comportement en surchargeant la fonction sommaire_lien_retour_dist($self, $titre) que vous pouvez trouver dans le fichier outils/sommaire_fonction.php.

Pour cela, il vous faut placer une nouvelle fonction sommaire_lien_retour($self, $titre) dans votre fichier config/mes_options.php que le compilateur utilisera à la place de la précédente. Par exemple, si vous ne voulez pas des liens de retour au sommaire dans les intertitres, utilisez le code suivant :

function sommaire_lien_retour($self, $titre) { 
  return $titre;
}

A titre d’info, voici le code actuel de la fonction utilisée par défaut :

function sommaire_lien_retour_dist($self, $titre) {
  static $haut = NULL;
  if(!isset($haut)) 
    $haut = '<a title="'._T('couteau:sommaire_titre')
        .'" href="'.$self.'#outil_sommaire" class="sommaire_ancre">&nbsp;</a>';
  return $haut . $titre;
}

Le calcul des ancres

Lors de la construction du sommaire, le plugin calcule automatiquement les ancres de chaque intertitre par incrémentation : outil_sommaire_XX. Vous avez maintenant la possibilité (version récente du Couteau Suisse) de modifier ce comportement en surchargeant la fonction sommaire_id_ancre_dist($index, &$titre, $hn) que vous pouvez trouver dans le fichier outils/sommaire_fonction.php.

A l’instar des liens au paragraphe précédent, il vous faut pour cela placer une nouvelle fonction sommaire_id_ancre($index, &$titre, $hn) dans votre fichier config/mes_options.php que le compilateur utilisera à la place de la précédente.

Si vous souhaitez de belles ancres en approfondissant la compatibilité avec le format proposé ici par mortimer, configurez votre outil pour utiliser de « jolies ancres » dans le sommaire. Le calcul des ancres n’est alors plus surchargeable et le plugin utilisera la fonction suivante (compatible avec les intertitres en image) :

function sommaire_id_ancre_ex($index, &$titre, $hn) {
  // traiter le format {{{Mon titre<mon_ancre>}}} (ou alt='Mon titre&lt;mon_ancre&gt;')
  if(preg_match(',<(\w+)>$,', $titre, $r)
      || preg_match(',&lt;(\w+)&gt;(?=\'),', $titre, $r)) {
    $titre = str_replace($r[0], '', $titre);
    return $r[1];
  }
  $a = strtolower(translitteration(sommaire_nettoyer_titre($titre)));
  $a = trim(preg_replace(',[^a-z0-9_]+,', '_', $a), '_');
  return strlen($a)>2?$a:"sommaire_$index";
}

A titre d’info, voici le code actuel de la fonction utilisée par défaut :

function sommaire_id_ancre_dist($index, &$titre, $hn) {
  return 'outil_sommaire_' . $index;
}

Notez que la variable $titre (intertitre en cours) est passée en référence, ce qui permet de la modifier le cas échéant. $index est incrémenté à chaque appel de la fonction. $hn est le rang (le « N » tiré de la balise HTML <hN>) de l’intertitre en cours. Si vous activez l’outil « Intertitres en images » il est fort probable que $titre soit une balise image (<img ... />) et non un texte...

Les éléments du sommaire

Lors de la construction du sommaire, le plugin cherche pour chaque élément, une fonction sommaire_id_page($element, $page) permettant certaines personnalisations, notamment en cas de découpe en pages. Le paramètre $element est le lien cliquable mis en forme pour accéder au paragraphe correspondant, et le paramètre $page est le numéro de l’extrait découpé. Par défaut, le plugin ajoute ce numéro dans le libellé de chaque lien, par exemple : « Introduction, p1 » , « Conclusion, p2 ».

Pour changer ce comportement d’origine, et à l’instar des ancres au paragraphe précédent, il vous faut pour cela placer la fonction sommaire_id_page($element, $page) dans votre fichier config/mes_options.php que le compilateur utilisera à la place de la fonction native sommaire_id_page_dist.

Voici un exemple de fonction qui supprime ici toute référence aux pages découpées :

function sommaire_id_page($element, $page) {
	return $element;
}

A titre d’info, voici le code actuel de la fonction utilisée par défaut :

function sommaire_id_page_dist($element, $page) {
	return $page ? $element 
		.  _T('couteau:sommaire_page', array('page'=>$page))
	 : $element;
}

Balise #CS_SOMMAIRE

Par défaut, le Couteau Suisse insère le sommaire en tête d’article automatiquement. Mais vous avez la possibilité de placer le sommaire ailleurs dans votre squelette qu’en tête de votre article grâce à une balise #CS_SOMMAIRE. Attention : l’utilisation de cette balise doit être activée dans la page de configuration de l’outil « Sommaire automatique » et annule ainsi l’insertion automatique du sommaire dans vos articles.

Cette balise renvoie le sommaire seul quand il existe, et se comporte un peu comme la balise #TEXTE : elle doit être placée à l’intérieur d’une boucle ARTICLES. Depuis la version 1.8.36.00 du Couteau Suisse, la balise #CS_SOMMAIRE accepte un paramètre numérique permettant d’accéder directement à un article par son id_article (grâce à un appel SQL), évitant ainsi une boucle dédiée.

Exemples : #CS_SOMMAIRE{2}, #CS_SOMMAIRE{#GET{toto}} ou #CS_SOMMAIRE{#ENV{id_article}}.

Attention, ce raccourci ne doit pas être utilisé à l’intérieur d’une boucle du même article, sous peine d’un appel SQL inutile. Exemple évident à éviter :
<BOUCLE01(ARTICLES)>#CS_SOMMAIRE{#ID_ARTICLE}</BOUCLE01>
Vous l’avez compris, la syntaxe correcte est bien sûr :
<BOUCLE01(ARTICLES)>#CS_SOMMAIRE</BOUCLE01>

Depuis la version 1.8.154 du Couteau Suisse, le filtre |sommaire_url{nouvelle_URL} vous permet de remplacer l’URL par défaut du sommaire (celle de la page courante en fait) par celle de votre choix. Ce filtre vous sera indispensable lorsque la balise #CS_SOMMAIRE n’est pas utilisée sur la page de l’article correspondant.

L’exemple suivant retourne une liste de sommaires d’articles pointant correctement vers les intertitres repérés dans chacun des articles :
<BOUCLE01(ARTICLES)>[(#CS_SOMMAIRE|sommaire_url{#URL_ARTICLE})]</BOUCLE01>

Voici deux exemples rendant le même résultat (le premier cependant fait un appel SQL supplémentaire) :
-  [(#CS_SOMMAIRE{2}|sommaire_url{#URL_ARTICLE{2}})]
-  <BOUCLE01(ARTICLES){id_article=2}>[(#CS_SOMMAIRE|sommaire_url{#URL_ARTICLE})]</BOUCLE01>

Notes techniques et astuces

-  Techniquement parlant, cet outil agit sur toutes les balises #TEXTE trouvées dans vos squelettes et insère un sommaire. Vous pouvez donc insérer des intertitres dans vos articles, vos textes de rubrique, etc.

-  Une condition est cependant nécessaire : l’insertion automatique du sommaire ne fonctionnera pas si votre squelette (en fait, l’ensemble de vos fichiers .html) utilise la balise #TEXTE étoilée (« #TEXTE* »). En effet, cette syntaxe permet de s’affranchir de tous les filtres automatiques et SPIP renvoie donc le texte brut sans aucune transformation. Si vous tenez absolument à l’étoile pour ajouter un de vos filtres par exemple, alors il faut écrire dans une boucle ARTICLES : [(#TEXTE*|mon_filtre|cs_traitements{TEXTE,articles})] à la place de [(#TEXTE)]. Explication : l’étoile de la balise empêche tout traitement SPIP et renvoie le texte brut stocké en base de données, le filtre |mon_filtre est votre fonction perso écrite dans le fichier mes_fonctions.php, puis le filtre |cs_traitement du Couteau Suisse rétablit les traitements originaux de SPIP correspondant à la balise #TEXTE et aux objets articles.

-  Si une balise n’est pas couverte par le traitement du sommaire automatique, alors utilisez le filtre |sommaire_d_article.
Exemple : [(#MA_BALISE|sommaire_d_article)].
Cette méthode est également applicable à une inclusion.
Exemple : [(#INCLURE{fond=mon-fond, id_article, env}|sommaire_d_article)]
Notez que si la balise #CS_SOMMAIRE est active, le sommaire n’est pas inséré automatiquement au texte examiné. Veuillez consulter le paragraphe suivant pour le paramétrage du filtre.

-  Paramétrage du filtre |sommaire_d_article (depuis la révision 61832 du Couteau Suisse) :
Un texte + son sommaire inséré si la balise #CS_SOMMAIRE est inactive :
   [(#UNTEXTE|sommaire_d_article)]
Un texte + son sommaire inséré quel que soit l’état de la balise #CS_SOMMAIRE :
   [(#UNTEXTE|sommaire_d_article{0})]
Le sommaire seul, calculé grâce au modèle fonds/sommaire.html :
   [(#UNTEXTE|sommaire_d_article{1})]
Le sommaire seul, sous forme de liste <li></li> :
   [(#UNTEXTE|sommaire_d_article{2})]

-  Comment faire pour éviter le sommaire automatique quelque part dans mon squelette ? Prenons par exemple la balise #TEXTE de la boucle (ARTICLES). Le code à utiliser est : [(#TEXTE*|concat{#EVAL{_CS_SANS_SOMMAIRE}}|cs_traitements{TEXTE,articles})]. Explication : l’étoile de la balise empêche tout traitement SPIP et renvoie le texte brut stocké en base de donnée, le filtre |concat ajoute au texte brut [!sommaire] pour empêcher la création future d’un sommaire, puis le filtre |cs_traitement du Couteau Suisse rétablit les traitements originaux de SPIP correspondant à la balise #TEXTE et aux objets articles. Si vous préférez restreindre le sommaire automatique à certaines rubriques, utilisez par exemple le test suivant : [(#ID_RUBRIQUE|match{'^(3|4|5)$'}|oui) placez votre balise #TEXTE étoilée et filtrée ici]

Correctif :  : Depuis la révision 43782 du Couteau Suisse, la notation précédente est caduque. Ceci :
[(#TEXTE*|concat{#EVAL{_CS_SANS_SOMMAIRE}}|cs_traitements{TEXTE,articles})]
doit être remplacé par cela :
[(#TEXTE*|cs_traitements{TEXTE,articles,sommaire_d_article})]

-  Afin d’éviter que les raccourcis « [!sommaire] » ou « [!fond] » se retrouvent automatiquement dans les résumés produits par la balise #INTRODUCTION, activez aussi l’outil « Balise #INTRODUCTION ».

-  En manipulant les styles css ou en utilisant jQuery, Il vous est possible de manipuler l’aspect du sommaire. Le cadre est en fait un <div id="outil_sommaire" class="cs_sommaire" >.

-  Le cadre du sommaire est livré par défaut avec une marge à gauche (1em) et une marge à droite (0.4em). Si la marge à droite ne vous est pas nécessaire, alors ajoutez le code suivant au fichier css de votre squelette : .cs_sommaire {margin-right:0pt !important;}. Si vous préférez mettre ce cadre en haut à gauche de votre article au lieu de l’avoir à droite, alors ajoutez ce code : .cs_sommaire {float:left !important;}.

-  Pour fixer la largeur et éviter les retours à la ligne : .cs_sommaire { width:10em; white-space:nowrap; }. Pour une hauteur fixe : div.cs_sommaire { height:16em; }. Etc, etc !

-  Cet outil « Sommaire en début d’article » se marie très bien avec l’utilisation d’un outil voisin : « Découpe un texte en pages et/ou onglets ». Si ce dernier est activé, le sommaire détecte en effet les découpages et ajoute le numéro de la page où les différents intertitres SPIP ont été trouvés. Voici l’exemple d’un article sur deux pages :

-  Si vous activez l’outil « Des blocs dépliables » et que vous définissez "h3" comme balise de titre, alors il est possible que le sommaire automatique prenne en compte les titres de vos blocs dépliables. Pour que ce ne soit pas le cas, configurez cet outil en spécifiant une valeur haute, exclue par le niveau de profondeur des intertitres. Exemple : h6.

Notes

[1Et s’il n’y a qu’un seul titre, pas besoin de sommaire, qui n’est donc pas affiché !

Discussion

Aucune discussion

Ajouter un commentaire

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparaît.

Merci d’avance pour les personnes qui vous aideront !

Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.

Qui êtes-vous ?
[Se connecter]

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom