toc ~ un sommaire pour vos articles

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

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 :

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

v1.8 le texte complet est affiché dans la bulle de title

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

.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é'