04 — Output API : renderers, templates Mustache, $PAGE, navigation

// ❌ Style préhistorique — vous le verrez encore dans de très vieux plugins.
echo '<div class="ma-boite"><h2>' . $titre . '</h2>';
foreach ($items as $item) {
    echo '<li><a href="view.php?id=' . $item->id . '">' . $item->name . '</a></li>';
}
echo '</div>';

// ⚠️ Style « legacy toléré » — encore massivement présent dans le cœur.
echo html_writer::div(
    html_writer::tag('h2', s($titre)),
    'ma-boite'
);

// ✅ Style moderne : les données d'un côté...
$data = [
    'title' => format_string($titre),
    'items' => $itemsexportes,   // tableau de données « bêtes »
    'hasitems' => !empty($itemsexportes),
];
echo $OUTPUT->render_from_template('local_foo/item_list', $data);

{{! ...le HTML de l'autre (templates/item_list.mustache). }}
<div class="ma-boite">
    <h2>{{title}}</h2>
    {{#hasitems}}
        <ul>
            {{#items}}<li><a href="{{url}}">{{name}}</a></li>{{/items}}
        </ul>
    {{/hasitems}}
</div>

use core\output\html_writer;
use core\output\pix_icon;
use core\output\single_button;
use core\url;   // le nouveau nom de moodle_url.

// Squelette canonique d'une page Moodle.
require(__DIR__ . '/../../config.php');   // Bootstrap : $CFG, $DB, $PAGE, $OUTPUT, $USER...
 
require_login();                           // Authentification (et inscription au cours le cas échéant).
 
$PAGE->set_url(new moodle_url('/local/foo/index.php'));
$PAGE->set_context(context_system::instance());
$PAGE->set_title(get_string('pluginname', 'local_foo'));
$PAGE->set_heading(get_string('pluginname', 'local_foo'));
 
echo $OUTPUT->header();      // ← Rien ne doit être affiché AVANT cette ligne.
 
echo $OUTPUT->heading(get_string('welcome', 'local_foo'));
// ... le contenu de la page ...
 
echo $OUTPUT->footer();      // ← Et rien après celle-ci.

// --- Titres et boîtes -------------------------------------------------------
echo $OUTPUT->heading('Mon titre');                 // <h2>Mon titre</h2>
echo $OUTPUT->heading('Sous-titre', 3, 'ma-classe'); // niveau + classes CSS.
 
echo $OUTPUT->box('Contenu encadré', 'generalbox mt-3');
// Variante ouverte/fermée pour englober un gros bloc :
echo $OUTPUT->box_start('generalbox');
// ... contenu ...
echo $OUTPUT->box_end();
 
// --- Notification inline (rendu immédiat, PAS stockée en session) ----------
echo $OUTPUT->notification('Opération réussie.', \core\output\notification::NOTIFY_SUCCESS);
echo $OUTPUT->notification('Attention !', \core\output\notification::NOTIFY_WARNING);
 
// --- Images et icônes -------------------------------------------------------
// URL d'une image du plugin (fichier local_foo/pix/logo.png ou .svg) :
$logourl = $OUTPUT->image_url('logo', 'local_foo');
echo html_writer::img($logourl, get_string('logoalt', 'local_foo'));
 
// Icône « pix » : résolue par le thème (depuis Moodle 4.x : FontAwesome 6
// via le mapping d'icônes, plus des fichiers image par défaut).
echo $OUTPUT->pix_icon('t/edit', get_string('edit'));           // icône du cœur.
echo $OUTPUT->pix_icon('icon', get_string('pluginname', 'local_foo'), 'local_foo');
 
// --- Boutons ----------------------------------------------------------------
// single_button : un mini-formulaire <form> avec un seul bouton (POST par défaut).
echo $OUTPUT->single_button(
    new moodle_url('/local/foo/delete.php', ['id' => $id, 'sesskey' => sesskey()]),
    get_string('delete'),
    'post'
);
 
// Bouton "Continuer" standard :
echo $OUTPUT->continue_button(new moodle_url('/local/foo/index.php'));
 
// Écran de confirmation complet (message + boutons Oui/Non) :
echo $OUTPUT->confirm(
    get_string('confirmdelete', 'local_foo', $item->name),
    new moodle_url('/local/foo/delete.php', ['id' => $id, 'confirm' => 1, 'sesskey' => sesskey()]),
    new moodle_url('/local/foo/index.php')   // URL d'annulation.
);
 
// --- Liens d'action et aide -------------------------------------------------
// action_link : un <a> qui peut porter des actions JS (confirmation, etc.).
echo $OUTPUT->action_link(
    new moodle_url('/local/foo/edit.php', ['id' => $id]),
    get_string('edit'),
    null,
    ['class' => 'btn btn-secondary']
);
 
// help_icon : le petit "?" qui ouvre l'aide contextuelle. La chaîne
// 'perimeter' ET 'perimeter_help' doivent exister dans le fichier de langue.
echo $OUTPUT->help_icon('perimeter', 'local_foo');
 
// --- Le point d'entrée générique -------------------------------------------
echo $OUTPUT->render($monrenderable);                       // voir section 3.
echo $OUTPUT->render_from_template('local_foo/card', $data); // rendu direct.

<?php
namespace local_foo\output;
 
use core\output\renderable;
use core\output\renderer_base;
use core\output\templatable;
use moodle_url;
 
/**
 * Page d'index du plugin local_foo.
 *
 * Cet objet transporte les données métier ; export_for_template() les
 * aplatit en « dumb data » consommables par Mustache.
 *
 * @package   local_foo
 * @copyright 2026 Vous
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class index_page implements renderable, templatable {
 
    /** @var array Liste d'enregistrements métier (issus de $DB). */
    protected array $items;
 
    /** @var bool L'utilisateur courant peut-il gérer les items ? */
    protected bool $canmanage;
 
    /** @var \context Le contexte de la page (pour format_text). */
    protected \context $context;
 
    public function __construct(array $items, bool $canmanage, \context $context) {
        $this->items = $items;
        $this->canmanage = $canmanage;
        $this->context = $context;
    }
 
    /**
     * Exporte les données pour le template Mustache.
     *
     * RÈGLE D'OR : tout est précalculé ici. Le template ne doit contenir
     * AUCUNE logique — pas de comparaison, pas de formatage, pas d'URL
     * à assembler. Booléens prêts, URLs en string, texte déjà formaté.
     *
     * @param renderer_base $output Le renderer (utile pour image_url, etc.).
     * @return \stdClass
     */
    public function export_for_template(renderer_base $output): \stdClass {
        $data = new \stdClass();
        $data->canmanage = $this->canmanage;                 // booléen prêt.
        $data->addurl = (new moodle_url('/local/foo/edit.php'))->out(false);
        $data->items = [];
 
        foreach ($this->items as $item) {
            $data->items[] = [
                // format_string pour un titre (filtres + nettoyage) :
                'name'        => format_string($item->name, true, ['context' => $this->context]),
                // format_text pour un contenu riche : le HTML est produit ICI,
                // le template l'insérera avec {{{description}}} (triple moustache).
                'description' => format_text($item->description, $item->descriptionformat,
                                             ['context' => $this->context]),
                'viewurl'     => (new moodle_url('/local/foo/view.php', ['id' => $item->id]))->out(false),
                'editurl'     => (new moodle_url('/local/foo/edit.php', ['id' => $item->id]))->out(false),
                // Booléen précalculé plutôt qu'une comparaison dans Mustache :
                'isvisible'   => (bool) $item->visible,
                'timecreated' => userdate($item->timecreated),   // date déjà formatée.
            ];
        }
 
        // Mustache ne sait pas tester count() : on fournit le booléen.
        $data->hasitems = !empty($data->items);
 
        return $data;
    }
}

{{!
    This file is part of Moodle - http://moodle.org/
    (en-tête de licence GPL habituel...)
}}
{{!
    @template local_foo/index_page

    Page d'index du plugin local_foo.

    Classes required for JS: none.
    Data attributes required for JS: none.

    Context variables required for this template:
    * hasitems - bool, y a-t-il au moins un item ?
    * items - array d'objets {name, description, viewurl, editurl, isvisible, timecreated}
    * canmanage - bool, afficher les contrôles d'édition ?
    * addurl - string, URL du formulaire de création.

    Example context (json):
    {
        "hasitems": true,
        "canmanage": true,
        "addurl": "https://example.com/local/foo/edit.php",
        "items": [
            {
                "name": "Premier item",
                "description": "<p>Une <strong>description</strong> riche.</p>",
                "viewurl": "https://example.com/local/foo/view.php?id=1",
                "editurl": "https://example.com/local/foo/edit.php?id=1",
                "isvisible": true,
                "timecreated": "7 juillet 2026, 10:15"
            }
        ]
    }
}}
<div class="local-foo-index">
    {{#canmanage}}
        <div class="mb-3">
            <a href="{{addurl}}" class="btn btn-primary">
                {{#pix}} t/add, core {{/pix}} {{#str}} additem, local_foo {{/str}}
            </a>
        </div>
    {{/canmanage}}

    {{#hasitems}}
        <ul class="list-group">
            {{#items}}
                <li class="list-group-item {{^isvisible}}dimmed_text{{/isvisible}}">
                    <a href="{{viewurl}}"><strong>{{name}}</strong></a>
                    <span class="text-muted small ms-2">{{timecreated}}</span>
                    {{#canmanage}}
                        <a href="{{editurl}}" class="ms-2" title="{{#str}} edit, core {{/str}}">
                            {{#pix}} t/edit, core, {{#str}} edit, core {{/str}} {{/pix}}
                        </a>
                    {{/canmanage}}
                    {{! Triple moustache : le HTML a été nettoyé par format_text en PHP. }}
                    <div class="mt-1">{{{description}}}</div>
                </li>
            {{/items}}
        </ul>
    {{/hasitems}}

    {{^hasitems}}
        {{< core/notification_info }}
            {{$message}}{{#str}} noitems, local_foo {{/str}}{{/message}}
        {{/ core/notification_info }}
    {{/hasitems}}
</div>

<?php
require(__DIR__ . '/../../config.php');
 
require_login();
$context = context_system::instance();
require_capability('local/foo:view', $context);
 
$PAGE->set_url(new moodle_url('/local/foo/index.php'));
$PAGE->set_context($context);
$PAGE->set_title(get_string('pluginname', 'local_foo'));
$PAGE->set_heading(get_string('pluginname', 'local_foo'));
 
$items = $DB->get_records('local_foo_items', null, 'timecreated DESC');
$canmanage = has_capability('local/foo:manage', $context);
 
$page = new \local_foo\output\index_page($items, $canmanage, $context);
 
echo $OUTPUT->header();
echo $OUTPUT->render($page);      // ← la magie opère ici.
echo $OUTPUT->footer();

<?php
namespace local_foo\output;
 
use core\output\plugin_renderer_base;
 
/**
 * Renderer du plugin local_foo.
 */
class renderer extends plugin_renderer_base {
 
    /**
     * Rendu de la page d'index (appelée automatiquement par $OUTPUT->render()
     * grâce à la convention de nommage render_ + nom de classe).
     *
     * @param index_page $page
     * @return string HTML
     */
    protected function render_index_page(index_page $page): string {
        $data = $page->export_for_template($this);
        return $this->render_from_template('local_foo/index_page', $data);
    }
}

$renderer = $PAGE->get_renderer('local_foo');
echo $renderer->render($page);

{{! Ceci est un commentaire — jamais rendu, n'apparaît pas dans le HTML. }}

{{! 1. Interpolation ÉCHAPPÉE (défaut) : les entités HTML sont encodées. }}
<p>{{username}}</p>
{{! Si username = "<script>", le rendu est &lt;script&gt; — sûr. }}

{{! 2. Interpolation BRUTE (triple moustache) : le HTML passe tel quel. }}
<div>{{{descriptionhtml}}}</div>
{{! ⚠️ À réserver au HTML déjà nettoyé par format_text() côté PHP. }}

{{! 3. Sections : conditionnelle si la valeur est un booléen... }}
{{#canedit}}
    <a href="{{editurl}}">Modifier</a>
{{/canedit}}

{{! ...ou itérative si la valeur est un tableau (le contexte descend dans l'item). }}
{{#items}}
    <li>{{name}}</li>
{{/items}}

{{! 4. Section inversée : rendue si la valeur est false, vide ou tableau vide. }}
{{^items}}
    <p>Aucun élément.</p>
{{/items}}

{{! 5. Partial : inclusion d'un autre template (composant réutilisable). }}
{{> core/loading }}
{{> local_foo/item_card }}

{{! 6. Héritage de template (pragma Mustache "blocks") :
     {{< parent }} inclut un template parent, {{$bloc}} remplace ses blocs. }}
{{< core/modal }}
    {{$title}}Mon titre de modale{{/title}}
    {{$body}}Le corps de ma modale{{/body}}
{{/ core/modal }}

{{! --- {{#str}} : chaîne de langue. Syntaxe : identifiant, composant, paramètre $a. }}
<h3>{{#str}} pluginname, local_foo {{/str}}</h3>
{{! Avec un $a scalaire : }}
<p>{{#str}} welcomeuser, local_foo, {{username}} {{/str}}</p>
{{! Avec un $a complexe, on passe du JSON — les valeurs peuvent venir du contexte : }}
<p>{{#str}} itemsummary, local_foo, { "name": {{#quote}} {{name}} {{/quote}}, "count": {{count}} } {{/str}}</p>

{{! --- {{#cleanstr}} : comme {{#str}} mais le résultat passe par clean_string().
     À utiliser quand la chaîne atterrit dans un attribut HTML. }}
<input type="image" alt="{{#cleanstr}} delete, core {{/cleanstr}}" ...>

{{! --- {{#quote}} : entoure la valeur de guillemets JSON en échappant proprement.
     Sert essentiellement à construire le $a JSON de {{#str}} ci-dessus. }}

{{! --- {{#pix}} : icône. Syntaxe : clé, composant, texte alternatif. }}
{{#pix}} t/edit, core, {{#str}} edit, core {{/str}} {{/pix}}
{{#pix}} icon, local_foo {{/pix}}

{{! --- {{#shortentext}} : tronque proprement (mots entiers, ellipse).
     Syntaxe : longueur, texte. }}
<p>{{#shortentext}} 80, {{description}} {{/shortentext}}</p>

{{! --- {{#userdate}} : formate un timestamp UNIX selon le fuseau de l'utilisateur.
     Syntaxe : timestamp, format strftime (souvent une chaîne core_langconfig). }}
<span>{{#userdate}} {{timecreated}}, {{#str}} strftimedatetime, core_langconfig {{/str}} {{/userdate}}</span>

{{! --- {{#js}} : enregistre du JS exécuté après le rendu du template.
     À réserver aux initialisations minimales — préférez js_call_amd côté PHP. }}
{{#js}}
    require(['local_foo/controller'], function(Controller) {
        Controller.init('{{uniqid}}');
    });
{{/js}}

import Templates from 'core/templates';
 
const {html, js} = await Templates.renderForPromise('local_foo/item_card', context);
Templates.replaceNodeContents(container, html, js);

require(__DIR__ . '/../../config.php');
 
$id = required_param('id', PARAM_INT);
$action = optional_param('action', '', PARAM_ALPHA);
 
// --- set_url : OBLIGATOIRE, et AVEC les paramètres ---------------------------
// C'est l'URL "canonique" de la page. Elle sert : au fil d'ariane, au bouton
// "réessayer" après erreur, aux redirections de login, aux logs, au bouton
// d'activation de l'édition... Si vous omettez les params, un F5 après login
// retombera sur la page SANS id → erreur.
$PAGE->set_url(new moodle_url('/local/foo/view.php', ['id' => $id]));
 
// --- set_context : le contexte de la page (permissions, filtres, fichiers) --
$PAGE->set_context(context_system::instance());
 
// Pour une page DE COURS, préférez set_course (qui règle aussi le contexte) :
$course = get_course($courseid);
require_login($course);            // require_login($course) appelle set_course pour vous.
// $PAGE->set_course($course);     // ...sinon manuellement.
 
// Pour une page DE MODULE (activité), set_cm règle cm + cours + contexte :
[$course, $cm] = get_course_and_cm_from_cmid($cmid, 'quiz');
require_login($course, false, $cm); // règle $PAGE->cm, course, context d'un coup.
// $PAGE->set_cm($cm, $course);
 
// --- Titre (onglet navigateur) et heading (gros titre dans l'en-tête) -------
$PAGE->set_title(get_string('viewitem', 'local_foo'));   // <title> — Moodle 4.x+
                                                          // y ajoute automatiquement
                                                          // " | Nom du site".
$PAGE->set_heading($course->fullname ?? format_string($SITE->fullname));
 
// --- Layout : quel gabarit du thème utiliser --------------------------------
$PAGE->set_pagelayout('standard');

// Forcer l'affichage (ou le masquage) de la navigation secondaire (les onglets
// sous l'en-tête, introduits par Boost en 4.0) :
$PAGE->set_secondary_navigation(false);           // pas d'onglets sur cette page.
$PAGE->set_secondary_active_tab('coursehome');    // onglet actif explicite.
 
// Fil d'ariane : la navbar se construit normalement toute seule à partir de
// l'arbre de navigation, mais on peut y ajouter des étapes manuellement :
$PAGE->navbar->add(get_string('pluginname', 'local_foo'),
                   new moodle_url('/local/foo/index.php'));
$PAGE->navbar->add(format_string($item->name));   // dernier maillon : pas de lien.

// --- LA méthode moderne : appeler la fonction init d'un module AMD/ESM ------
// Charge local/foo/amd/build/controller.min.js et appelle sa fonction init()
// avec les arguments donnés (sérialisés en JSON).
$PAGE->requires->js_call_amd('local_foo/controller', 'init', [
    ['itemid' => $id, 'contextid' => $context->id],
]);
 
// --- CSS additionnel (rare : le CSS d'un plugin vit dans styles.css,
//     compilé avec le thème ; ceci est pour les cas dynamiques) --------------
$PAGE->requires->css('/local/foo/extra.css');   // AVANT $OUTPUT->header() !
 
// --- Exposer des chaînes de langue au JavaScript -----------------------------
// (côté JS moderne, préférez le module 'core/str' qui les charge en AJAX,
//  mais ces méthodes restent utiles pour éviter un aller-retour)
$PAGE->requires->string_for_js('confirmdelete', 'local_foo');
$PAGE->requires->strings_for_js(['save', 'cancel'], 'core');
// → accessibles côté JS via M.util.get_string('confirmdelete', 'local_foo').
 
// --- Divers -------------------------------------------------------------------
$PAGE->requires->data_for_js('mavariable', $donnees);  // expose M.cfg-like (legacy).

$PAGE->theme;                  // objet theme_config du thème actif ($PAGE->theme->name).
$PAGE->context;                // le contexte réglé par set_context/set_cm.
$PAGE->course;                 // le cours courant (ou le pseudo-cours "site").
$PAGE->cm;                     // le course_module courant (cm_info) ou null.
$PAGE->user_is_editing();      // true si l'utilisateur a activé le mode édition
                               // (ET a la permission) — pour afficher les contrôles
                               // d'édition conditionnellement.
$PAGE->add_body_class('local-foo-page');  // classe CSS sur <body>.
$PAGE->set_docs_path('local/foo/view');   // lien "Documentation Moodle" du footer.

echo $OUTPUT->header();
$PAGE->set_title('Trop tard');                    // ❌ exception coding_exception.
$PAGE->requires->css('/local/foo/extra.css');     // ❌ exception : head déjà rendu.
$PAGE->requires->js_call_amd('local_foo/x', 'init'); // ✅ OK ! Le JS est injecté
                                                      // dans le footer, donc accepté
                                                      // même après header().

use core\notification;
 
// Empile un message qui sera affiché sur la PROCHAINE page rendue —
// y compris après un redirect(). Stocké en session.
notification::success(get_string('itemsaved', 'local_foo'));
notification::warning(get_string('quotanearlyfull', 'local_foo'));
notification::error(get_string('savefailed', 'local_foo'));
notification::info(get_string('syncscheduled', 'local_foo'));
 
// Le pattern POST-Redirect-GET canonique d'un formulaire :
if ($data = $mform->get_data()) {
    local_foo_save_item($data);
    notification::success(get_string('itemsaved', 'local_foo'));
    redirect(new moodle_url('/local/foo/index.php'));   // le message s'affichera là-bas.
}

// Retourne le HTML d'une alerte, à échoer où VOUS voulez dans la page.
// Ne survit PAS à une redirection : c'est du rendu direct.
echo $OUTPUT->notification(
    get_string('nopermissiontoedit', 'local_foo'),
    \core\output\notification::NOTIFY_WARNING,
    false   // 3e paramètre : refermable ou non.
);

// redirect() accepte un message : il est automatiquement converti en
// notification de session, puis affiché sur la page cible.
redirect(
    new moodle_url('/local/foo/index.php'),
    get_string('itemdeleted', 'local_foo'),
    null,                                              // délai : null = immédiat.
    \core\output\notification::NOTIFY_SUCCESS          // type de notification.
);
// ⚠️ redirect() termine le script (die). Aucun code après n'est exécuté.

use core\output\html_writer;
 
// --- tag : balise avec contenu (le contenu N'EST PAS échappé — à vous de le faire).
echo html_writer::tag('p', s($texte), ['class' => 'lead']);
// → <p class="lead">Texte échappé</p>
 
// --- empty_tag : balise auto-fermante.
echo html_writer::empty_tag('input', [
    'type' => 'hidden', 'name' => 'sesskey', 'value' => sesskey(),
]);
 
// --- Raccourcis div / span.
echo html_writer::div($contenuhtml, 'card p-3', ['id' => 'foo-card']);
echo html_writer::span(get_string('new'), 'badge bg-info');
 
// --- link : un <a>. Accepte moodle_url directement (échappement géré).
echo html_writer::link(
    new moodle_url('/local/foo/view.php', ['id' => $id]),
    format_string($item->name),
    ['class' => 'fw-bold']
);
 
// --- start_tag / end_tag pour englober un gros bloc généré en boucle.
echo html_writer::start_tag('ul', ['class' => 'list-unstyled']);
foreach ($items as $item) {
    echo html_writer::tag('li', format_string($item->name));
}
echo html_writer::end_tag('ul');
 
// --- html_table : LA façon rapide de sortir un tableau statique.
$table = new html_table();
$table->head = [get_string('name'), get_string('date'), get_string('actions')];
$table->attributes['class'] = 'table table-striped generaltable';
foreach ($items as $item) {
    $table->data[] = [
        format_string($item->name),
        userdate($item->timecreated),
        html_writer::link(new moodle_url('/local/foo/edit.php', ['id' => $item->id]),
                          get_string('edit')),
    ];
}
echo html_writer::table($table);

use core\url;   // ou l'alias historique moodle_url — identique.
 
// --- Construction : chemin relatif à la racine Moodle + paramètres. ---------
$url = new moodle_url('/mod/quiz/view.php', ['id' => $cmid]);
 
// $CFG->wwwroot est préfixé automatiquement. Si le site vit dans un
// sous-répertoire (https://exemple.fr/moodle), c'est géré.
 
// --- Manipulation des paramètres --------------------------------------------
$url->param('page', 2);                    // ajoute/écrase un paramètre.
$url->params(['sort' => 'name', 'dir' => 'ASC']);  // plusieurs d'un coup.
$url->remove_params('page');               // supprime.
$page = $url->get_param('page');           // lit.
$url->set_anchor('section-3');             // fragment #section-3.
 
// --- Sortie : LA subtilité critique -----------------------------------------
echo $url->out();        // échappé HTML : les & deviennent &
                         // → pour insertion DIRECTE dans un attribut href écrit à la main.
echo $url->out(false);   // brut : & littéraux
                         // → pour les en-têtes Location, redirect(), JSON,
                         //   export_for_template() (Mustache ré-échappera), JS...
 
// Règle simple : dans export_for_template(), TOUJOURS ->out(false),
// car {{url}} dans le template appliquera l'échappement HTML lui-même.
// Sinon : double échappement, et vos URLs contiennent des "&".
 
// --- Comparaison (utile pour marquer l'onglet actif) -------------------------
if ($PAGE->url->compare($url, URL_MATCH_BASE)) {        // même script, on ignore les params.
    // ...
}
// URL_MATCH_EXACT : identiques ; URL_MATCH_PARAMS : les params de $url
// doivent tous être présents.
 
// --- URL locale (chemin relatif au wwwroot, pour stockage/redirection sûre) --
$local = $url->out_as_local_url(false);   // "/mod/quiz/view.php?id=42"
// Lève une exception si l'URL n'appartient PAS au site → protection
// anti open-redirect quand l'URL vient d'un paramètre utilisateur.
 
// --- URLs de fichiers servis par pluginfile.php ------------------------------
$fileurl = url::make_pluginfile_url(
    $context->id,        // contexte du fichier.
    'local_foo',         // composant.
    'attachments',       // filearea.
    $item->id,           // itemid.
    '/',                 // filepath.
    $filename            // filename.
);
// → https://site/pluginfile.php/CTXID/local_foo/attachments/ITEMID/fichier.pdf
// (le chapitre 05 détaille l'API Fichiers et la callback local_foo_pluginfile.)

<?php
defined('MOODLE_INTERNAL') || die();
 
use core\url;
 
/**
 * Ajoute un lien "Rapport Foo" dans la navigation d'administration du cours.
 * Apparaît dans l'onglet "Plus" de la navigation secondaire du cours.
 *
 * @param navigation_node $navigation Le nœud d'administration du cours.
 * @param stdClass $course Le cours.
 * @param context_course $context Le contexte du cours.
 */
function local_foo_extend_navigation_course(navigation_node $navigation,
                                            stdClass $course,
                                            context_course $context): void {
    // TOUJOURS vérifier la permission : la callback est appelée pour tout
    // le monde, c'est à vous de filtrer.
    if (!has_capability('local/foo:viewreport', $context)) {
        return;
    }
 
    $url = new url('/local/foo/report.php', ['courseid' => $course->id]);
 
    // Méthode 1 : add() directement sur le nœud parent.
    $navigation->add(
        get_string('fooreport', 'local_foo'),     // libellé.
        $url,                                      // URL (ou null pour un dossier).
        navigation_node::TYPE_SETTING,             // type de nœud.
        null,                                      // shorttext.
        'local_foo_report',                        // clé unique (pour retrouver le nœud).
        new pix_icon('i/report', '')               // icône.
    );
 
    // Méthode 2 : create() puis add_node(), utile pour contrôler la position.
    $node = navigation_node::create(
        get_string('foosettings', 'local_foo'),
        new url('/local/foo/coursesettings.php', ['courseid' => $course->id]),
        navigation_node::TYPE_SETTING,
        null,
        'local_foo_settings'
    );
    $node->set_force_into_more_menu(true);   // reste dans le menu "Plus",
                                              // ne devient jamais un onglet.
    $navigation->add_node($node);
}

/**
 * Étend le menu de réglages de l'activité (onglet "Plus" de l'activité).
 *
 * @param settings_navigation $settingsnav
 * @param navigation_node $monmodnode Le nœud racine des réglages de CETTE instance.
 */
function monmod_extend_settings_navigation(settings_navigation $settingsnav,
                                           navigation_node $monmodnode): void {
    if (has_capability('mod/monmod:manage', $settingsnav->get_page()->cm->context)) {
        $monmodnode->add(
            get_string('manageentries', 'mod_monmod'),
            new moodle_url('/mod/monmod/manage.php',
                           ['id' => $settingsnav->get_page()->cm->id]),
            navigation_node::TYPE_SETTING
        );
    }
}

<?php
require(__DIR__ . '/../../config.php');
 
// Convention de nommage universelle dans Moodle : page (0-indexée !) et perpage.
$page    = optional_param('page', 0, PARAM_INT);
$perpage = optional_param('perpage', 20, PARAM_INT);
 
require_login();
$context = context_system::instance();
 
// L'URL de base DOIT contenir tous les paramètres de filtre/tri courants,
// SAUF "page" que paging_bar gère lui-même.
$baseurl = new moodle_url('/local/foo/index.php', ['perpage' => $perpage]);
 
$PAGE->set_url($baseurl);
$PAGE->set_context($context);
$PAGE->set_title(get_string('pluginname', 'local_foo'));
$PAGE->set_heading(get_string('pluginname', 'local_foo'));
 
// Compte total (pour connaître le nombre de pages) + tranche courante.
$totalcount = $DB->count_records('local_foo_items');
$items = $DB->get_records('local_foo_items', null, 'timecreated DESC',
                          '*',
                          $page * $perpage,   // offset = page × perpage.
                          $perpage);          // limite.
 
echo $OUTPUT->header();
 
// ... rendu de la liste (template Mustache, table, etc.) ...
 
// La barre de pagination : (total, page courante, taille de page, URL de base).
// Elle génère des liens baseurl + "&page=N". Ne s'affiche pas s'il n'y a
// qu'une seule page.
echo $OUTPUT->paging_bar($totalcount, $page, $perpage, $baseurl);
 
echo $OUTPUT->footer();

<?php
namespace local_foo\table;
 
defined('MOODLE_INTERNAL') || die();
 
require_once($CFG->libdir . '/tablelib.php');   // table_sql n'est pas autoloadée !
 
use core\output\html_writer;
use core\url;
use table_sql;
 
/**
 * Table de listing des items de local_foo : tri, pagination, export.
 */
class items_table extends table_sql {
 
    /** @var \context Contexte pour le formatage. */
    protected \context $context;
 
    /** @var bool Droit de gestion (colonne actions). */
    protected bool $canmanage;
 
    /**
     * @param string $uniqueid Identifiant unique de la table (persistance du tri
     *                         dans les préférences utilisateur).
     * @param \context $context
     */
    public function __construct(string $uniqueid, \context $context) {
        parent::__construct($uniqueid);
        $this->context = $context;
        $this->canmanage = has_capability('local/foo:manage', $context);
 
        // --- Colonnes : les clés correspondent aux alias du SELECT -----------
        $columns = ['name', 'category', 'timecreated', 'visible'];
        $headers = [
            get_string('name'),
            get_string('category', 'local_foo'),
            get_string('date'),
            get_string('visible'),
        ];
        if ($this->canmanage) {
            $columns[] = 'actions';
            $headers[] = get_string('actions');
        }
        $this->define_columns($columns);
        $this->define_headers($headers);
 
        // --- Tri ----------------------------------------------------------------
        $this->sortable(true, 'timecreated', SORT_DESC);  // tri par défaut.
        $this->no_sorting('actions');                     // pas de tri sur les actions.
        $this->collapsible(false);                        // pas de colonnes repliables.
 
        // --- Export -----------------------------------------------------------
        // "actions" ne doit pas apparaître dans le CSV : on la marque non exportable.
        $this->column_nosort[] = 'actions';
        $this->is_downloadable(true);
        $this->show_download_buttons_at([TABLE_P_BOTTOM]);
    }
 
    /**
     * Formatage de la colonne "name" : convention col_{nomcolonne}().
     * Si aucune méthode col_xxx n'existe, la valeur brute est affichée
     * (échappée en mode web).
     *
     * @param \stdClass $row La ligne SQL complète.
     * @return string
     */
    public function col_name(\stdClass $row): string {
        $name = format_string($row->name, true, ['context' => $this->context]);
        if ($this->is_downloading()) {
            return $name;                       // export : texte brut, pas de lien.
        }
        return html_writer::link(
            new url('/local/foo/view.php', ['id' => $row->id]),
            $name
        );
    }
 
    public function col_timecreated(\stdClass $row): string {
        return userdate($row->timecreated, get_string('strftimedatetime', 'langconfig'));
    }
 
    public function col_visible(\stdClass $row): string {
        return $row->visible ? get_string('yes') : get_string('no');
    }
 
    /**
     * Colonne calculée qui n'existe pas en SQL : "actions".
     * (Pour des colonnes inconnues à traiter en masse, on peut aussi
     * surcharger other_cols($colname, $row).)
     */
    public function col_actions(\stdClass $row): string {
        global $OUTPUT;
        if ($this->is_downloading()) {
            return '';
        }
        $edit = $OUTPUT->action_icon(
            new url('/local/foo/edit.php', ['id' => $row->id]),
            new \core\output\pix_icon('t/edit', get_string('edit'))
        );
        $delete = $OUTPUT->action_icon(
            new url('/local/foo/delete.php', ['id' => $row->id, 'sesskey' => sesskey()]),
            new \core\output\pix_icon('t/delete', get_string('delete'))
        );
        return $edit . ' ' . $delete;
    }
 
    /**
     * Filet de sécurité pour toute colonne sans méthode dédiée.
     */
    public function other_cols($colname, $row) {
        // Par défaut : échapper la valeur brute (sécurité en mode web).
        return s($row->$colname ?? '');
    }
}

<?php
require(__DIR__ . '/../../config.php');
 
$download = optional_param('download', '', PARAM_ALPHA);   // '' | csv | excel...
$category = optional_param('category', 0, PARAM_INT);      // filtre.
 
require_login();
$context = context_system::instance();
require_capability('local/foo:view', $context);
 
$baseurl = new moodle_url('/local/foo/manage.php', ['category' => $category]);
$PAGE->set_url($baseurl);
$PAGE->set_context($context);
$PAGE->set_title(get_string('manageitems', 'local_foo'));
$PAGE->set_heading(get_string('manageitems', 'local_foo'));
$PAGE->set_pagelayout('admin');
 
// --- Construction de la table ------------------------------------------------
$table = new \local_foo\table\items_table('local_foo_items_table', $context);
 
// set_sql(fields, from, where, params) : la table gère ORDER BY, LIMIT, COUNT.
$where = '1=1';
$params = [];
if ($category) {
    $where .= ' AND i.categoryid = :categoryid';
    $params['categoryid'] = $category;
}
$table->set_sql(
    'i.id, i.name, i.timecreated, i.visible, c.name AS category',
    '{local_foo_items} i JOIN {local_foo_categories} c ON c.id = i.categoryid',
    $where,
    $params
);
 
// L'URL de base sert aux liens de tri et de pagination : elle doit
// embarquer les filtres courants (sinon trier = perdre le filtre).
$table->define_baseurl($baseurl);
 
// --- Mode export : PAS de header/footer, la table streame le fichier ---------
if ($download) {
    $table->is_downloading($download, 'items_export', get_string('items', 'local_foo'));
    $table->out(0, false);   // 0 = pas de pagination en export.
    exit;                    // le fichier est déjà parti, on s'arrête.
}
 
// --- Mode web ------------------------------------------------------------------
echo $OUTPUT->header();
echo $OUTPUT->heading(get_string('manageitems', 'local_foo'));
 
// Un petit formulaire de filtre (en vrai projet : un moodleform ou le
// composant core/search_input — ici version minimale).
$categories = $DB->get_records_menu('local_foo_categories', null, 'name', 'id, name');
echo html_writer::start_tag('form', ['method' => 'get', 'class' => 'mb-3']);
echo html_writer::select($categories, 'category', $category, get_string('allcategories', 'local_foo'));
echo html_writer::empty_tag('input', ['type' => 'submit', 'value' => get_string('filter'),
                                      'class' => 'btn btn-secondary ms-2']);
echo html_writer::end_tag('form');
 
// out(pagesize, useinitialsbar) : rend la table, avec tri cliquable,
// pagination automatique (paramètres page/tsort/tdir gérés pour vous),
// et boutons d'export (CSV, Excel, ODS, JSON, PDF) en bas.
$table->out(25, true);
 
echo $OUTPUT->footer();