toc ~ un sommaire pour vos articles

Cette action créé un sommaire qui reprend les titres de l'article courant

➠ toc : Sommaire automatique

Cliquer pour lire la documentation

Création d'un sommaire à partir des titres de l'article
syntaxe {up toc}
author LOMART version 1.0 license GNU/GPLv3 credit https://www.jqueryscript.net/layout/Highly-Configurable-jQuery-Table-of-Contents-Plugin-TocJS.html
  • toc: inutilisé
  • class: classe(s) ajoutées au bloc principal
  • style: style inline ajouté au bloc principal
  • css-head: style ajouté au head de la page
  • content = [itemprop="articleBody"]: bloc analysé pour le sommaire
  • selector = h2,h3,h4,h5,h6: liste des selecteurs utilisés pour le sommaire
  • exclude = .notoc: liste sélecteur pour exclusion du sommaire
  • indexingFormats: format des index : nombres, lettres ou
  • maxlen: longueur maxi des titres du sommaire
  • elementClass = uptoc: class de la div navigation
  • rootUlClass = toc-ul-root:
  • ulClass = toc-ul:
  • levelPrefixClass = toc-level-: (interne) préfixe des classes
  • heading:

    Présentation

    Cette action, vous allez la retrouver sur une majorité de pages (longues) de ce site. Elle permet d'ajouter un sommaire à partir des balises de titres

    Vous pouvez la voir en action sur le côté droit de votre navigateur. Elle affiche le sommaire de cet article.

    Pour la démo, je dois me contenter de l'unique sommaire que cette action peut générer pour une page.

    le shortcode de base

    Il suffit de ce simple code pour afficher le sommaire de l'article

    {up toc}

    Comme d'habitude, il est possible d'affiner avec des options et de l'inclure dans une autre action pour avoir le rendu sur le côté droit de cet article.

    {up tabslide=sommaire | tabLocation=right | onLoadSlideOut=1 | panel-style=min-width:170px;max-height:60vh}
    {up toc | indexingFormats=number | heading=TOC->Sommaire | Class=chevron | style=max-height:58vh;overflow-y:auto}
    {/up tabslide}

    Il est inclus dans l'action tabslide avec un onglet sur la droite et une ouverture au chargement. Pour gérer les longs sommaires, on limite la largeur à 170px et la hauteur à 60% de la hauteur de l'écran. Pour l'action, style permet de limiter la hauteur en ajoutant un ascenseur si nécessaire. Nous verrons les autres options au cours de cette démo.

    les URL

    En priorité, les liens utilisent l'attribut id de la balise titre. Sinon, ils sont construits à partir du texte des titres.

    Si 2 titres ont le même texte, un suffixe discriminant sera ajouté pour que le lien soit unique.

    Il est possible de copier le lien pour l'utiliser comme lien avec ancre dans une autre page.

    Les options

    Pour le contenu

    content

    Il s'agit du sélecteur CSS du bloc analysé pour construire le sommaire. [itemprop="articleBody"] par défaut, car c'est celui utilisé par les templates Protostar, Astroid. Pour le site démo qui utilise le template Helix Ultimate, je l'ai défini à .article-details dans le custom/prefs.ini de ce site.

    Il sera sans doute nécessaire de l'adapter pour votre template. pour Astroid

    selector

    'h2,h4,h4,h5,h6' par défaut, il s'agit de la liste des sélecteurs utilisés pour le sommaire. Ils sont séparés par des virgules.

    Bien qu'il soit possible d'utiliser n'importe quel sélecteur (h2, .title, #mainTitle, ...) il est préférable d'utiliser cette possibilité pour restreindre les titres pris en compte avec par exemple selector=h2.toc, h3.toc où seuls les titres que vous avez affectés de la classe 'toc' seront utilisés pour le sommaire.

    exclude

    Par défaut, il suffit d'ajouter la classe '.notoc' à une balise pour l'exclure des éléments composant le sommaire.

    indexingFormats

    Permets d'ajouter un index devant le texte des titres et sous-titres Hx. Le préfixe sera ajouté dans le contenu et dans la table des matières.
    Il faut l'indiquer en utilisant une des formes ci-dessous :

    'number', '1': les titres seront précédés d'un préfixe numérique. (1, 2, 3, ...)
    'upperAlphabet', 'A': préfixe avec caractères alphabétiques majuscules (A, B, C, ...)
    'lowerAlphabet', 'a': préfixe avec caractères alphabétiques minuscules (a, b, c, ...)
    'upperRoman', 'I': préfixes avec chiffres romains majuscules (I, II, III, ...)
    'lowerRoman', 'i': préfixes avec chiffres romains minuscules (i, ii, iii, ...)
    ' ' ou '-' : pas de préfixe

    Si vous utilisez la même forme pour tous les niveaux, il suffit de saisir : indexingFormats=number

    Sinon pour une forme différenciée selon les niveaux, le plus rapide est : indexingFormats=1-AaIi.
    Ce qui correspond à number pour les H1, rien pour H2, upperAlphabet pour H3, lowerAlphabet pour H4, upperRoman pour H5 et lowerRoman pour h6
    Note : il faut saisir tous les niveaux même si non pris en compte.

    Attention : cette option est utilisable uniquement pour les sélecteurs H1 à H6. Ne pas utiliser en même temps d'autres sélecteurs pour ne pas perturber la numérotation.

    maxlen

    99 caractères par défaut, cette option limite la longueur des titres dans le sommaire en ajoutant 3 points à la fin

    Pour le style

    Pour illustrer les éléments intervenant pour styler le sommaire, vous trouverez les premières lignes de code générées pour le menu ci-contre.

    <div id="up-134-3" class="uptoc chevron" style="max-height:58vh;overflow-y:scroll">
       <ul class="toc-ul-root toc-ul">
          <li class="toc-heading">
             <a href="#">TOC->Sommaire</a>
          </li>
          <li class="toc-level-1">
             <a href="#presentation">1. Présentation</a>
             <ul class="toc-ul">
                <li class="toc-level-2">
                   <a href="#le-shortcode-de-base">1. 1. le shortcode de base</a>
                </li>
             </ul>
          </li>
    ...      	
    

    Notez que l'id est celle ce l'action. Cela permet d'avoir plusieurs sommaires sur une même page.

    elementClass

    Par défaut 'uptoc', on le retrouve sur la 1ère ligne de l'exemple ci-dessus

    rootUlClass

    Par défaut 'toc-ul-root', c'est la classe de la balise UL principale. Voir ligne 2

    ulClass

    Par défaut 'toc-ul', on le retrouve comme argument de toutes les listes UL. Voir ligne 2 et 8

    La barre ci-dessus, reprenant les principales sections de cette page, est obtenue avec ce shortcode qui utilise la feuille de style de UP :

    {up toc | selector=h2 | ulclass=list-inline-dot | class=tc bg-beige | css-head=#id a:hover[background:tan]}
    

    L'option css-head ajoute du code CSS global à la page. Pour limiter sa portée, on utilise comme premier sélecteur #id, UP le remplacera par l'ID réelle de l'instance de l'action. Dans cet exemple, seul le fond des balises A de ce sommaire changera de couleur.

    levelPrefixClass

    Par défaut 'toc-level-', il sera complété par le niveau de titre. Exemple 'toc-level-1' pour premier niveau indiqué dans selector. 'toc-level-2' pour le 2ème.

    heading

    Non défini par défaut, il s'agit du titre affiché au début du sommaire. Il est clicable pour revenir en haut de la page. Il est affecté de la classe 'toc-heading'

    Personnaliser cette action

    Fichier custom/prefs.ini

    Pour éviter la saisie répétitive des options, vous pouvez y répondre par avance dans le fichier custom/prefs.ini

    Pensez à utiliser css-head pour donner des règles CSS adaptées à votre template.

    Sur ce site qui utilise le template Helix Ultimate, j'ai défini le sélecteur de contenu à l'aide des lignes ci-dessous dans mon fichier custom/prefs.ini

    [options]
    content=.article-details

    SCSS et CSS

    Si la personnalisation avec le fichier prefs.ini ne suffit pas ou si vous voulez avoir plusieurs présentations, copier le fichier que vous voulez personnaliser (toc.scss ou toc.css) dans le sous-dossier custom. Attention, ne copier jamais le fichier SCSS si vous ne comptez pas l'utiliser, car il écraserait le fichier CSS lors de sa compilation

    Le sommaire de cette démo utilise la personnalisation chevron dont le code SCSS est affiché ci-contre.

    Les lignes 2 à 5 ajoutent un chevron (unicode UxBB) bleu devant toutes les lignes. L'unicode 0a est un espace pour le séparer du texte.

    La ligne 6 cible le lien a du premier niveau (toc-level-1) pour le mettre en gras

    La ligne 7 modifie l'icône et modifie la couleur

    .uptoc.chevron {
        li:before {
            content:"\BB\0A";
            color:#369;
        }
        .toc-level-1 > a {font-weight:bold}
        .toc-level-1:before {content:"\27a7\0a";color:#369}
    }

    Smooth scroll et décalage

    Vous avez, sans doute, remarqué que pour cette démo le déplacement vers la partie ciblée se fait avec douceur et prend en compte la hauteur de la barre de menu. Cela est fait par le script smooth-scroll.js

    Par défaut, le fichier fourni avec l'action toc n'a pas de décalage. Pour l'adapter à votre site, il va falloir mettre les mains dans le camboui !

    1. dupliquer le fichier /plugins/content/up/actions/toc/smooth-scroll.js dans le sous-dossier custom. Doréavant, c'est cette version qui sera chargée par UP
    2. Ouvrez ce fichier avec un éditeur de texte
    3. Modifier la valeur de headerHeight avec la hauteur en pixel du décalage souhaité
    4. Vous pouvez ajuster la valeur de speed à votre convenance. Plus sa valeur est élevée, plus le déplacement est lent

    Ce script est également utilisé lorsque vous venez d'une autre page avec un lien 'ancré'