Un sommaire pour vos articles, sans plugin

Comment créer simplement un sommaire pour vos articles WordPress ?

Même si des plugins le font déjà, je vous propose de voir ici comment réaliser un système de sommaire automatique, avec deux petits bouts de code.

Il s’agit de la même fonction qui me sert à concevoir les indexes de ce site…

Pourquoi un sommaire

Le sommaire est un élément ergonomique important dont la présence est nécessaire pour plusieurs raisons :

• Il permet d’abord au lecteur de savoir rapidement de quoi traite un article, et il informe sur les chemins que va emprunter l’auteur pour délivrer son message.
• S’il s’agit d’un contenu d’une longueur conséquente, il incite l’internaute à s’y intéresser.
• Enfin c’est un outil qui permet d’aller directement de chapitre en chapitre pour trouver le passage qui nous intéresse, et de retourner à une partie précise si on a besoin de la relire.

Pour ces trois motifs, je vous conseille de mettre un sommaire dès que l’article comporte plus de deux sections.

Fonctionnement du sommaire

Pour réaliser un sommaire, il nous faut deux types d’éléments :

1. Des ancres, qui vont nous servir à baliser le contenu
2. Des liens vers ces ancres, qui vont constituer les entrées de l’index

Il est possible de réaliser ça à la main, bien évidemment, en ajoutant des ancres dans le texte et des liens juste après l’introduction, mais ce serait long et fastidieux.

Nous pouvons également d’utiliser un plugin comme Table of Content, cependant c’est vraiment plus fun de le coder sois-même :-P.

Pour baliser vos articles de façon pertinente, le plus logique est d’utiliser les niveaux de titre <h2>,<h3>,<h4>. Notre système va donc leur ajouter des ancres, puis il va automatiquement créer des liens vers celles-ci.

Into ze code !

Nous allons concevoir le système de sommaire en deux étapes : d’abord nous allons voir le code pour ajouter les ancres ; ensuite nous allons coder l’affichage de l’index.

Ajout automatique des ancres dans votre contenu

Pour ajouter les ancres sur les différentes sections, nous allons ajouter un filtre sur le contenu des posts qui va rechercher le h2,h3 et h4 et placer des id sur ces balises.

Il faut utiliser la fonction preg_replace_callback() de PHP qui permet de faire des modifications sur des éléments que notre regex va isoler dans la chaîne. L’avantage, par rapport à un simple preg_replace() c’est que l’on peut passer une fonction en paramètre et donc effectuer des transformations plus complexes.

Dans le fichier functions.php de votre thème, ajoutez le code suivant :

function replace_ca($matches){
  return '<h'.$matches[1].$matches[2].' id="'.sanitize_title($matches[3]).'">'.$matches[3].'</h'.$matches[4].'>';
}

//Ajout d'un filtre sur le contenu  
add_filter('the_content', 'add_anchor_to_title', 12);
function add_anchor_to_title($content){   
  if(is_singular('post')){ // s'il s'agit d'un article
    global $post;
    $pattern = "/<h([2-4])(.*?)>(.*?)<\/h([2-4])>/i";
    
    $content = preg_replace_callback($pattern, 'replace_ca', $content);
    return $content;
  }else{
    return $content;
  }
}

Notre regex /<h([2-4])(.*?)>(.*?)</h([2-4])>/ recherche tout ce qui correspond à des balise <h2>,<h3> ou <h4>, peut importe leur attribut ou leur contenu.
Le callback replace_ca() rajoute à ces balises un ID dont la valeur est une chaîne normalisé inspirée du texte du titre.

Pour prendre un exemple :

<h2>Mon titre de niveau 2</h2>

… va devenir…

<h2 id= »mon-titre-de-niveau-2″>Mon titre de niveau 2</h2>

Nos articles seront alors balisés automatiquement.

Une fonction pour ressortir le sommaire

Il faut donc maintenant coder la fonction pour afficher le sommaire, qui sera constitué de liens pointant vers les ancres précédemment crées.

Cette fonction va récupérer le contenu de l’article, puis isoler les balises qui nous intéresse afin de reconstituer les liens comme il faut.

On utilise pour ça la fonction preg_match_all() pour pousser tout ce qui correspond à notre regex (/<h([2-4])(.*?)>(.*?)</h([2-4])>/) dans la variable $results sous forme de tableau.

Ensuite, il reste à utiliser $results pour générer nos liens.

Ajoutez le code suivant dans le functions.php de votre thème :

function automenu( $echo = false ){
  global $post;
  $obj = '<nav id="sommaire-article">';
  $original_content = $post->post_content;

  //on récupère les titres
  $patt = "/<h([2-4])(.*?)>(.*?)<\/h([2-4])>/i";
  preg_match_all($patt, $original_content, $results);
        
  //on génère les liens
  foreach ($results[3] as $k=> $r) {
    $obj .= '<a class="title_lvl'.$results[1][$k].' " href="#'.sanitize_title($r).'">'.$r.'</a>';
  }

  $obj .= '</nav>';
  if ( $echo )
    echo $obj;
  else
    return $obj;
}

Cette fonction, utilisée dans la boucle, nous permet d’obtenir le sommaire de l’article. Mais il est encore possible de l’améliorer…

Avec des numéros s’il vous plait!

Comme vous pouvez le voir par exemple dans le sommaire de cet article, il est possible d’ajouter des numéro devant chaque entrée du sommaire, de manière à se repérer encore plus facilement.

Disons que les titres de niveau 2 sont ornés d’un numéro, et les titres de niveau 3 d’une lettre.

L’itération des lettres doit bien sûr être réinitialisée à chaque fois que l’on change de grand titre.

Modifions la function automenu() :

function automenu( $echo = false ){
  global $post;
  $obj = '<nav id="sommaire-article">';
  $original_content = $post->post_content;

  $patt = "/<h([2-4])(.*?)>(.*?)<\/h([2-4])>/i";
  preg_match_all($patt, $original_content, $results);

  $lvl1 = 0;
  $lvl2 = 0;
  $lvl3 = 0;

  foreach ($results[3] as $k=> $r) {
    switch($results[1][$k]){
      case 2:
        $lvl1++;
        $niveau = '<span class="title_lvl">'.$lvl1.'/</span>';
        $lvl2 = 0;
        $lvl3 = 0;
        break;

      case 3:
        $lvl2++;
        $niveau = '<span class="title_lvl">'.base_convert(($lvl2+9),10,36).'.</span>';
        $lvl3 = 0;
        break;

      case 4:
        $lvl3++;
        $niveau = '<span class="title_lvl">'.$lvl3.')</span>';
        break;
    }

    $obj .= '<a href="#'.sanitize_title($r).'" class="title_lvl'.$results[1][$k].'">'.$niveau.$r.'</a>';
  }

  $obj .= '</nav>';
  if ( $echo )
    echo $obj;
  else
    return $obj;
}

Par rapport à la version précédente, on a simplement ajouté 3 variables dans lesquelles vont s’incrémenter les niveaux de titre.
Un switch est utilisé pour itérer/réinitialiser les variables, ainsi que pour déterminer la lettre ou le numéro qui va bien.

La fonction base_convert() sert à faire ressortir une lettre selon sa position dans la table des caractères.

Le code complet

Notre système de sommaire est complet, il est temps de récapituler.
Le fichier functions.php doit contenir :

/**
Génèse des ancres
*/
function replace_ca($matches){
  return '<h'.$matches[1].$matches[2].' id="'.sanitize_title($matches[3]).'">'.$matches[3].'</h'.$matches[4].'>';
}

//Ajout d'un filtre sur le contenu  
add_filter('the_content', 'add_anchor_to_title', 12);
function add_anchor_to_title($content){   
  if(is_singular('post')){ // s'il s'agit d'un article
    global $post;
    $pattern = "/<h([2-4])(.*?)>(.*?)<\/h([2-4])>/i";
    
    $content = preg_replace_callback($pattern, 'replace_ca', $content);
    return $content;
  }else{
    return $content;
  }
}

/**
Function automenu( $echo = false )
*/
function automenu(){
  global $post;
  $obj = '<nav id="sommaire-article">';
  $original_content = $post->post_content;

  $patt = "/<h([2-4])(.*?)>(.*?)<\/h([2-4])>/i";
  preg_match_all($patt, $original_content, $results);

  $lvl1 = 0;
  $lvl2 = 0;
  $lvl3 = 0;

  foreach ($results[3] as $k=> $r) {
    switch($results[1][$k]){
      case 2:
        $lvl1++;
        $niveau = '<span class="title_lvl">'.$lvl1.'/</span>';
        $lvl2 = 0;
        $lvl3 = 0;
        break;

      case 3:
        $lvl2++;
        $niveau = '<span class="title_lvl">'.base_convert(($lvl2+9),10,36).'.</span>';
        $lvl3 = 0;
        break;

      case 4:
        $lvl3++;
        $niveau = '<span class="title_lvl">'.$lvl3.')</span>';
        break;
    }

    $obj .= '<a href="#'.sanitize_title($r).'" class="title_lvl'.$results[1][$k].'">'.$niveau.$r.'</a>';
  }

  $obj .= '</nav>';
  if ( $echo )
    echo $obj;
  else
    return $obj;
}

Parfait !

Mais nous n’en n’avons pas fini pour autant, il faut afficher le sommaire…

Appel du sommaire

Soit on décide d’afficher le sommaire systématiquement sur tous les articles, à un emplacement dédiée et inéchangeable, soit on préfère utiliser un shortcode pour placer le sommaire dans le contenu de l’article, après l’introduction par exemple.

Dans le template

Si on veut afficher l’index toujours au même endroit dans le thème, alors il suffit d’appeler la fonction automenu() à cet emplacement.
La fonction doit être utilisée dans la boucle WordPress, ou alors il faudra revoir le code de manière à préciser l’ID du post pour détailler le contenu voulu.

// template function
automenu( true );

Via un shortcode

Une autre solution est d’utiliser un shortcode. L’API des shortcodes de WordPress est schtroumphement bien faite, puisque schtroumphement simple.

Il suffit d’ajouter cette ligne dans le fichier functions.php :

// shortcode
add_shortcode('sommaire','automenu');

Dès lors, il suffira d’ajouter [sommaire] dans le contenu de notre article pour générer un sommaire à ce lieu précis.

Animation du scroll avec jQuery

Je pense qu’ergonomiquement, il peut être intelligent d’utiliser une transition pour rendre compte d’un déplacement dans le contenu, lorsque l’on clique sur une entrée du sommaire.

En effet :

1. Ça permet déjà de visualiser si l’on se rend à un chapitre précédent ou suivant.
2. Cela rend compte de la quantité de texte survolé (et potentiellement nécessaire à la compréhension de l’article).

Ce bout de javascript utilise le plugin jQuery scrollTo utilise un code jQuery de Geoffrey Crofte pour se déplacer verticalement de façon fluide dans la page.

Il suffit de place le code suivant dans votre fichier javascript principal :

jQuery(document).ready(function($){
    $(document).on('click','#sommaire-article a',function(){
        var h = $(this).attr('href');

        $('body,html').animate({  
            scrollTop:$(h).offset().top  
        }, 500); 
        return false;
    });
});

…Bonus

En bonus voici le détail du code pour réaliser des animations d’entrée du menu comme sur ce site.
Ici les éléments du menu surgissent de la gauche, mais il est possible de réaliser de nombreuses animations, ce n’est pas très compliqué…