Reading Indicator js v1.0

Reading Indicator est un plugin jQuery qui a pour objectif de mesurer le taux de lecture d'un contenu ou d'un texte, et non d'une page complète comme le font très bien d'autres plugins. La difficulté est de réussir à mesurer le pourcentage de lecture d'une zone précise, ce à quoi ReadingIndicator.js répond.

Lisez la documentation complète et visionnez les exemples ci-dessous pour vous familiariser avec l'outil, mais retenez que de nombreux usages sont possibles grâce aux fonctions de retour (callbacks), en plus d'afficher le pourcentage et une barre de progression.

  • Affichage d'un pourcentage de lecture.
  • Personnalisation de l'affichage de la barre de progression et du pourcentage.
  • Affichage d'alertes personnalisées dans une fonction de rappel.
  • Envoi de scripts (Ajax ou non) dans une fonction de rappel.
  • Gestion de l'arrêt du défilement avec l'événement scrollStop.
Télécharger ReadingIndicator.js (v.1.0) [RAR - 7Ko]

Utilisation

Insertion dans le code HTML

Vous pouvez récupérer les URL des dernières versions des librairies externes sur ce site.

Inclusion du code Javascript

<!-- Normalement dans le <head>, idéalement avant </body> -->
<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
<script src="CHEMIN_DOSSIER_JS/reading-indicator.min.js"></script>

Lancement du script jQuery

<!-- Normalement dans le <head>, idéalement avant </body> -->
<script>
jQuery(document).ready(function($) {
	$(SELECTEUR).readingIndicator();
});
</script>

Inclusion du fichier CSS (personnalisable)

<!-- Placé dans le <head> -->
<link rel="stylesheet" type="text/css" href="reading-indicator.css"/>

Simple usage

Utilisation par défaut du plugin readingIndicator(). Le placement de la barre de progression se colle au body (avec un mode "sticky") et affiche le pourcentage de lecture de la zone ciblée (ici le contenu au centre). Par défaut, le milieu de la fenêtre représente le contexte de lecture, on considère donc que le pourcentage va évoluer en se basant sur le point central (en hauteur) de la fenêtre.

Multiple usage

Utilisation multiple du plugin readingIndicator(). Ici, la première instance analyse le taux de lecture de l'entête (#header), déjà à 100% à cause des réglages par défaut (milieu de l'écran comme zone de repère). La seconde instance profite de quelques options pour s'afficher à gauche et s'adapter à la taille du bloc de contenu (ici, c'est le bas de l'écran qui sert de contexte pour calculer le pourcentage de lecture).

Affichage arrondi

Utilisation du plugin readingIndicator() avec une barre de progression arrondie. Il faut utiliser des fonctions de callbacks pour créer ce type de barre spécifique, comme dans l'exemple suivant.

Affichage personnalisé

Personnalisation de l'affichage du pourcentage. On utilise la fonction de callback cbkPercentDisplay pour retourner ce qu'on souhaite. Dans l'exemple, il est affiché "Reading:" devant le pourcentage de lecture, pour apporter une précision supplémentaire.

Alert en fonction du scroll

Exemple d'affichage d'une alert Javascript lorsqu'un pourcentage de lecture est atteint et dépassé. Il est possible de proposer bien d'autres alternatives plus évoluées, il s'agit essentiellement de montrer un exemple d'usage de la fonction de callback "cbk". Il convient de bien gérer l'option scrollStopDelay à 250 (ms) ou plus pour éviter une propagation de l'effet (répétition des alertes à cause de la vitesse de scroll).

jQuery UI Dialog en cliquant sur un lien

Ajout de jQuery UI et utilisation des fonctions Dialog qui permettent d'afficher des alertes personnalisées et plus jolies dans Reading Indicator. Dans l'exemple, un clic sur un lien dans la page affiche une alerte Dialog avec le pourcentage de lecture déjà lu. On peut imaginer des fonctions bien plus évoluées pour afficher des publicités, des contenus alternatifs, etc.

Options et fonctions de rappels (callbacks)

Plusieurs options sont disponibles pour personnaliser le plugin Reading Indicator. Toutes ne peuvent pas fonctionner ensemble à tout moment, il convient de bien vérifier et paramétrer le plugin pour adapter le résultat à votre volonté. Les exemples proposés dans cette page donnent une idée des possibilités, bien que tout n'a pas été dévoilé.

Liste complète des options (avec valeurs par défaut)

var options = {
	context: 'middle',
	distance: 0,
	targetProgressBar: 'body',
	fixedBarSize: false,
	stickyProgressBar: true,
	stickyClass: 'stickyProgressBar',
	progressPositions: {
		progressBarPosition: 'top',
		progressValuePosition: 'bottom',
	},
	progressBarValue: true,
	progressBarID: 'reading-scroller',
	progressBarClass: 'reading-progress',
	progressPercentClass: 'reading-percentage',
	percentSignClass: 'reading-sign',
	hideBeforeOffsetTop: false,
	hideAfterOffsetBottom: false,
	hideBeforePercent: false,
	hideAfterPercent: false,
	scrollStopDelay: 200,
	cbkOnce: false,
	cbk: function() {},
	cbkDisplay: function() {},
	cbkPercentDisplay: function() {}
};

Détails des options

  • context(middle)String [top / middle / bottom]
    Contexte qui détermine le point de départ (offset) pour le calcul du pourcentage. Considérez cela comme la cible de base du calcul. Par exemple, "top" utilise le haut de l'écran comme facture de calcul, "bottom" le bas et "middle" le milieu de la fenêtre visible.
  • distance(0)Integer [-i / i]
    Décalage de l'offset vers le haut (-i) ou vers le bas (i) par rapport au "context". Cela permet d'adapter la cible du calcul du pourcentage de lecture selon la zone du regard que vous estimez courante pour vos lecteurs. Par exemple, mettez "context" sur top et "distance" sur 200 pour décaler le point de calcul de 200 pixels par rapport au haut de la fenêtre.
  • targetProgressBar(body)String
    Sélecteur de la zone cible pour afficher la barre de progression de lecture. On utilise body par défaut mais vous pouvez choisir une zone de contenu ou n'importe quel autre bloc.
  • fixedBarSize(false)Boolean [true / false]
    Permet d'adapter la taille de la barre de progression aux dimensions de la zone de lecture (hauteur ou largeur). Par exemple, si vous placez "targetProgressBar" sur la valeur body et que "fixedBarSize" est sur true, la barre de progression ne fera pas 100% de largeur ou hauteur, mais seulement la dimension de la zone de lecture ciblée par la fonction readingIndicator().
  • stickyProgressBar(true)Boolean [true / false]
    Rend la barre collante (sticky) en haut de l'écran si true est sélectionné. Lorsque l'on positionne la barre à gauche ou à droite de la zone de lecture, il est recommandé de mettre sur false.
  • stickyClass(stickyProgressBar)String
    Classe CSS pour le mode Sticky de la barre de progression.
  • progressPositionsJSON object
    • progressBarPosition(top)String or boolean [top / bottom / left / right / false]
      Position de la barre par rapport à la cible de "targetProgressBar". Utilisez la valeur false pour masquer la barre de progression.
    • progressValuePosition(top)String or boolean [top / bottom / left / right / false]
      Position de la valeur (pourcentage de lecture) par rapport à la barre de progression. Utilisez false pour masquer la valeur et n'afficher que la barre de progression.
  • progressBarValue(true)Boolean [true / false]
    Active ou désactive l'affichage du pourcentage. Indiquer false revient au même que de mettre "progressBarValue" sur false si vous voulez la désactiver.
  • progressBarID(reading-progress)String
    ID du bloc général contenant la barre de progression et la valeur en pourcentage.
  • progressBarClassreading-progress(String)
    Classe du bloc pour la barre de progression.
  • progressPercentClass(reading-percentage)String
    Classe du bloc qui affiche le pourcentage.
  • percentSignClass(reading-sign)String
    Classe du signe "%" (si vous souhaitez le décaler en CSS par exemple).
  • hideBeforeOffsetTop(false)Boolean [true / false]
    Masque la barre de pourcentage de lecture avant d'atteindre l'offset top de la zone de lecture (équivalent au passage entre 0% et 1%).
  • hideAfterOffsetBottom(false)Boolean [true / false]
    Masque la barre de pourcentage de lecture après avoir dépassé l'offset bottom de la zone de lecture (équivalent au passage entre 99% et 100%).
  • hideBeforePercent(false)Integer [-i / i]
    Pourcentage réel (donc de moins de 0% de lecture à plus de 100%) avant lequel la barre de progression n'apparaît pas. Par exemple, indiquez -20 si vous voulez masquer la barre automatiquement 20% avant le début de la zone de lecture.
  • hideAfterPercent(false)Integer [i]
    Pourcentage réel (donc de moins de 0% de lecture à plus de 100%) à partir duquel on fait disparaître la barre de progression. Par exemple, indiquez 120 si vous voulez masquer la barre automatiquement près de 20% après la fin de la zone de lecture.
  • scrollStopDelay(200)Integer [i]
    Délai (en ms) pour le custom event "scrollStop" et pour le debouncing automatique (anti-propagation d'un défilement/scroll). 0 est recommandé si vous voulez afficher l'évolution du pourcentage de manière très fluide (pas de latence), 200 (ou plus) est conseillé si vous souhaitez utiliser des alertes dans une fonction de retour (callback).
  • cbkOnce(false)Boolean [true / false]
    Pour n'activer la fonction de rappel "cbk" qu'une seule fois (effet 'fired'). Cela peut-être utile dans certains cas si la propagation du défilement/scroll se fait trop sentir.
  • cbk({})Function
    Fonction de rappel (callback) après le scrollStop. Retourne trois valeurs : pourcentage, pourcentage réel, pourcentage inversé.
  • cbkDisplay({})Function
    Fonction de rappel (callback) pour personnaliser l'affichage complet de la barre de progression, du pourcentage, etc. La fonction retourne un objet JSON avec les classes CSS utiles.
  • cbkPercentDisplay({})Function
    Fonction de rappel (callback) pour personnaliser l'affichage du pourcentage uniquement. La fonction retourne deux objets JSON : divers pourcentages, classes CSS.

Méthode/Événement

Un événement a été créé spécifiquement pour éviter la propagation du scroll (effet \"debounce\"), intitulé scrollStop. Il se lance au chargement (load) et pendant le défilement des pages (scroll), puis retourne trois valeurs, comme expliqué ci-dessous. Le défilement classique peut poser des problèmes de propagation d'effet lorsque l'on souhaite utiliser une fonction de rappel (callback), cet événement permet donc de les éviter.

Événement disponible : scrollStop

$(SELECTEUR).on('scrollStop', function(e) {
	// Votre code ici...
	// Exemple => alert('Pourcentage : ' + e.getProgress + ' | Pourcentage réel : ' + e.getRealProgress  + ' | Event : ' + e.getEvent);
});

Détail de la méthode scrollStop

  • scrollStopEvent [event.getProgress, event.getRealProgress, event.getEvent]
    L'événement "scrollStop" permet d'effectuer des actions uniquement au chargement et surtout lorsque le scroll s'arrête, après un délai (en ms) fixé par l'option "scrollStopDelay". En cas d'usage multiple du plugin Reading Indicator, le sélecteur "window" peut être remplacé par celui de la zone ciblée afin de n'effectuer l'action que dans un cas précis. L'usage de l'événement retourne quatre valeurs : event.getProgress (pourcentage affichée :0% à 100%), event.getRealProgress (pourcentage réel), event.getInvertedProgress (pourcentage inversé) et event.getEvent (nom de l'événement originel : load ou scroll).

Exemple d'utilisation simple