@menções

Digite @ e algumas letras para escolher uma pessoa em uma lista. O editor insere a pessoa como um pequeno chip não editável que leva o id dela, para que o seu servidor saiba quem foi mencionado. A lista pode ser um array estático ou uma função que consulta o seu servidor.

Ative o recurso

O recurso é o plugin mentionplugin.js (também incluído em plugins/all_plugins.js). Não há botão na barra de ferramentas: o seletor abre quando o usuário digita o caractere de gatilho. O gatilho @ só é registrado quando você fornece ao editor uma lista ou uma fonte; por isso, só carregar o plugin não faz nada.

<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>

Cada item precisa de um id e de um label. subtitle e avatarUrl são opcionais; sem avatar, o seletor mostra as iniciais da pessoa. Itens no formato { id, name, email } também funcionam: name é usado como label e email como subtitle.

Como consultar o seu servidor

Para um diretório real de usuários, passe mentionSource em vez disso. Ele recebe o texto digitado depois do gatilho e retorna um array, ou uma Promise de um array. Enquanto ele roda, o seletor mostra "Searching…"; um resultado vazio mostra "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);
        });
    }
});

A primeira chamada, logo depois do gatilho, tem a consulta vazia e roda imediatamente. As chamadas seguintes esperam mentionDebounceMs depois da última tecla. Respostas que chegam depois de uma consulta mais recente são descartadas.

Opções

Opção	Padrão	O que faz
`mentionStaticList`	`null`	Array de pessoas. Filtrado por correspondência sem diferenciar maiúsculas de minúsculas em label, subtitle e id. Com a consulta vazia, os 50 primeiros são oferecidos.
`mentionSource`	`null`	`function (query, ctx)` que retorna um array ou uma Promise. Usado em vez da lista estática quando os dois estão definidos.
`mentionTrigger`	`"@"`	O caractere que abre o seletor.
`mentionMaxItems`	`8`	Máximo de itens exibidos de uma vez.
`mentionDebounceMs`	`150`	Espera depois da digitação antes de chamar a fonte de novo.
`mentionInsertClass`	`"rte-mention"`	Classe colocada no chip inserido.
`mentionTriggers`	`null`	Array de definições de gatilhos extras (no mesmo formato de `register` abaixo), registradas na inicialização.
`mentionEnabled`	`true`	`false` desativa o plugin; `editor.mentions` então não é criado.

Mais gatilhos e a API

editor.mentions.register() adiciona um gatilho, por exemplo # para tags. Forneça source(query, ctx) como acima, ou search(query, done) e chame 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"
});

Uma definição também pode ter renderItem(item) (retorna texto ou um nó para a linha da lista), renderInsert(item) (retorna o texto do chip ou um nó) e label (o nome acessível da lista). Os outros métodos são editor.mentions.remove(trigger), list(), close() e isOpen().

Teclas com o seletor aberto: ArrowUp e ArrowDown movem a seleção, Enter ou Tab insere, Escape fecha. Digitar um espaço também o fecha. O seletor só abre no início de uma linha ou depois de um espaço; assim, um endereço de e-mail como mail@example.com não o abre, e ele nunca abre dentro de <code>, <pre> ou de um chip existente.

O que você precisa saber

Este é o HTML salvo. O chip é seguido de um espaço não separável, para que o cursor tenha para onde ir:
```
<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>
```
Leia data-rte-mention-id no servidor para enviar notificações. Se você sanitiza o HTML, permita span com class, contenteditable e os dois atributos data-rte-mention-*.
O estilo de pílula do chip é adicionado apenas dentro do editor. A página que exibe o HTML salvo precisa do próprio CSS para .rte-mention, e um insertClass personalizado não recebe estilo nenhum.
O gatilho é comparado com a tecla que o usuário pressionou; por isso, ele precisa ser um único caractere.
Os textos do seletor vêm das chaves de idioma text_mn_searching e text_mn_nomatches.

Relacionados: demonstração de @menções, referência de configuração.