@mentions

Saisissez @ et quelques lettres pour choisir une personne dans une liste. L’éditeur insère une petite puce non modifiable contenant son identifiant : votre serveur peut ainsi savoir qui est mentionné. La liste peut être un tableau statique ou une fonction interrogeant votre serveur.

Activation

Cette fonctionnalité est fournie par le plugin mentionplugin.js (également inclus dans plugins/all_plugins.js). Aucun bouton : le sélecteur s’ouvre à la saisie du caractère déclencheur. Le déclencheur @ n’est enregistré que si vous fournissez une liste ou une source : charger le plugin seul ne fait donc rien.

<link rel="stylesheet" href="/richtexteditor/rte_theme_default.css">
<script src="/richtexteditor/rte.js"></script>
<script src="/richtexteditor/plugins/mentionplugin.js"></script>

<div id="editor"><p>Thanks for the review.</p></div>
<script>
var editor = new RichTextEditor("#editor", {
    mentionStaticList: [
        { id: "u1", label: "Ana Ruiz", subtitle: "ana@example.com" },
        { id: "u2", label: "Ben Okafor", subtitle: "ben@example.com" },
        { id: "u3", label: "Bea Lindqvist", subtitle: "bea@example.com" },
        { id: "u4", label: "Chen Wei", subtitle: "chen@example.com" }
    ]
});
</script>

Chaque élément nécessite un id et un label. subtitle et avatarUrl sont facultatifs ; sans avatar, le sélecteur affiche les initiales. Les éléments de la forme { id, name, email } fonctionnent aussi : name sert de libellé et email de sous-titre.

Interroger votre serveur

Pour un véritable annuaire, transmettez plutôt mentionSource. Il reçoit le texte saisi après le déclencheur et renvoie un tableau, directement ou par une Promise. Pendant l’attente, le sélecteur affiche « Searching… » ; un résultat vide affiche « No matches ».

var people = [{ id: 7, name: "Ana Ruiz", email: "ana@example.com" }, { id: 9, name: "Ben Okafor", email: "ben@example.com" }];
var editor = new RichTextEditor("#editor", {
    mentionSource: function (query, ctx) {
        // ctx.trigger is "@"; replace this with a fetch to your own endpoint
        return new Promise(function (resolve) {
            setTimeout(function () {
                resolve(people.filter(function (p) { return p.name.toLowerCase().indexOf(query.toLowerCase()) >= 0; }));
            }, 100);
        });
    }
});

Le premier appel, juste après le déclencheur, utilise une recherche vide et s’exécute immédiatement. Les suivants attendent mentionDebounceMs après la dernière touche. Les réponses arrivant après une recherche plus récente sont ignorées.

Options

Option	Valeur par défaut	Fonctionnement
mentionStaticList	null	Tableau de personnes. Filtré sans distinction de casse sur le libellé, le sous-titre et l’identifiant. Une recherche vide propose les 50 premières.
mentionSource	null	function (query, ctx) renvoyant un tableau ou une Promise. Prioritaire sur la liste statique si les deux sont définis.
mentionTrigger	"@"	Caractère qui ouvre le sélecteur.
mentionMaxItems	8	Nombre maximal d’éléments affichés à la fois.
mentionDebounceMs	150	Délai après la saisie avant de rappeler la source.
mentionInsertClass	"rte-mention"	Classe attribuée à la puce insérée.
mentionTriggers	null	Tableau de définitions de déclencheurs supplémentaires (même forme que register ci-dessous), enregistrés au démarrage.
mentionEnabled	true	false désactive le plugin ; editor.mentions n’est alors pas créé.

Déclencheurs supplémentaires et API

editor.mentions.register() ajoute un déclencheur, par exemple # pour les étiquettes. Fournissez-lui source(query, ctx) comme ci-dessus, ou search(query, done) puis appelez done(list).

editor.mentions.register({
    trigger: "#",
    search: function (query, done) { done([{ id: "t-12", label: "release-2.6" }, { id: "t-13", label: "billing" }]); },
    insertClass: "tag-chip"
});

Une définition peut aussi contenir renderItem(item) (renvoie du texte ou un nœud pour la ligne de liste), renderInsert(item) (renvoie le texte de la puce ou un nœud) et label (nom accessible de la liste). Les autres méthodes sont editor.mentions.remove(trigger), list(), close() et isOpen().

Touches lorsque le sélecteur est ouvert : Flèche haut et Flèche bas naviguent, Entrée ou Tab insèrent, Échap ferme. Un espace le ferme aussi. Le sélecteur ne s’ouvre qu’en début de ligne ou après un espace : une adresse e-mail comme mail@example.com ne l’ouvre donc pas, ni une saisie dans <code>, <pre> ou une puce existante.

À savoir

• Voici le HTML enregistré. La puce est suivie d’une espace insécable pour permettre au curseur de se placer après :

  <p>Thanks for the review. <span class="rte-mention" contenteditable="false" data-rte-mention-id="u1" data-rte-mention-trigger="@">@Ana Ruiz</span>&nbsp;and ...</p>

  Lisez data-rte-mention-id côté serveur pour envoyer les notifications. Si vous nettoyez le HTML, autorisez span avec class, contenteditable et les deux attributs data-rte-mention-*.
• Le style en pilule de la puce n’est ajouté que dans l’éditeur. La page affichant le HTML enregistré doit définir son propre CSS pour .rte-mention, et une insertClass personnalisée ne reçoit aucun style.
• Le déclencheur est comparé à la touche appuyée : il doit donc être un caractère unique.
• Les textes du sélecteur proviennent des clés de langue text_mn_searching et text_mn_nomatches.

Voir aussi : démonstration des @mentions, référence de configuration.