Neueste Beiträge
Neueste Themen
Anleitung Mon premier widget : « Bienvenue »
Niveau débutant · environ 30 minutes · NeoFrag Reborn 1.2.50 ou plus récent
Un widget, c'est un bloc que tu poses où tu veux sur ton site avec l'éditeur en direct : la colonne de droite, le haut de l'accueil, le pied de page. Le site en a déjà une quarantaine (le forum, les membres en ligne, le calendrier…). Dans ce tutoriel, tu écris le tien, de zéro, et tu l'installes sur ton site.
Ce que tu vas construire : un bloc qui salue le visiteur par le nom du site, le membre connecté par son pseudo, et qui ajoute un message que tu choisis.
L'archive terminée, bienvenue-1.0.0.zip, est jointe à ce sujet : si tu bloques, compare tes fichiers aux siens.
Ce qu'il te faut
- un site NeoFrag Reborn sur lequel tu es administrateur — un site d'essai de préférence, pas ton site en ligne ;
- un éditeur de texte qui enregistre en UTF-8 : VS Code, Notepad++, Sublime Text… (pas le Bloc-notes de Windows, ni un traitement de texte) ;
- de quoi faire une archive .zip : le clic droit de ton système suffit.
Pas besoin de savoir programmer : chaque fichier est donné en entier, et chaque ligne qui compte est expliquée. Tu n'as pas non plus besoin d'accès FTP : le widget s'installe depuis l'administration.
Étape 1 — Le dossier
Un widget est un dossier. Son nom est le nom du widget : des lettres minuscules, des chiffres et des _, rien
d'autre. Crée un dossier bienvenue où tu veux sur ton ordinateur. À la fin du tutoriel, il contiendra ceci :
bienvenue/
├── bienvenue.php la carte d'identité du widget
├── controllers/
│ ├── index.php ce que le widget affiche
│ ├── admin.php son formulaire de réglages
│ └── checker.php le gardien de ses réglages
├── views/
│ ├── index.tpl.php le HTML du widget
│ └── admin.tpl.php le HTML du formulaire
├── css/
│ └── bienvenue.css son style
├── langs/ ses traductions (fr, en, de, es, it, pt)
└── images/
└── thumbnail.jpg sa vignette dans « Thèmes & addons » (facultative)
Crée les sous-dossiers controllers, views et css tout de suite ; on remplit le reste au fil des étapes.
Étape 2 — La carte d'identité
Le premier fichier porte le nom du dossier : bienvenue.php. Il dit au site qui est ce widget.
bienvenue/bienvenue.php
<?php
declare(strict_types=1);
/**
* Bienvenue — le widget du tutoriel « Mon premier widget » (niveau débutant). 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' => '1.0.0',
'depends' => [
'neofrag' => '1.2.50'
],
'core' => FALSE,
'presets' => [],
'requires' => []
];
}
}
Ce qui compte, ligne par ligne :
namespace NF\Widgets\Bienvenue;— le nom du dossier, avec une majuscule. Un widgetma_meteoauraitNF\Widgets\Ma_meteo, et sa classe s'appelleraitMa_meteo.use NF\NeoFrag\Addons\Widget;— c'est à cette ligne, exactement, que l'installeur reconnaît un widget. Ne la change pas.titleetdescription— ce que l'administrateur lit dans « Thèmes & addons » et dans l'éditeur en direct. Ils passent par$this->lang(…), pour être traduits (étape 8).icon— une icône de Font Awesome 7, que le site embarque. Choisis une icône gratuite, et écris-la avec son style :fas fa-…pour une icône pleine.versionetdepends— obligatoires pour installer par une archive.dependsdit de quelle version du site le widget a besoin : sur un site plus ancien, l'installeur refuse, avec un message qui le dit.core,presets,requires— pour un widget à toi, toujoursFALSE,[]et[]. Ils servent aux addons livrés avec le site.
Étape 3 — Ce que le widget affiche
Le contrôleur prépare ce qu'on montre. Crée controllers/index.php :
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
{
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'] ?? ''
]));
}
}
$this->user()est vrai quand le visiteur est connecté ; son pseudo est alors$this->user->username.$this->config->nf_name, c'est le nom de ton site, celui des Paramètres.$this->lang('Bonjour %s !', …): le%sest remplacé par ce qui suit — le pseudo.$this->css('bienvenue')chargecss/bienvenue.css(étape 5).$this->panel()->heading()->body(…)range le tout dans un panneau, le cadre que tous les widgets partagent : son titre est celui du widget, que l'administrateur pourra changer en le posant, et le thème du site l'habille.$settings['message'] ?? '': le message, qu'on rendra réglable à l'étape 6. Tant qu'il n'existe pas, il vaut « rien ».
Étape 4 — Le HTML
La vue est le HTML du widget, avec quelques morceaux de PHP. Crée views/index.tpl.php :
bienvenue/views/index.tpl.php
<div class="bienvenue">
<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>
$salut et $message sont les deux valeurs que le contrôleur a passées à view().
Tout texte posé dans la page passe par nf_texte(). Un pseudo peut contenir un < ; un message écrit dans
l'administration aussi. Sans nf_texte(), ce texte deviendrait du HTML — et un pseudo bien choisi deviendrait un
script, servi à tous tes visiteurs. nf_texte() l'affiche tel qu'il a été écrit, accents compris. (Si tu as déjà
vu htmlspecialchars() ailleurs : sur NeoFrag Reborn, il ferait apparaître é à la place des « é » des
textes enregistrés par le site.)
nl2br() garde les retours à la ligne du message.
Étape 5 — Le style
Crée css/bienvenue.css :
bienvenue/css/bienvenue.css
.bienvenue-salut {
margin: 0;
font-size: 1.15rem;
font-weight: 600;
color: var(--nf-text-strong);
}
.bienvenue-salut i {
margin-right: .35rem;
color: var(--nf-accent);
}
.bienvenue-message {
margin: .5rem 0 0;
color: var(--nf-text-soft);
}
Aucune couleur n'est écrite en dur : var(--nf-text-strong), var(--nf-accent) et var(--nf-text-soft) sont
les couleurs du thème de ton site — le texte appuyé, la couleur d'accent, le texte discret. Tous les thèmes les
définissent, en clair comme en sombre : ton widget prend leurs couleurs sans que tu aies rien à faire. Un
color: #222 serait illisible sur un thème sombre.
Premier essai
Ton widget sait déjà s'afficher. Installe-le :
- Compresse le dossier
bienvenue: clic droit → Compresser (ou Envoyer vers → Dossier compressé sur Windows). Tu obtiensbienvenue.zip, avec le dossierbienvenueà l'intérieur. - Dans l'administration, ouvre Thèmes & addons, clique sur Ajouter, choisis ton
bienvenue.zip, puis Ajouter. Le site répond « Le widget Bienvenue a été installé ». - Ouvre l'Éditeur en direct, va sur la page où tu veux le widget, et clique sur le bouton + (Ajouter un widget) d'une colonne. Dans la fenêtre Nouveau Widget, choisis la carte Bienvenue (tape « bien » dans le filtre pour la trouver), laisse le titre vide pour garder « Bienvenue », et valide.
Le widget apparaît : « Bienvenue sur … ! » pour un visiteur, « Bonjour … ! » pour toi. Pas encore de message : c'est l'étape suivante.
Étape 6 — Un réglage : le message
Pour qu'un widget ait des réglages, il lui faut un formulaire. Crée controllers/admin.php :
bienvenue/controllers/admin.php
<?php
declare(strict_types=1);
namespace NF\Widgets\Bienvenue\Controllers;
use NF\NeoFrag\Loadables\Controller;
class Admin extends Controller
{
public function index($settings = [])
{
$settings = (array) $settings + ['message' => ''];
return $this->view('admin', [
'message' => $settings['message']
]);
}
}
et sa vue, views/admin.tpl.php :
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>
- Le champ s'appelle
settings[message]: tout champ nommésettings[…]devient un réglage du widget, que le contrôleur de l'étape 3 reçoit dans$settings. (array) $settings + ['message' => '']donne une valeur par défaut au réglage s'il n'existe pas encore — à la première ouverture du formulaire, par exemple.nf-field,col-12 col-lg-4… : les classes des formulaires du site. Le champ a la même allure que tous les autres, dans tous les thèmes.col-12 col-lg-4veut dire « toute la largeur sur un téléphone, un tiers sur un grand écran ».
Dès que ce contrôleur existe, l'éditeur en direct ajoute l'étape Configuration à la fenêtre du widget.
Étape 7 — Le gardien des réglages
Le checker reçoit ce qui a été saisi, avant l'enregistrement, et rend des réglages propres. Crée
controllers/checker.php :
bienvenue/controllers/checker.php
<?php
declare(strict_types=1);
namespace NF\Widgets\Bienvenue\Controllers;
use NF\NeoFrag\Loadables\Controller;
class Checker extends Controller
{
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' => ''];
return [
'message' => trim((string) $settings['message'])
];
}
}
Il retire les espaces en trop autour du message. Surtout, il sait partir de rien : un widget peut être posé sans que personne n'ouvre son formulaire — par un thème qui l'installe, par exemple. Le site demande alors au checker les réglages par défaut, et ton widget s'affiche quand même.
Étape 8 — Les traductions
Ton site parle peut-être plusieurs langues. Les textes que le widget affiche lui-même — son titre, sa
description, « Bonjour », « Bienvenue sur », l'étiquette du champ — passent par $this->lang(…) : le site les
cherche dans le dossier langs/, un fichier par langue. Voici l'anglais, langs/en.php :
bienvenue/langs/en.php
<?php
declare(strict_types=1);
return [
'650a65c7' => 'Welcome', // Bienvenue
'0d0759dd' => 'Greets the logged-in member by their username, visitors by the site name, and adds the message of your choice.', // Salue le membre connecté par son pseudo, les visiteurs par le nom du site, et ajoute le message de ton choix.
'b0987800' => 'Hello %s!', // Bonjour %s !
'fb0c89ac' => 'Welcome to %s!', // Bienvenue sur %s !
'790009e3' => 'Message', // Message
'0a536731' => 'Leave empty to show only the greeting.', // Laisse vide pour n'afficher que la salutation.
];
La clé à gauche (650a65c7) est l'empreinte du texte français : un code calculé à partir de lui. Le
commentaire à droite rappelle de quel texte il s'agit. L'archive jointe contient les six langues du site ; copie
son dossier langs dans le tien.
Si tu changes un texte français, son empreinte change, et sa traduction n'est plus trouvée : le site affiche
alors le texte français, sans rien casser. Pour recalculer une empreinte, si PHP est installé sur ton
ordinateur : php -r "echo hash('crc32b', 'Bienvenue');". On y revient au niveau intermédiaire.
Le message, lui, n'est pas traduit : c'est ton texte, celui que tu as saisi.
Étape 9 — Mettre à jour
Recompresse le dossier et envoie l'archive par Ajouter, comme au premier essai. Si le site répond « Le widget
Bienvenue est déjà installé en version 1.0.0 », c'est normal : une archive ne remplace une version installée que si
la sienne est plus récente. Passe 'version' à '1.0.1' dans bienvenue.php, recompresse, envoie : le site
répond « Le widget Bienvenue a été mis à jour ».
Puis rouvre l'éditeur en direct, clique sur la roue dentée du widget (Configurer), et va à l'étape Configuration : écris ton message, valide. C'est fini.
Si ça ne marche pas
| Le site répond | Ce que ça veut dire |
|---|---|
| « Le composant ne peut pas être installé, veuillez vérifier la présence des numéros de version » | Il manque 'version' ou 'depends' dans bienvenue.php (étape 2). |
| « Le composant ne peut pas être installé, veuillez vérifier son contenu » | L'installeur n'a pas trouvé bienvenue.php dans le dossier bienvenue de l'archive, ou la ligne use NF\NeoFrag\Addons\Widget; a changé. |
| « Le widget Bienvenue nécessite la version 1.2.50 de NeoFrag, veuillez mettre à jour votre site » | Ton site est plus ancien que ce que demande depends. Mets ton site à jour. |
| « Le widget Bienvenue est déjà installé en version … » | Augmente 'version' (étape 9). |
| « Archive refusée : elle contient un chemin non sûr. » | L'archive porte un chemin anormal. Recompresse le dossier avec le clic droit de ton système. |
| Bienvenue n'est pas dans la fenêtre Nouveau Widget | L'installation n'a pas eu lieu : relis le message qu'a affiché Ajouter. |
| Le widget est posé, mais ne s'affiche pas sur la page | Il a été désactivé dans Thèmes & addons : réactive-le depuis le menu de sa carte. |
| Une page blanche, ou « Une erreur est survenue » | Une faute de frappe dans un fichier PHP — souvent un ; ou une } oubliés. Compare ton fichier à celui de l'archive. |
Pour aller plus loin
- Change l'icône : remplace
fa-hand-spockdansbienvenue.phpet dans la vue. - Ajoute un deuxième réglage — l'alignement du texte, par exemple : un champ de plus dans
admin.tpl.php, sa valeur par défaut et sa vérification dans le checker. - Le guide Créer un widget, dans la documentation du site, décrit tout ce qu'un widget peut faire.
Le tutoriel suivant, au niveau intermédiaire, reprend ce widget : plusieurs présentations au choix, des réglages vérifiés, des informations venues d'un autre module, et la fabrication des traductions.
