0 visualização
Tutorial Un widget qui vit dans le navigateur : « Compte à rebours »
Mensagem por ler

Niveau expert · environ 1 h 30 · NeoFrag Reborn 1.2.50 ou plus récent

Les widgets des niveaux précédents étaient dessinés une fois, par le site, puis ne bougeaient plus. Celui-ci continue de vivre dans la page : il compte, seconde après seconde, le temps qui reste avant un événement — un tournoi, une ouverture, un direct. Trois sujets d'expert en chemin :

  • l'heure : l'administrateur la saisit à son heure, le site l'enregistre à la sienne, et chaque visiteur la lit à la sienne ;
  • un script livré avec le widget, sans jQuery, et qui respecte la politique de sécurité du site ;
  • les pluriels dans le navigateur, selon les règles de la langue de la page.

Le compte à rebours

Une fois l'heure passée

Il te faut un site d'essai en NeoFrag Reborn 1.2.50 ou plus récent. Ce widget part de zéro, mais suppose connues les bases des tutoriels Mon premier widget et Un widget à plusieurs visages : la carte d'identité, le checker, le formulaire des réglages. L'archive de ce tutoriel, compte_a_rebours-1.0.0.zip, est jointe à ce sujet.

Le dossier

compte_a_rebours/
├── compte_a_rebours.php        la carte d'identité
├── controllers/
│   ├── index.php               l'affichage : l'instant visé, et les mots des unités
│   ├── checker.php             l'heure saisie, passée à l'heure du site
│   └── admin.php               le formulaire des réglages
├── views/
│   ├── index.tpl.php
│   └── admin.tpl.php
├── js/
│   └── compte_a_rebours.js     le script qui compte
├── css/
│   └── compte_a_rebours.css
├── langs/                      fr.php, en.php, de.php, es.php, it.php, pt.php
└── images/
    └── thumbnail.jpg

Le nom d'un addon s'écrit en minuscules, chiffres et _. Sa classe porte le même nom, Compte_A_Rebours : PHP ne distingue pas les majuscules dans les noms de classes.

Étape 1 — La carte d'identité

compte_a_rebours/compte_a_rebours.php

<?php
declare(strict_types=1);
/**
 * Compte à rebours — le widget du tutoriel « Un widget qui vit dans le navigateur » (expert). LGPLv3.
 */

namespace NF\Widgets\Compte_A_Rebours;

use NF\NeoFrag\Addons\Widget;

class Compte_A_Rebours extends Widget
{
	protected function __info()
	{
		return [
			'title'       => $this->lang('Compte à rebours'),
			'description' => $this->lang('Le temps qui reste avant un événement, à la seconde, dans le fuseau de chaque visiteur.'),
			'icon'        => 'fas fa-hourglass-half',
			'link'        => 'https://neofrag-reborn.xyz',
			'author'      => 'NeoFrag Reborn',
			'license'     => 'LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>',
			'version'     => '1.0.0',
			'depends'     => [
				'neofrag' => '1.2.50'
			],
			'core'        => FALSE,
			'presets'     => [],
			'requires'    => [],
			'types'       => [
				'index' => $this->lang('Compte à rebours')
			]
		];
	}
}

Un seul type, index. Rien de nouveau ici : tout se passe dans les fichiers suivants.

Étape 2 — Trois heures pour un même instant

« Le 24 décembre à 20 h » n'est pas un instant : c'est 20 h quelque part. Trois fuseaux se croisent dans ce widget :

  • celui de l'administrateur qui saisit la date. Le site le connaît : nf_fuseau() rend celui que le membre a choisi dans son profil, sinon celui que son navigateur a annoncé, sinon celui du site ;
  • celui où le site enregistre ses dates : nf_fuseau_stockage() ;
  • celui de chaque visiteur, qui doit lire l'heure à la sienne.

Le checker convertit la saisie une fois, à l'enregistrement :

compte_a_rebours/controllers/checker.php

<?php
declare(strict_types=1);

namespace NF\Widgets\Compte_A_Rebours\Controllers;

use NF\NeoFrag\Loadables\Controller;

class Checker extends Controller
{
	/**
	 * Ce que l'administrateur a saisi, prêt à enregistrer. Le checker ne sert qu'à l'ENREGISTREMENT : c'est donc ici,
	 * une fois, que l'heure saisie passe dans le fuseau d'enregistrement du site.
	 */
	public function index($settings = [])
	{
		$settings = (array) $settings + ['evenement' => '', 'quand' => '', 'message_fin' => ''];

		return [
			'evenement'   => trim((string) $settings['evenement']),
			'quand'       => $this->_quand((string) $settings['quand']),
			'message_fin' => trim((string) $settings['message_fin'])
		];
	}

	/**
	 * « 2026-12-24T20:00 », comme l'envoie le champ `datetime-local`, lu à l'heure de celui qui le saisit, rendu à
	 * l'heure d'enregistrement : « 2026-12-24 19:00:00 » si le site enregistre en UTC et que l'administrateur est à
	 * Paris. Ce qui n'est pas une date valable devient vide.
	 */
	private function _quand(string $saisie): string
	{
		$saisie = str_replace('T', ' ', trim($saisie));

		// Relue puis réécrite, la date doit redonner la saisie : le 31 février deviendrait sinon le 3 mars.
		$date = \DateTime::createFromFormat('!Y-m-d H:i', $saisie);

		if (!$date || $date->format('Y-m-d H:i') !== $saisie)
		{
			return '';
		}

		return (string) nf_heure_saisie($saisie.':00');
	}
}
  • Le champ datetime-local envoie « 2026-12-24T20:00 » : une date et une heure, sans fuseau.
  • La date est relue puis réécrite, et doit redonner la saisie. Sans ce contrôle, PHP accepte le 31 février et en fait le 3 mars.
  • nf_heure_saisie() lit l'heure dans le fuseau de celui qui la saisit, et la rend dans le fuseau d'enregistrement.
  • Pourquoi dans le checker ? Parce que le site ne l'appelle qu'à l'enregistrement du formulaire. Il l'appelle aussi avec des réglages vides, pour connaître les valeurs par défaut : une chaîne vide reste vide.

Le formulaire fait le chemin inverse, pour montrer à l'administrateur l'heure qu'il a saisie :

compte_a_rebours/controllers/admin.php

<?php
declare(strict_types=1);

namespace NF\Widgets\Compte_A_Rebours\Controllers;

use NF\NeoFrag\Loadables\Controller;

class Admin extends Controller
{
	public function index($settings = [])
	{
		$settings = (array) $settings + ['evenement' => '', 'quand' => '', 'message_fin' => ''];

		// L'heure enregistrée, ramenée à celle de l'administrateur, au format du champ : « 2026-12-24T20:00 ».
		$quand = $settings['quand'] !== '' ? substr(str_replace(' ', 'T', (string) nf_heure_affichee($settings['quand'])), 0, 16) : '';

		return $this->view('admin', [
			'evenement'   => $settings['evenement'],
			'quand'       => $quand,
			'message_fin' => $settings['message_fin'],
			'fuseau'      => nf_fuseau()->getName()
		]);
	}
}

compte_a_rebours/views/admin.tpl.php

<div class="nf-field row">
	<label for="settings-evenement" class="col-12 col-lg-4 col-form-label"><?php echo $this->lang('Événement') ?></label>
	<div class="col-12 col-lg-8">
		<input class="form-control" type="text" name="settings[evenement]" id="settings-evenement" value="<?php echo nf_texte($evenement) ?>">
		<div class="form-text"><?php echo $this->lang('Le titre du widget.') ?></div>
	</div>
</div>
<div class="nf-field row">
	<label for="settings-quand" class="col-12 col-lg-4 col-form-label"><?php echo $this->lang('Date et heure') ?></label>
	<div class="col-12 col-lg-8">
		<input class="form-control" type="datetime-local" name="settings[quand]" id="settings-quand" value="<?php echo nf_texte($quand) ?>">
		<div class="form-text"><?php echo $this->lang('À ton heure (%s) : chaque visiteur verra la sienne.', nf_texte($fuseau)) ?></div>
	</div>
</div>
<div class="nf-field row">
	<label for="settings-message-fin" class="col-12 col-lg-4 col-form-label"><?php echo $this->lang('Message une fois l\'heure passée') ?></label>
	<div class="col-12 col-lg-8">
		<input class="form-control" type="text" name="settings[message_fin]" id="settings-message-fin" value="<?php echo nf_texte($message_fin) ?>" placeholder="<?php echo nf_texte($this->lang('L\'événement a commencé.')) ?>">
	</div>
</div>

nf_heure_affichee() ramène l'heure enregistrée dans le fuseau de l'administrateur ; le T et les seize premiers caractères la mettent au format du champ. Sans cette conversion, le formulaire montrerait l'heure enregistrée, et chaque nouvel enregistrement la décalerait de l'écart entre les deux fuseaux.

Étape 3 — Le contrôleur : un instant, pas une heure

compte_a_rebours/controllers/index.php

<?php
declare(strict_types=1);

namespace NF\Widgets\Compte_A_Rebours\Controllers;

use NF\NeoFrag\Loadables\Controllers\Widget as Controller_Widget;

class Index extends Controller_Widget
{
	public function index($settings = [])
	{
		// L'heure enregistrée se lit dans le fuseau d'ENREGISTREMENT du site : c'est le sien.
		$quand = (string) ($settings['quand'] ?? '');
		$cible = $quand !== '' ? date_create($quand, nf_fuseau_stockage()) : FALSE;

		$this->css('compte_a_rebours')->js('compte_a_rebours');

		return $this->panel()
					->heading(($settings['evenement'] ?? '') ?: $this->lang('Compte à rebours'), 'fas fa-hourglass-half')
					->body($this->view('index', [
						'quand'       => $cible ? $quand : '',
						// Un instant, et non une heure : des millisecondes depuis 1970, les mêmes partout sur Terre. Le
						// navigateur de chaque visiteur compte à partir de là, quel que soit son fuseau.
						'cible'       => $cible ? $cible->getTimestamp() * 1000 : 0,
						'iso'         => $cible ? $cible->format(DATE_ATOM) : '',
						'passe'       => $cible && $cible->getTimestamp() <= time(),
						'message_fin' => ($settings['message_fin'] ?? '') ?: $this->lang('L\'événement a commencé.'),
						// Les mots des unités dans la langue de la page, au singulier puis au pluriel : le navigateur
						// choisira, pour chaque nombre, selon les règles de cette langue.
						'unites'      => [
							'jours'    => $this->lang('jour').'|'.$this->lang('jours'),
							'heures'   => $this->lang('heure').'|'.$this->lang('heures'),
							'minutes'  => $this->lang('minute').'|'.$this->lang('minutes'),
							'secondes' => $this->lang('seconde').'|'.$this->lang('secondes')
						]
					]));
	}
}
  • date_create($quand, nf_fuseau_stockage()) lit la date enregistrée dans son fuseau, et en fait un instant.
  • getTimestamp() * 1000 : cet instant en millisecondes depuis 1970. C'est le même nombre à Paris, à Montréal et à Tokyo : le navigateur de chaque visiteur n'a qu'à le comparer à son horloge.
  • DATE_ATOM donne l'instant sous une forme que les machines lisent (2030-12-24T19:00:00+00:00), pour la balise <time>.
  • $this->css(…)->js(…) charge css/compte_a_rebours.css et js/compte_a_rebours.js, pris dans le dossier du widget.
  • Les mots des unités sont traduits par le site, comme tout texte, puis confiés au navigateur : « jour|jours ».

Étape 4 — La vue

compte_a_rebours/views/index.tpl.php

<?php if (!$quand): ?>
	<p class="car-vide"><?php echo $this->lang('Aucune date réglée : ouvre les réglages du widget.') ?></p>
<?php else: ?>
	<div class="car" data-cible="<?php echo $cible ?>" data-fin="<?php echo nf_texte($message_fin) ?>"<?php foreach ($unites as $unite => $mots) echo ' data-'.$unite.'="'.nf_texte($mots).'"' ?>>
		<p class="car-date"><i class="far fa-calendar"></i> <time datetime="<?php echo $iso ?>"><?php echo nf_date_heure($quand) ?></time></p>
		<?php if ($passe): ?>
			<p class="car-fin"><?php echo nf_texte($message_fin) ?></p>
		<?php else: ?>
			<div class="car-compteur" role="timer" hidden></div>
		<?php endif ?>
	</div>
<?php endif ?>
  • Le script ne porte aucune donnée : tout passe par les attributs data- de la page. Un même fichier sert ainsi chaque compte à rebours de la page, et le navigateur le garde en cache.
  • nf_texte() protège chaque valeur écrite dans un attribut.
  • nf_date_heure() écrit la date dans le fuseau du visiteur et au format de sa langue (« 24/12/2030 20:00 » en français). Jamais date(), qui écrirait l'heure du serveur.
  • Le compteur est hidden : seul le script le montre, une fois rempli. Sans JavaScript, le visiteur lit la date, jamais des cases vides.
  • role="timer" dit aux lecteurs d'écran que ce bloc est un minuteur : ils ne lisent pas chaque seconde à voix haute.
  • Si l'heure est déjà passée quand la page est servie, le message s'affiche directement.

Étape 5 — Le script

compte_a_rebours/js/compte_a_rebours.js

// Compte à rebours : chaque seconde, le temps qui reste jusqu'à `data-cible`, un instant en millisecondes.
NF.ready(function(){
	// Les règles du pluriel de la langue de la page : en français, 0 et 1 sont au singulier ; en anglais, 1 seulement.
	var regles = new Intl.PluralRules(document.documentElement.lang || 'fr');

	document.querySelectorAll('.car[data-cible]').forEach(function(car){
		var cible    = parseInt(car.getAttribute('data-cible'), 10);
		var compteur = car.querySelector('.car-compteur');

		if (!compteur || !cible)
		{
			return;
		}

		// Quatre blocs : le nombre, et le mot de son unité.
		var blocs = ['jours', 'heures', 'minutes', 'secondes'].map(function(unite){
			var bloc   = document.createElement('span');
			var nombre = document.createElement('b');
			var mot    = document.createElement('small');

			bloc.className   = 'car-bloc';
			nombre.className = 'car-nombre';
			mot.className    = 'car-unite';
			bloc.append(nombre, mot);
			compteur.append(bloc);

			return {nombre: nombre, mot: mot, formes: (car.getAttribute('data-' + unite) || '').split('|')};
		});

		var minuterie = setInterval(afficher, 1000);

		function afficher()
		{
			var reste   = Math.max(0, Math.floor((cible - Date.now()) / 1000));
			var valeurs = [Math.floor(reste / 86400), Math.floor(reste % 86400 / 3600), Math.floor(reste % 3600 / 60), reste % 60];

			valeurs.forEach(function(n, i){
				// textContent, jamais innerHTML : ce qu'on écrit reste du texte.
				blocs[i].nombre.textContent = i ? String(n).padStart(2, '0') : String(n);
				blocs[i].mot.textContent    = blocs[i].formes[regles.select(n) === 'one' ? 0 : 1] || '';
			});

			if (!reste)
			{
				clearInterval(minuterie);

				var fin = document.createElement('p');
				fin.className   = 'car-fin';
				fin.textContent = car.getAttribute('data-fin');
				compteur.replaceWith(fin);
			}
		}

		afficher();
		compteur.hidden = false;
	});
});
  • NF.ready() attend que la page soit prête : c'est l'outil du site, à la place de jQuery, qui n'est plus chargé.
  • Intl.PluralRules connaît les règles de pluriel de chaque langue. En français, 0 et 1 sont au singulier (« 0 jour », « 1 jour ») ; en anglais, seul 1 l'est (« 0 days », « 1 day »). La langue est celle de la page, que le site écrit sur la balise <html lang="…">.
  • textContent, jamais innerHTML : le message de fin, écrit par un administrateur, reste du texte, quoi qu'il contienne.
  • À chaque seconde, le reste est recalculé à partir de l'instant visé, au lieu d'enlever 1 au compteur. Un navigateur ralentit les minuteries d'un onglet en arrière-plan : un compteur qui compterait ses secondes prendrait du retard ; celui-ci se recale au tic suivant.
  • À zéro, la minuterie s'arrête, et le message de fin prend la place du compteur.

Un script chargé par ->js() est un fichier du site : la politique de sécurité (CSP) l'accepte sans rien ajouter.

Étape 6 — La feuille de style

compte_a_rebours/css/compte_a_rebours.css

.car-date {
	margin: 0 0 .75rem;
	color: var(--nf-text-muted);
}

.car-compteur {
	display: grid;
	grid-template-columns: repeat(4, 1fr);
	gap: .5rem;
	text-align: center;
}

.car-bloc {
	display: flex;
	flex-direction: column;
	padding: .6rem .25rem;
	border-radius: .6rem;
	background: color-mix(in srgb, var(--nf-accent) 12%, transparent);
}

/* Des chiffres de même largeur : le compteur ne tremble pas d'une seconde à l'autre. */
.car-nombre {
	font-size: 1.6rem;
	line-height: 1.1;
	font-variant-numeric: tabular-nums;
	color: var(--nf-text-strong);
}

.car-unite {
	font-size: .75rem;
	color: var(--nf-text-muted);
}

.car-fin {
	margin: 0;
	font-weight: 600;
	color: var(--nf-accent);
}

.car-vide {
	margin: 0;
	color: var(--nf-text-muted);
}
  • font-variant-numeric: tabular-nums donne à tous les chiffres la même largeur : sans lui, le compteur tremble à chaque seconde, un « 1 » étant plus étroit qu'un « 8 ».
  • Les couleurs viennent du thème (--nf-accent, --nf-text-muted…) : le widget prend celles de chaque thème, en clair comme en sombre.

Étape 7 — Les traductions

Dix-sept textes, dans les six fichiers de langs/. Chaque unité y est deux fois, au singulier et au pluriel : « jour » et « jours », « heure » et « heures »… L'archive les porte.

Installer le widget

  1. Compresse le dossier compte_a_rebours, puis Thèmes & addons → Ajouter. Le site répond « Le widget Compte à rebours a été installé ».
  2. Ouvre l'éditeur en direct, ajoute Compte à rebours à une zone, et règle l'événement, la date et le message de fin. Enregistre.
  3. Le widget compte. Ouvre la page dans une autre langue (/en/…) : les unités suivent, avec leurs pluriels.

Sur la capture du haut, la date a été saisie pour 20 h sur un site réglé en UTC, puis la page ouverte par un navigateur réglé sur Paris : il affiche 21 h. Le temps qui reste, lui, est le même pour tous.

Si ça ne marche pas

Ce que tu vois Ce que ça veut dire
La date, mais pas de compteur Le script ne tourne pas : ->js('compte_a_rebours') manque, le fichier n'est pas dans js/, ou il a une erreur (la console du navigateur, touche F12, la montre).
L'heure se décale à chaque enregistrement Le formulaire montre l'heure enregistrée sans nf_heure_affichee().
« Aucune date réglée » après l'enregistrement La date n'existe pas (un 31 février), ou le champ ne s'appelle pas settings[quand].
Le compteur saute des secondes dans un onglet en arrière-plan C'est le navigateur qui ralentit l'onglet. Le compteur se recale dès qu'on y revient.

Pour aller plus loin

  • La prochaine date du module Événements : un deuxième type qui la lit dans la base, en déclarant le module dans requires, comme « Astuce du jour » déclare le sien.
  • Ajouter à mon agenda : un bouton qui fabrique, dans le navigateur, un fichier .ics à partir de data-cible.

C'est le dernier widget de la série : le tutoriel expert des thèmes termine « Aube ».


Atividade do fórum
Há 0 utilizador no fórum
sem visitantes
Estatísticas
  • 72 tópicos criados
  • 0 mensagem postada
  • 63 anúncios
  • 1 participante

Gerir os meus cookies

O site só instala os cookies necessários ao seu funcionamento: não exigem o seu consentimento. Os outros serviços pertencem a outras empresas; só são carregados se os aceitar. A sua escolha é guardada durante seis meses, e pode alterá-la a qualquer momento.

Necessários ao site Sempre ativos

  • __Host-session Mantém a sua sessão iniciada e protege os formulários contra envios fraudulentos. Até fechar o navegador; um ano com «Lembrar-me»
  • nf_consent Guarda as escolhas que faz nesta janela. 6 meses
  • nf_fuseau Mostra as datas e as horas no seu fuso horário. 1 ano
  • Armazenamento do navegador Guarda a sua escolha entre o modo dia e o modo noite, e a apresentação escolhida para a lista de artigos. Até que o limpe

Vídeos

Os vídeos integrados nas páginas: o leitor vem da plataforma, que recebe o seu endereço IP e pode instalar os seus cookies.

Música

As faixas e listas de reprodução integradas nas páginas: o leitor vem da plataforma, que recebe o seu endereço IP e pode instalar os seus cookies.