Cartes de liens

Insérez un lien sous forme de carte d’aperçu avec un titre, une courte description, l’icône du site et une miniature, comme un lien partagé dans une messagerie. L’éditeur ne récupère rien lui-même : la carte affiche ce que renvoie votre bookmarkResolver, ou simplement le nom de domaine si vous n’en avez pas.

L’éditeur avec une carte de lien : le titre Quick start - RichTextEditor, une description sur une ligne, une petite icône avec le domaine richtexteditor.com et une miniature à droite — Carte construite à partir des données que `bookmarkResolver` a renvoyées pour `richtexteditor.com/docs/quick-start`. Le cercle en pointillés autour de la petite icône signale, dans l’éditeur, une image dont l’attribut `alt` est vide ; il n’apparaît que pendant la modification.

Activation

Cette fonctionnalité est fournie par le plugin bookmarkcard.js (également inclus dans plugins/all_plugins.js). L’élément de la barre d’outils est insertbookmark (infobulle « Bookmark »). La barre d’outils par défaut le place dans le menu « More » (⋮) ; ajoutez insertbookmark dans votre propre barre d’outils. Pour obtenir des cartes complètes, fournissez un résolveur qui demande les métadonnées de la page à votre serveur :

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

<div id="div_editor1"><p>Start here:</p></div>
<script>
var editor1 = new RichTextEditor("#div_editor1", {
  toolbar: "custom",
  toolbar_custom: "{bold,italic,underline}|{insertbookmark}|{undo,redo}",
  bookmarkResolver: function (url) {
    return fetch("/api/unfurl?url=" + encodeURIComponent(url))
      .then(function (r) { return r.json(); }); // { title, description, image, favicon }
  }
});
</script>

/api/unfurl est votre point de terminaison, et ne fait pas partie de l’éditeur. Il doit récupérer la page côté serveur, lire ses données <title>, og:description, og:image et son icône, puis les renvoyer en JSON. Un navigateur ne peut pas lire lui-même les pages d’autres sites : ce traitement doit donc s’exécuter sur votre serveur.

Options

Option	Valeur par défaut	Fonctionnement
`bookmarkResolver`	`null`	`function (url)` renvoyant les métadonnées, directement ou par une Promise : `{ title, description, image, favicon }`. Tous les champs sont facultatifs.
`bookmarkFaviconService`	`""` (désactivé)	Préfixe d’URL pour les icônes des sites. L’adresse de l’icône de la carte est ce préfixe suivi du domaine, par exemple `"/favicon-proxy?domain="`. Utilisé uniquement si le résolveur ne renvoie pas de `favicon`.
`text_insertbookmark`, `text_insertbookmarktitle`, `text_insertbookmarklabel`	`"Bookmark"`, `"Insert bookmark"`, `"Link URL"`	Infobulle du bouton, titre de la boîte de dialogue et libellé du champ.

L’éditeur avec une carte simple affichant uniquement richtexteditor.com comme titre, puis comme domaine — Le même lien sans résolveur : le titre est le domaine, sans description, icône ni image.

Utilisation

Cliquez sur le bouton, appelez editor1.execCommand("insertbookmark"), ou choisissez « Bookmark » dans le menu de commandes slash. Saisissez l’adresse, puis appuyez sur Entrée ou sur Insert.
Seuls http et https sont acceptés. Un domaine sans protocole, comme richtexteditor.com/docs/quick-start, est précédé de https://. Les adresses javascript:, data:, vbscript: et file: sont refusées avec le message « Enter a valid http(s) URL. »
Pendant l’exécution du résolveur, la boîte de dialogue affiche « Fetching preview… ». En cas d’échec ou de délai supérieur à 8 secondes, une carte simple est insérée à la place.
Pour supprimer une carte, survolez-la et cliquez sur le × rond dans son coin, ou appuyez sur Suppr ou Retour arrière lorsque le curseur est dessus. Il n’existe pas d’étape de modification : supprimez la carte puis insérez-la à nouveau.

À savoir

La carte enregistrée est un lien. Avec le résolveur ci-dessus, le contenu était le suivant :

<p><a class="rte-bookmark-card" data-rte-block="bookmark" href="https://richtexteditor.com/docs/quick-start" target="_blank" rel="noopener noreferrer" contenteditable="false" style=""><span class="rte-bookmark-remove" data-rte-bookmark-remove="1" role="button" tabindex="0" aria-label="Remove bookmark" title="Remove bookmark">x</span><span class="rte-bookmark-main"><span class="rte-bookmark-title">Quick start - RichTextEditor</span><span class="rte-bookmark-desc">Add the editor to a page in a few lines: download or npm, two script tags, one constructor call.</span><span class="rte-bookmark-url"><img class="rte-bookmark-favicon" src="/img/editor_32x32.png" alt="" width="16" height="16"><span>richtexteditor.com</span></span></span><span class="rte-bookmark-thumb" style="background-image:url('/img/editor-image.png')"></span></a></p>

L’apparence de la carte (bordure, disposition, taille de la miniature) provient d’une feuille de style que le plugin ajoute uniquement dans l’éditeur. Votre page d’affichage doit définir ses propres règles pour les classes rte-bookmark-*. Masquez-y aussi .rte-bookmark-remove : le × est enregistré avec la carte.
Les adresses de l’icône et de la miniature sont enregistrées telles que le résolveur les fournit et chargées par le navigateur de chaque lecteur. Renvoyez des adresses sur votre propre serveur (ou un proxy) si vous souhaitez éviter que les navigateurs des lecteurs contactent le site lié.
Sans résolveur ni bookmarkFaviconService, l’insertion d’une carte n’effectue aucune requête réseau. La note de la boîte de dialogue mentionne une favicon, mais il n’y en a aucune par défaut.
Les filtres de nettoyage doivent conserver a avec href, target, rel et class, les éléments internes span et img, ainsi que l’attribut style de la miniature (il contient l’image).

Voir aussi : intégration automatique, puces intelligentes, démonstration de blocs enrichis.