0 visualização
Tutorial Un widget à plusieurs visages : « Bienvenue » 2.0
Mensagem por ler

Niveau intermédiaire · environ 1 heure · NeoFrag Reborn 1.2.50 ou plus récent

Ce tutoriel reprend le widget « Bienvenue » du niveau débutant et le fait grandir. À la fin, il a :

  • deux présentations au choix — le message de bienvenue, ou une carte du membre ;
  • un réglage vérifié : l'alignement du message, qu'aucun formulaire trafiqué ne peut détourner ;
  • un regard sur un autre module : la carte compte les messages non lus de la Messagerie, si elle est installée, sans jamais en dépendre ;
  • un pluriel correct dans les six langues ;
  • une mise à jour propre : les widgets déjà posés gardent leur message.

Le message, centré

La carte, pour un visiteur

La carte, pour un membre connecté

Il te faut le widget de Mon premier widget (ou son archive, bienvenue-1.0.0.zip), installé sur un site d'essai. L'archive de ce tutoriel, bienvenue-2.0.0.zip, est jointe à ce sujet.

Étape 1 — Deux présentations : les types

Un widget peut proposer plusieurs types : l'administrateur choisit le sien en posant le widget. Ils se déclarent dans la carte d'identité :

bienvenue/bienvenue.php

<?php
declare(strict_types=1);
/**
 * Bienvenue — le widget des tutoriels « Mon premier widget » (débutant) et « Un widget à plusieurs visages »
 * (intermédiaire). LGPLv3.
 */

namespace NF\Widgets\Bienvenue;

use NF\NeoFrag\Addons\Widget;

class Bienvenue extends Widget
{
	protected function __info()
	{
		return [
			'title'       => $this->lang('Bienvenue'),
			'description' => $this->lang('Salue le membre connecté par son pseudo, les visiteurs par le nom du site, et ajoute le message de ton choix.'),
			'icon'        => 'fas fa-hand-spock',
			'link'        => 'https://neofrag-reborn.xyz',
			'author'      => 'NeoFrag Reborn',
			'license'     => 'LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>',
			'version'     => '2.0.0',
			'depends'     => [
				'neofrag' => '1.2.50'
			],
			'core'        => FALSE,
			'presets'     => [],
			'requires'    => [],
			'types'       => [
				'index' => $this->lang('Message de bienvenue'),
				'carte' => $this->lang('Carte du membre')
			]
		];
	}
}

Deux choses changent : 'version' passe à '2.0.0', et types nomme les présentations. La clé (index, carte) est le nom d'une méthode du contrôleur ; le texte est ce que l'administrateur lit. Dès qu'un widget a plusieurs types, la fenêtre Nouveau Widget de l'éditeur en direct ajoute l'étape Type.

Le contrôleur a donc une méthode par type :

bienvenue/controllers/index.php

<?php
declare(strict_types=1);

namespace NF\Widgets\Bienvenue\Controllers;

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

class Index extends Controller_Widget
{
	/** Le type « Message de bienvenue » : la salutation, et le message réglé. */
	public function index($settings = [])
	{
		// Un membre connecté est salué par son pseudo, un visiteur par le nom du site. `&nbsp;` : l'espace
		// insécable de la typographie française, qui garde le « ! » sur la ligne du nom.
		if ($this->user())
		{
			$salut = $this->lang('Bonjour %s&nbsp;!', $this->user->username);
		}
		else
		{
			$salut = $this->lang('Bienvenue sur %s&nbsp;!', $this->config->nf_name);
		}

		$this->css('bienvenue');

		return $this->panel()
					->heading()
					->body($this->view('index', [
						'salut'      => $salut,
						'message'    => $settings['message'] ?? '',
						'alignement' => $settings['alignement'] ?? 'text-start'
					]));
	}

	/** Le type « Carte du membre » : l'avatar et les raccourcis d'un membre, ou de quoi se connecter. */
	public function carte($settings = [])
	{
		$this->css('bienvenue');

		if (!$this->user())
		{
			return $this->panel()
						->heading()
						->body($this->view('carte-visiteur', [
							'inscriptions' => (bool) $this->config->nf_registration_status
						]));
		}

		// La messagerie est un AUTRE module : il peut ne pas être installé, ou être désactivé. On la consulte
		// quand elle est là, sans jamais en dépendre — sans elle, la ligne des messages ne s'affiche pas.
		$non_lus = 0;

		if (($messagerie = $this->module('talks')) && $messagerie->is_enabled())
		{
			$non_lus = (int) $messagerie->model('talks')->get_unread_count((int) $this->user->id);
		}

		return $this->panel()
					->heading()
					->body($this->view('carte-membre', [
						'non_lus' => $non_lus
					]));
	}
}

index() est celle du débutant, avec un réglage de plus, alignement. carte() est nouvelle :

  • pour un visiteur, elle montre de quoi se connecter, et le bouton d'inscription seulement si les inscriptions sont ouvertes ($this->config->nf_registration_status) ;
  • pour un membre, son avatar ($this->user->avatar()), un lien vers son espace, et ses messages non lus.

Les deux vues de la carte :

bienvenue/views/carte-visiteur.tpl.php

<p class="bienvenue-message"><?php echo $this->lang('Connecte-toi pour retrouver ton espace et tes messages.') ?></p>
<div class="bienvenue-boutons">
	<a class="btn btn-primary btn-sm" href="<?php echo url('user/login') ?>"><?php echo $this->lang('Connexion') ?></a>
	<?php if ($inscriptions): ?>
		<a class="btn btn-outline-secondary btn-sm" href="<?php echo url('user/registration') ?>"><?php echo $this->lang('Inscription') ?></a>
	<?php endif ?>
</div>

bienvenue/views/carte-membre.tpl.php

<div class="bienvenue-carte">
	<?php echo $this->user->avatar() ?>
	<div class="bienvenue-carte-texte">
		<p class="bienvenue-salut"><?php echo nf_texte($this->user->username) ?></p>
		<a href="<?php echo url('user') ?>"><i class="fas fa-house-user"></i> <?php echo $this->lang('Mon espace') ?></a>
		<?php if ($non_lus > 0): ?>
			<a class="bienvenue-non-lus" href="<?php echo url('talks') ?>">
				<i class="far fa-envelope"></i> <?php echo $this->lang('Tu as %d message non lu|Tu as %d messages non lus', $non_lus, $non_lus) ?>
			</a>
		<?php endif ?>
	</div>
</div>

Étape 2 — Regarder un autre module sans en dépendre

Les messages non lus appartiennent à la Messagerie, un module que ton site n'a peut-être pas : on l'installe ou non, on peut le désactiver. Il y a deux façons d'en avoir besoin, et elles ne disent pas la même chose :

Ce que tu écris Si la Messagerie manque
Dépendance 'requires' => ['talks'] dans bienvenue.php le widget ne s'affiche plus du tout, l'éditeur ne le propose plus, et « Ajouter » refuse de l'installer
Regard $this->module('talks'), puis is_enabled() le widget s'affiche, sans la ligne des messages

Ici, les messages sont un plus : la carte sert sans eux. C'est donc un regard. $this->module('talks') rend le module s'il est installé, NULL sinon ; is_enabled() dit s'il est activé. Ce n'est qu'après ces deux questions qu'on appelle son modèle (get_unread_count()).

Ne lis jamais directement la table d'un autre module (nf_talks_…) depuis ton widget : sans le module, la table n'existe pas, et la page tombe.

Étape 3 — Un réglage vérifié

Le formulaire de réglages gagne une liste déroulante, l'alignement :

bienvenue/controllers/admin.php

<?php
declare(strict_types=1);

namespace NF\Widgets\Bienvenue\Controllers;

use NF\NeoFrag\Loadables\Controller;

class Admin extends Controller
{
	/** Les réglages du type « Message de bienvenue ». La carte n'en a pas : pas de méthode `carte()` ici. */
	public function index($settings = [])
	{
		$settings = (array) $settings + ['message' => '', 'alignement' => 'text-start'];

		return $this->view('admin', [
			'message'     => $settings['message'],
			'alignement'  => $settings['alignement'],
			'alignements' => [
				'text-start'  => $this->lang('À gauche'),
				'text-center' => $this->lang('Au centre'),
				'text-end'    => $this->lang('À droite')
			]
		]);
	}
}

bienvenue/views/admin.tpl.php

<div class="nf-field row">
	<label for="settings-message" class="col-12 col-lg-4 col-form-label"><?php echo $this->lang('Message') ?></label>
	<div class="col-12 col-lg-8">
		<textarea class="form-control" name="settings[message]" id="settings-message" rows="3"><?php echo nf_texte($message) ?></textarea>
		<div class="form-text"><?php echo $this->lang('Laisse vide pour n\'afficher que la salutation.') ?></div>
	</div>
</div>
<div class="nf-field row">
	<label for="settings-alignement" class="col-12 col-lg-4 col-form-label"><?php echo $this->lang('Alignement') ?></label>
	<div class="col-12 col-lg-8">
		<select class="form-select" name="settings[alignement]" id="settings-alignement">
			<?php foreach ($alignements as $valeur => $libelle): ?>
				<option value="<?php echo $valeur ?>"<?php echo $valeur === $alignement ? ' selected' : '' ?>><?php echo $libelle ?></option>
			<?php endforeach ?>
		</select>
	</div>
</div>

Il n'y a pas de méthode carte() ici : la carte n'a rien à régler, et l'éditeur en direct saute alors l'étape Configuration pour ce type.

Le checker vérifie ce qui arrive :

bienvenue/controllers/checker.php

<?php
declare(strict_types=1);

namespace NF\Widgets\Bienvenue\Controllers;

use NF\NeoFrag\Loadables\Controller;

class Checker extends Controller
{
	/** Les alignements permis, et celui qu'on prend quand rien n'est réglé (le premier). */
	const ALIGNEMENTS = ['text-start', 'text-center', 'text-end'];

	public function index($settings = [])
	{
		// Le widget peut arriver sans réglage : la valeur par défaut d'abord, puis ce qui a été saisi.
		$settings = (array) $settings + ['message' => '', 'alignement' => ''];

		return [
			'message'    => trim((string) $settings['message']),
			// Une valeur qui n'est pas dans la liste — un formulaire trafiqué, un réglage d'une autre version —
			// est remplacée par celle par défaut : la vue ne reçoit jamais qu'une classe connue.
			'alignement' => in_array($settings['alignement'], self::ALIGNEMENTS, TRUE) ? $settings['alignement'] : self::ALIGNEMENTS[0]
		];
	}

	public function carte($settings = [])
	{
		// Rien à régler : la carte montre ce qui concerne le visiteur.
		return [];
	}
}

Une liste déroulante ne propose que trois valeurs, mais rien n'empêche d'envoyer autre chose : un formulaire se modifie dans le navigateur en deux clics. Le checker n'accepte qu'une valeur de sa liste ; pour toute autre, il prend celle par défaut. La vue reçoit ainsi toujours une classe connue :

bienvenue/views/index.tpl.php

<div class="bienvenue <?php echo nf_texte($alignement) ?>">
	<p class="bienvenue-salut"><i class="fas fa-hand-spock"></i> <?php echo nf_texte($salut) ?></p>
	<?php if ($message !== ''): ?>
		<p class="bienvenue-message"><?php echo nl2br(nf_texte($message)) ?></p>
	<?php endif ?>
</div>

Et pour la carte, carte() rend un tableau vide : rien à vérifier, mais la méthode dit que le type existe.

Étape 4 — Le pluriel

La carte écrit « Tu as 3 messages non lus », ou « Tu as 1 message non lu ». Une seule phrase s'en charge, ses deux formes séparées par une barre verticale :

$this->lang('Tu as %d message non lu|Tu as %d messages non lus', $non_lus, $non_lus)

Le premier nombre choisit la forme — la première jusqu'à 1, la seconde au-delà — et il est consommé par ce choix. Le second remplace le %d. D'où le nombre écrit deux fois. Chaque traduction garde ses deux formes : « You have %d unread message|You have %d unread messages ».

Étape 5 — Les traductions, pour de vrai

Au niveau débutant, tu as copié le dossier langs de l'archive. Voici comment il se fabrique. Chaque texte que le widget passe à $this->lang() a une clé : l'empreinte CRC32 de son texte français, en huit caractères. Pour « Carte du membre » :

php -r "echo hash('crc32b', 'Carte du membre');"
e3491a18

Chaque fichier de langue associe ces clés à leur traduction. Voici l'allemand, langs/de.php :

bienvenue/langs/de.php

<?php
declare(strict_types=1);

return [
	'650a65c7' => 'Willkommen', // Bienvenue
	'0d0759dd' => 'Begrüßt das angemeldete Mitglied mit seinem Benutzernamen, Besucher mit dem Namen der Website, und fügt die Nachricht deiner Wahl hinzu.', // Salue le membre connecté par son pseudo, les visiteurs par le nom du site, et ajoute le message de ton choix.
	'b0987800' => 'Hallo %s!', // Bonjour %s&nbsp;!
	'fb0c89ac' => 'Willkommen auf %s!', // Bienvenue sur %s&nbsp;!
	'790009e3' => 'Nachricht', // Message
	'0a536731' => 'Leer lassen, um nur die Begrüßung anzuzeigen.', // Laisse vide pour n'afficher que la salutation.
	'7cd49724' => 'Begrüßungsnachricht', // Message de bienvenue
	'e3491a18' => 'Mitgliedskarte', // Carte du membre
	'e17afcad' => 'Ausrichtung', // Alignement
	'cceaa7d5' => 'Links', // À gauche
	'738fee54' => 'Zentriert', // Au centre
	'b97a5759' => 'Rechts', // À droite
	'b6a189c8' => 'Mein Bereich', // Mon espace
	'173f7fae' => 'Du hast %d ungelesene Nachricht|Du hast %d ungelesene Nachrichten', // Tu as %d message non lu|Tu as %d messages non lus
	'be1a3174' => 'Melde dich an, um deinen Bereich und deine Nachrichten wiederzufinden.', // Connecte-toi pour retrouver ton espace et tes messages.
	'119a7b3f' => 'Anmelden', // Connexion
	'd80c7901' => 'Registrierung', // Inscription
];
  • La clé dépend du texte exact, espaces et accents compris : change une virgule dans le texte français, et sa traduction n'est plus trouvée. Le site affiche alors le français, sans rien casser — mais pense à recalculer la clé.
  • Les commentaires (// Carte du membre) ne servent qu'à toi : ils rappellent de quel texte il s'agit.
  • fr.php porte les textes français eux-mêmes. Le site n'en a pas besoin pour afficher le français, mais c'est la liste de référence de ce qu'il y a à traduire.
  • Ce que tu saisis dans un réglage — le message — n'est pas traduit : c'est ton texte.

Étape 6 — La mise à jour

Compresse le dossier bienvenue et envoie-le par Thèmes & addons → Ajouter. Comme la version de l'archive (2.0.0) est plus récente que celle installée (1.0.0), le site répond « Le widget Bienvenue a été mis à jour ».

Les widgets déjà posés gardent leur message. Ils n'ont pas encore de réglage alignement : le site le complète avec la valeur que rend le checker pour des réglages vides, text-start. C'est pourquoi un checker doit toujours savoir partir de rien.

Pour poser la carte : Éditeur en direct → + dans une colonne → Bienvenue → étape Type → Carte du membre.

Si ça ne marche pas

Ce que tu vois Ce que ça veut dire
« Le widget Bienvenue est déjà installé en version 2.0.0 » La version de l'archive n'est pas plus récente que celle installée.
L'étape Type n'apparaît pas types manque dans bienvenue.php, ou l'archive envoyée est encore l'ancienne.
La carte ne s'affiche pas La méthode carte() manque au contrôleur, ou son nom diffère de la clé de types.
La ligne des messages n'apparaît jamais La Messagerie n'est pas installée ou est désactivée — ou tu n'as aucun message non lu.
Le texte reste en français sur le site en anglais Sa clé ne correspond plus à son texte : recalcule-la.

Pour aller plus loin

  • Ajoute un troisième type, « Les membres en ligne » : une méthode de plus, une entrée de plus dans types.
  • La documentation du site, guide Créer un widget, décrit le JavaScript dans un widget : c'est l'objet du tutoriel expert, un compte à rebours qui avance seconde par seconde.

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.