Derniers messages
Derniers sujets
Tutoriel Un widget à plusieurs visages : « Bienvenue » 2.0
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.



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. ` ` : 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 !', $this->user->username);
}
else
{
$salut = $this->lang('Bienvenue sur %s !', $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 !
'fb0c89ac' => 'Willkommen auf %s!', // Bienvenue sur %s !
'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.phpporte 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.

Activité du forum
2 visiteurs
Statistiques
- 72 sujets créés
- 0 message posté
- 63 annonces
- 1 participant