HTML : details

J'ai développé en 2007, au boulot, un composant javascript appelé « InfoBox » qui fait ce qui est aujourd'hui proposé par l'élément details dans les spécifications HTML 5 (et même un peu plus). Cet élément n'est encore implémenté que par très peu de navigateurs web. Voici quelques pistes pour l'utiliser / le simuler.

Présentation

Les spécifications

Voyons d'abord ce que dit le brouillon des recommandations HTML 5 à propos de l'élément details :

  • Il s'agit d'un élément de divulgation (disclosure widget) qui permet de fournir une information complémentaire en se dépliant.
  • Il peut contenir des éléments summary dont seul le premier est affiché.
  • S'il ne possède pas de summary, les navigateurs web doivent en afficher / générer un automatiquement.
  • Le plier / déplier du contenu est marqué par la propriété booléenne open ; le navigateur web doit fournir à l'utilisateur un moyen d'effectuer cette opération.

Voilà pour la théorie. Pour la pratique, prenons un exemple simple qui nous servira de base de travail par la suite :

<details>
    <summary>Plus de détails</summary>
    <p>Ce paragraphe fournit un détail supplémentaire.</p>
    <p>Ce second paragraphe fournit autre détail.</p>
</details>
Exemple simple d'utilisation de l'élément details.

Avec ce code, nous devrions voir affiché dans le document web uniquement le texte du summary, le reste étant masqué. Par une interaction quelconque avec le document (clic sur l'élément par exemple), l'utilisateur pourrait afficher / masquer les deux paragraphes. Et dans les faits ?

Plus de détails

Ce paragraphe fournit un détail supplémentaire.

Ce second paragraphe fournit un autre détail.

Rendu original d'un élément details.

Si vous visualisez cette page avec Firefox <= 19, Opera <= 12.12 ou Internet Explorer <= 10, vous verrez en fait l'intégralité du contenu de l'élément affiché. Seul Chromium, à partir de la version 14, semble appliquer un rendu en accord avec les recommandations W3C.

Pourquoi cet élément ?

Il n'est pas question ici de discuter du bien fondé de l'élément details : les composants de ce type sont assez courant dans les librairies graphiques pour application de bureau, d'où leur simulation dans les applications web à l'aide de CSS et de javascript. Comme le HTML 5 est très orienté « application web », et qu'il est toujours préférable - pour des questions de performances principalement - d'utiliser une fonctionnalité native...

Le comportement plier / déplier pourrait aussi être utile ailleurs ; comme sur un élément section par exemple, avec son header qui aurait le même comportement que le summary quand on clique dessus : afficher / masquer le reste du bloc ; ou bien un comportement plier / déplier pour des listes hiérarchisées : cliquer sur un item plie / déplie ses sous-items.

D'aucuns diraient que le web, c'est avant tout du contenu avant d'être de l'applicatif ; pas faux. Toujours est-il que l'on peut envisager de nombreux usages pour l'élément details dans un cadre « classique », comme par exemple dans des critiques de films / romans : on voit souvent l'auteur de la critique avertir le lecteur que le texte qui va suivre dévoile une partie de l'intrigue ; on pourrait dés lors imaginer structurer le texte avec des éléments details de telle sorte que ces parties soient masquées par défaut.

Encore faut-il que l'élément soit fontionnel, ce qui n'est aujourd'hui pas le cas pour la plupart des navigateurs web. Nous allons voir comment corriger cela.

Implémentation javascript

Il ne serait pas judicieux de publier ici le code du composant InfoBox développé au boulot il y a quelques années, non pas que cela me soit interdit (il est sous licence libre), mais c'est un code (1) qui ne se base pas sur details, (2) qui est un peu trop spécifique à la libraire javascript/java sur laquelle il repose et (3) qui possède plus de fonctionnalités que l'élément HTML5. On peut cependant et très simplement penser un code javascript qui obéirait à quelques règles de bases :

  • Afficher / masquer le contenu de details quand on clique sur son premier enfant.
  • Appliquer notre implémentation uniquement si l'élément details n'est pas géré nativement par le navigateur web.
  • Laisser l'ensemble de l'élément visible lorsque le javascript n'est pas actif.

Nous pouvons écrire cette logique d'affichage / masquage du contenu de l'élément dans un objet dédié afin de pouvoir éventuellement l'utiliser ailleurs.

define(function () {
    'use strict';
    
    var RE_HEADINGS = /^h\d$/;
    
    var RE_PARENT = /^(article|section|div)$/;
    
    var CLASS = 'expander';
    
    var CLASS_TARGET = 'expander-target';
    
    /**
     *  Flag to know if 'details' elements are supported by the browser.
     *  @private
     *  @type Boolean
     */
    var detailsSupported = ('open' in document.createElement('details'));

    /**
     *  Listen to mutation events.
     *  @protected
     *  @param {MutationRecord[]} mutations
     */
    var onPropertyMutation = function (mutations) {
        render(mutations[0].target);
    };

    /**
     *  Listen click events on element to open / close.
     *  @protected
     *  @param {Event} e Object DOM Event
     */
    var onTargetClick = function (e) {
        var target = e.target,
            targetName = target.nodeName.toLowerCase();
        if (target.htmlFor || targetName === 'input' || targetName === 'button') {
            // Ne pas agir sur un label avec un for, un input, un button
            return;
        }
        if (targetName === 'a' && target !== e.currentTarget) {
            // Ne pas agir si c'est un lien qui n'est pas l'élément cible.
            return;
        }
        e.preventDefault();
        toggle(e.currentTarget.parentNode);
    };

    /**
     *  Mutation observer.
     *  @private
     *  @type MutationObserver
     */
    var observer = ('MutationObserver' in window) 
        ? new MutationObserver(onPropertyMutation) 
        : (('WebkitMutationObserver' in window) 
            ? new WebkitMutationObserver(onPropertyMutation) 
            : null);

    /**
     *  Configuration de l'observateur de mutations.
     *  @private
     *  @type MutationObserverInit
     */
    var observerConfig = {
        attributes: true,
        attributeFilter: ['open']
    };

    /**
     *  Descripteur de la propriété 'open' pour les details.
     *  @private
     *  @type Object
     */
    var openProperty = {
        enumerable: true,
        configurable: false,
        get: function () {
            return this.getAttribute('open') !== null;
        },
        set: function (newValue) {
            if (newValue === this.open) {
                return;
            }
            if (newValue) {
                this.setAttribute('open', 'open');
            } else {
                this.removeAttribute('open');
            }
        }
    };

    /**
     *  Méthode de switch de l'état ouvert / fermé d'un élément.
     *  @private
     *  @param {HTMLElement} el
     */
    var toggle = function (el) {
        var state = !el.open;
        el.open = state;
        el.setAttribute('aria-expanded', state ? 'true' : 'false');
        if (!observer) {
            render(el);
        }
    };

    /**
     * Rendu graphique de l'état ouvert / fermé d'un élément.
     * @private
     * @param {HTMLElement} el
     */
    var render = function (el) {
        el.style.height = el.getAttribute('data-height-' 
                + (el.open ? 'open' : 'close')) + 'px';
    };

    var init = function (el, target) {
    
        var nodeName = el.nodeName.toLowerCase(),
            styles,
            pTop,
            pBottom,
            hClose,
            hOpen;
        
        if ((nodeName === 'details' && detailsSupported)
                || el.classList.contains('nojs') 
                || el.getAttribute('data-expander-initialized') === 'true') {
            return;
        }
        
        // Manage target
        if (!target) {
            // first target with offset
            var n = el.children.length,
                i = 0;
            for (i = 0; i < n; i += 1) {
                if (el.children[i].offsetHeight) {
                    target = el.children[i];
                    break;
                }
            }
        }
        if (!target) {
            console.warn('[rnb2/ui/expander] No target for click');
            console.log(el);
            return;
        }
        
        // Create sumlamry for details if it does not exist
        if (nodeName === 'details' 
                && target.nodeName.toLowerCase() !== 'summary') {
            target = document.createElement('summary');
            target.appendChild(document.createTextNode('Details'));
            el.insertBefore(target, el.firstChild);
        }
        
        // Find heights
        styles = window.getComputedStyle(el, null);
        pTop = styles.paddingTop;
        pBottom = styles.paddingBottom;
        hOpen = el.clientHeight;
        hClose = el.getAttribute('data-height-close');
        if (pTop) {
            hOpen -= parseInt(pTop, 10);
        }
        if (pBottom) {
            hOpen -= parseInt(pBottom, 10);
        }
        
        if (!hClose) {
            el.setAttribute('data-height-close', target.offsetHeight);
        }
        el.setAttribute('data-height-open', hOpen);
        el.setAttribute('data-expander-initialized', 'true');
        el.classList.add(CLASS);
        target.classList.add(CLASS_TARGET);
        
        // Définir la propriété 'open' mappée sur l'attribut 'open'
        Object.defineProperty(el, 'open', openProperty);
        
        var state = el.getAttribute('aria-expanded') === 'true';
        el.open = state;
        el.setAttribute('aria-expanded', state ? 'true' : 'false');
        render(el);
        
        if (observer) {
            observer.observe(el, observerConfig);
        }
        
        target.addEventListener('click', onTargetClick, false);
    };
    
    // export
    return {
        /**
         * Manage a specific element
         * @param {HTMLElement} el
         * @param {HTMLElement} [target]
         */
        initElement: function (el, target) {
            init(el, target);
        },
        
        /**
         * Initialize all available components in the current document.
         */
        initDocument: function () {
            var list = document.querySelectorAll('details, .expander'),
                i,
                n,
                element,
                target;
            
            n = list.length;
            
            for (i = 0; i < n; i += 1) {
                element = list[i];
                target = null;
                // Cas particulier si class portée par un titre et parent est un
                // article, section, div, alors expander est ce parent
                if (element.nodeName.toLowerCase().search(RE_HEADINGS) > -1
                        && element.parentNode.nodeName.toLowerCase().search(RE_PARENT) > -1) {
                    target = element;
                    target.classList.remove('expander');
                    element = element.parentNode;
                    element.classList.add('expander');
                }
                init(element, target);
            }
        }
    };
});
Gestion d'affichage / masquage d'un élément.

Ensuite, il ne reste plus qu'à gérer les éléments details au chargement de la page.

Implémentation CSS

Contenu indisponible.
Code CSS associé à la gestion des details en javascript.

Résultat et discussions

Plus de détails

Ce paragraphe fournit un détail supplémentaire.

Ce second paragraphe fournit un autre détail.

Afficher le contenu de details en cliquant dessus.
  • Le code javascript ci-dessus est très basique et très simplifiée ; il nécessiterait quelques adaptations pour se retrouver en production et être utilisable avec tous les navigateurs web. L'exemple est cependant fonctionnel sous Firefox >= 5, Opera >= 11.11 et Internet Explorer >= 9.
  • On pourrait penser à augmenter les fonctionnalités de l'élément comme gérer l'événement focus et permettre par exemple d'utiliser la touche enter ou space pour ouvrir / fermer l'élément.
  • On pourrait enfin émettre des évenements « open » et « close » lors des actions sur l'élément.

Ressources et références

HICKSON, Ian ; BERJON, Robin ; FAULKNER, Steve, et al.. HTML 5. W3C, . 4.11.1 The details element

HUNT, Lachlan. Styling <details>. Public mailing list for the WHAT working group, . Pistes de reflexion sur l'implémentation de details dans Opera.

LAWSON, Bruce. HTML5 details element, built-in and bolt-on accessibility. brucelawson.co.uk,

NIBAU, Rui. Attributs et propriétés DOM. Omacronides,

NIBAU, Rui. Objet javascript vs DOM. Omacronides,

Historique

2013-10-05
  • add Fonctionnalités supplémentaires possibles (événements).
  • upd Seconde implémentation avec couple propriété / attribut.
2013-08-23
  • upd Extraction de la logique 'expander' dans un objet extérieur.
2013-07-02
  • fix Suppression des dépendances à rnb-js.
2013-01-05
  • fix Suppression des expérimentations CSS.
  • upd Lien vers le code original utilisé dans rnb-js.
2012-04-09
  • upd Evolution: Icône plier / déplier avec le pseudo-élément before plutôt qu'une image de fond.
2012-02-11
  • upd Jouer sur la taille et l'overflow de l'élément plutôt que la visibilité des enfants pour afficher / masquer le contenu.
2011-06-25
  • add Création de l'article.