Neueste Beiträge
Neueste Themen
Anleitung Mon premier module : « Astuces »
Niveau débutant · environ 45 minutes · NeoFrag Reborn 1.2.50 ou plus récent
Un module, c'est une partie du site qui a ses propres pages, à sa propre adresse : le forum vit sous
/forum, les actualités sous /news. Un widget se pose dans une page ; un module est des pages. Dans ce
tutoriel, tu écris un module « Astuces » : une page qui liste quelques conseils, et une page par conseil.
Les astuces sont écrites dans le code, pour garder ce premier module simple. Au niveau intermédiaire, elles passeront dans la base de données et s'écriront depuis l'administration.
L'archive terminée, astuces-1.0.0.zip, est jointe à ce sujet.
Ce qu'il te faut
- un site NeoFrag Reborn sur lequel tu es administrateur, de préférence un site d'essai ;
- un éditeur de texte qui enregistre en UTF-8 (VS Code, Notepad++, Sublime Text…) ;
- avoir suivi Mon premier widget aide, mais n'est pas obligatoire : tout est réexpliqué.
Étape 1 — Le dossier
Comme un widget, un module est un dossier dont le nom est celui du module. Crée un dossier astuces. À la fin, il
contiendra :
astuces/
├── astuces.php la carte d'identité, les adresses et les astuces
├── controllers/
│ ├── checker.php vérifie l'adresse demandée et trouve l'astuce
│ └── index.php prépare les pages
├── views/
│ ├── index.tpl.php le HTML de la liste
│ └── astuce.tpl.php le HTML d'une astuce
├── css/
│ └── astuces.css
├── langs/ les traductions
└── images/
└── thumbnail.jpg sa vignette (facultative)
Étape 2 — La carte d'identité et les adresses
astuces/astuces.php
<?php
declare(strict_types=1);
/**
* Astuces — le module du tutoriel « Mon premier module » (niveau débutant). LGPLv3.
*/
namespace NF\Modules\Astuces;
use NF\NeoFrag\Addons\Module;
class Astuces extends Module
{
protected function __info()
{
return [
'title' => $this->lang('Astuces'),
'description' => $this->lang('Quelques astuces pour bien démarrer sur le site, chacune sur sa page.'),
'icon' => 'fas fa-lightbulb',
'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' => [],
'admin' => FALSE,
'routes' => [
'' => 'index',
'{id}/{url_title}' => '_astuce'
]
];
}
/** Les astuces, par numéro. Au niveau intermédiaire, elles quittent le code pour la base de données. */
public function astuces(): array
{
return [
1 => [
'titre' => $this->lang('Complète ton profil'),
'texte' => $this->lang('Un avatar et quelques mots sur toi : les autres membres savent à qui ils parlent.')
],
2 => [
'titre' => $this->lang('Suis les sujets qui t\'intéressent'),
'texte' => $this->lang('Suivre un sujet du forum te prévient de chaque nouvelle réponse.')
],
3 => [
'titre' => $this->lang('Change la langue du site'),
'texte' => $this->lang('Le sélecteur du pied de page affiche le site dans ta langue, pour toi seul.')
],
4 => [
'titre' => $this->lang('Choisis ce que ton profil montre'),
'texte' => $this->lang('Dans ton espace membre, tu décides de ce que les autres voient de toi, comme ton âge ou ta présence en ligne.')
]
];
}
}
Le début ressemble à celui d'un widget : namespace NF\Modules\Astuces, la ligne
use NF\NeoFrag\Addons\Module; qui fait reconnaître un module, puis le titre, la description, l'icône, la
version et depends, sans lesquels l'archive ne s'installe pas. 'admin' => FALSE : ce module n'a pas
encore de page d'administration.
Ce qui est nouveau, ce sont les routes : les adresses du module, chacune liée à une méthode.
| Route | Adresse | Méthode |
|---|---|---|
'' |
/astuces |
index |
'{id}/{url_title}' |
/astuces/2/suis-les-sujets-qui-t-interessent |
_astuce |
{id} attrape un nombre, {url_title} un titre écrit pour une adresse (en minuscules, avec des tirets). Ce sont
des mots réservés : le site n'en connaît que quelques-uns ({id}, {url_title}, {page}…), et une route qui en
invente un ne mène nulle part.
La méthode astuces() rend la liste des astuces, par numéro. Chaque texte passe par $this->lang(…), pour être
traduit.
Étape 3 — Le checker : la bonne adresse, ou rien
Avant chaque page, le site appelle le checker du module. Son rôle : vérifier que l'adresse demandée a un sens,
et aller chercher ce dont la page a besoin. Crée controllers/checker.php :
astuces/controllers/checker.php
<?php
declare(strict_types=1);
namespace NF\Modules\Astuces\Controllers;
use NF\NeoFrag\Loadables\Controllers\Module_Checker;
class Checker extends Module_Checker
{
public function index()
{
return [$this->module->astuces()];
}
public function _astuce($id, $url_title)
{
$astuces = $this->module->astuces();
if (isset($astuces[$id]))
{
// Une adresse dont le titre n'est pas le bon mène à la bonne adresse.
nf_bon_titre((string) $url_title, (string) $astuces[$id]['titre'], 'astuces/'.(int) $id);
return [(int) $id, $astuces[$id], count($astuces)];
}
// Rien n'est rendu : le site répond « page introuvable ».
}
}
- Chaque méthode porte le nom d'une route, et reçoit ce que l'adresse contient :
_astucereçoit le numéro et le titre. $this->moduleest le module lui-même :$this->module->astuces()appelle la méthode de l'étape 2.- Ce que la méthode rend (un tableau) devient les arguments de la méthode du même nom dans le contrôleur. Si elle ne rend rien — l'astuce n° 9 n'existe pas —, le site répond « page introuvable » (une erreur 404), et c'est exactement ce qu'il faut.
nf_bon_titre(): si quelqu'un arrive par/astuces/2/nimporte-quoi, il est renvoyé vers la vraie adresse. Les moteurs de recherche ne voient ainsi qu'une adresse par page.
Étape 4 — Le contrôleur : les pages
Crée controllers/index.php :
astuces/controllers/index.php
<?php
declare(strict_types=1);
namespace NF\Modules\Astuces\Controllers;
use NF\NeoFrag\Loadables\Controllers\Module as Controller_Module;
class Index extends Controller_Module
{
public function index($astuces)
{
$this ->title($this->lang('Astuces'))
->icon('fas fa-lightbulb')
->breadcrumb();
return $this->css('astuces')
->panel()
->heading()
->body($this->view('index', [
'astuces' => $astuces
]));
}
public function _astuce($id, $astuce, $total)
{
$this ->title($astuce['titre'])
->icon('fas fa-lightbulb')
->breadcrumb($this->lang('Astuces'), url('astuces'))
->breadcrumb();
return $this->css('astuces')
->panel()
->heading($astuce['titre'], 'fas fa-lightbulb')
->body($this->view('astuce', [
'id' => $id,
'astuce' => $astuce,
'total' => $total
]));
}
}
title()donne le titre de l'onglet du navigateur,icon()son icône,breadcrumb()le fil d'Ariane (Accueil › Astuces › …) que les thèmes affichent. Sur une astuce, on y ajoute d'abord le lien vers la liste.url('astuces')construit l'adresse complète, langue comprise (/fr/astuces,/en/astuces…). Écris toujours tes liens avecurl(), jamais à la main.- Le reste est connu depuis le widget : un panneau, son titre (
heading()), et une vue pour le contenu.
Étape 5 — Les vues
La liste, views/index.tpl.php :
astuces/views/index.tpl.php
<ol class="astuces">
<?php foreach ($astuces as $id => $astuce): ?>
<li>
<a href="<?php echo url('astuces/'.$id.'/'.url_title((string) $astuce['titre'])) ?>"><?php echo nf_texte($astuce['titre']) ?></a>
</li>
<?php endforeach ?>
</ol>
url_title() transforme un titre en morceau d'adresse : « Complète ton profil » devient complete-ton-profil.
nf_texte() affiche un texte sans risque, comme dans le widget.
Une astuce, views/astuce.tpl.php :
astuces/views/astuce.tpl.php
<p class="astuces-numero"><?php echo $this->lang('Astuce %d sur %d', $id, $total) ?></p>
<p class="astuces-texte"><?php echo nf_texte($astuce['texte']) ?></p>
<a class="btn btn-outline-secondary btn-sm" href="<?php echo url('astuces') ?>">
<i class="fas fa-arrow-left"></i> <?php echo $this->lang('Toutes les astuces') ?>
</a>
'Astuce %d sur %d' : chaque %d reçoit un nombre, dans l'ordre — « Astuce 2 sur 4 ». Les classes btn btn-outline-secondary btn-sm sont celles des boutons du site : le thème les dessine.
Étape 6 — Le style
astuces/css/astuces.css
.astuces {
margin: 0;
padding-left: 1.4rem;
display: grid;
gap: .6rem;
}
.astuces a {
color: var(--nf-text-strong);
font-weight: 600;
}
.astuces li::marker {
color: var(--nf-accent);
font-weight: 700;
}
.astuces-numero {
margin: 0 0 .25rem;
color: var(--nf-text-muted);
font-size: .9rem;
}
.astuces-texte {
font-size: 1.1rem;
color: var(--nf-text);
}
Toujours les couleurs du thème, var(--nf-…) : le module s'accorde à tous les thèmes, en clair comme en sombre.
li::marker colore les numéros de la liste.
Étape 7 — Les traductions
Les fichiers de langs/ suivent la même règle que pour le widget : une clé par texte français, un fichier par
langue. Voici l'anglais, langs/en.php :
astuces/langs/en.php
<?php
declare(strict_types=1);
return [
'39020260' => 'Tips', // Astuces
'7c3489ca' => 'A few tips to get started on the site, each on its own page.', // Quelques astuces pour bien démarrer sur le site, chacune sur sa page.
'd6fff4fc' => 'Complete your profile', // Complète ton profil
'f9c9e10d' => 'An avatar and a few words about yourself: other members know who they are talking to.', // Un avatar et quelques mots sur toi : les autres membres savent à qui ils parlent.
'09d8c7ea' => 'Follow the topics you care about', // Suis les sujets qui t'intéressent
'760bc5fd' => 'Following a forum topic notifies you of every new reply.', // Suivre un sujet du forum te prévient de chaque nouvelle réponse.
'9f685eea' => 'Change the site language', // Change la langue du site
'35480c6c' => 'The selector in the footer shows the site in your language, just for you.', // Le sélecteur du pied de page affiche le site dans ta langue, pour toi seul.
'4f26c8a6' => 'Choose what your profile shows', // Choisis ce que ton profil montre
'1859449c' => 'In your member area, you decide what others see of you, such as your age or whether you are online.', // Dans ton espace membre, tu décides de ce que les autres voient de toi, comme ton âge ou ta présence en ligne.
'aa2ff3c0' => 'Tip %d of %d', // Astuce %d sur %d
'451f19d1' => 'All tips', // Toutes les astuces
];
Un visiteur anglais lit « Tips » et « Complete your profile ». L'adresse du module, elle, reste /en/astuces :
c'est le nom du dossier. Celle d'une astuce prend son titre traduit : /en/astuces/1/complete-your-profile. Copie
le dossier langs de l'archive : il porte les six langues.
Installer, et ajouter le lien au menu
- Compresse le dossier
astuces(clic droit → Compresser), puis Thèmes & addons → Ajouter. Le site répond « Le module Astuces a été installé ». - Ouvre
/astucessur ton site : la liste est là. Clique sur une astuce. - Pour un lien dans le menu : ouvre l'Éditeur en direct, clique sur la roue dentée (Configurer) du menu, puis onglet Ajouter → Lien vers un module → Astuces, et valide.
Essaie aussi /astuces/9/rien : « page introuvable », comme prévu.
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 astuces.php. |
| « Le composant ne peut pas être installé, veuillez vérifier son contenu » | L'archive ne contient pas astuces/astuces.php, ou la ligne use NF\NeoFrag\Addons\Module; a changé. |
| « Le module Astuces est déjà installé en version … » | Augmente 'version' dans astuces.php avant de renvoyer l'archive. |
/astuces répond « page introuvable » |
Vérifie la route '' dans astuces.php, et la méthode index du checker : elle doit rendre un tableau. |
| Une astuce répond « page introuvable » | Le nom de la méthode doit être celui de la route (_astuce), dans le checker et dans le contrôleur. |
| Une page blanche, ou « Une erreur est survenue » | Une faute de frappe dans un fichier PHP : compare-le à celui de l'archive. |
Pour aller plus loin
- Ajoute une cinquième astuce : une entrée de plus dans
astuces(), et ses traductions (ou pas : sans traduction, le site affiche le français). - Ajoute « Astuce suivante » sous chaque astuce : le contrôleur connaît
$idet$total. - Le guide Créer un module, dans la documentation du site, décrit tout ce qu'un module peut faire.
Le tutoriel intermédiaire reprend ce module : les astuces passent dans la base de données, s'écrivent depuis une page d'administration, avec des permissions, et le module apporte son widget « Astuce du jour ».
