Aperçu d'Action Text

1 Qu'est-ce qu'Action Text ?

Action Text apporte du contenu en texte enrichi et des fonctionnalités d'édition à Rails. Il inclut l'éditeur Trix qui gère tout, du formatage aux liens en passant par les citations, les listes, les images intégrées et les galeries. Le contenu en texte enrichi généré par l'éditeur Trix est enregistré dans son propre modèle RichText qui est associé à n'importe quel modèle Active Record existant dans l'application. Toutes les images intégrées (ou autres pièces jointes) sont automatiquement stockées à l'aide de Active Storage et associées au modèle RichText inclus.

2 Trix par rapport aux autres éditeurs de texte enrichi

La plupart des éditeurs WYSIWYG sont des enveloppes autour des API contenteditable et execCommand de HTML, conçues par Microsoft pour prendre en charge l'édition en direct des pages Web dans Internet Explorer 5.5, et ultérieurement rétro-ingénierées et copiées par d'autres navigateurs.

Étant donné que ces API n'ont jamais été entièrement spécifiées ou documentées, et étant donné que les éditeurs HTML WYSIWYG sont d'une ampleur considérable, chaque implémentation de navigateur a son propre ensemble de bugs et d'excentricités, et les développeurs JavaScript sont laissés pour résoudre les incohérences.

Trix contourne ces incohérences en traitant contenteditable comme un périphérique d'E/S : lorsque l'entrée parvient à l'éditeur, Trix convertit cette entrée en une opération d'édition sur son modèle de document interne, puis réaffiche ce document dans l'éditeur. Cela donne à Trix un contrôle total sur ce qui se passe après chaque frappe, et évite d'avoir à utiliser execCommand du tout.

3 Installation

Exécutez bin/rails action_text:install pour ajouter le package Yarn et copier la migration nécessaire. De plus, vous devez configurer Active Storage pour les images intégrées et les autres pièces jointes. Veuillez vous référer au guide Présentation d'Active Storage.

NOTE : Action Text utilise des relations polymorphiques avec la table action_text_rich_texts afin de pouvoir être partagé avec tous les modèles qui ont des attributs de texte enrichi. Si vos modèles avec du contenu Action Text utilisent des valeurs UUID pour les identifiants, tous les modèles qui utilisent des attributs Action Text devront utiliser des valeurs UUID pour leurs identifiants uniques. La migration générée pour Action Text devra également être mise à jour pour spécifier type: :uuid pour la ligne :record references.

Une fois l'installation terminée, une application Rails devrait avoir les modifications suivantes :

Les packages trix et @rails/actiontext doivent être requis dans votre point d'entrée JavaScript.
```
// application.js
import "trix"
import "@rails/actiontext"
```
La feuille de style trix sera incluse avec les styles Action Text dans votre fichier application.css.

4 Création de contenu en texte enrichi

Ajoutez un champ de texte enrichi à un modèle existant :

# app/models/message.rb
class Message < ApplicationRecord
  has_rich_text :content
end

ou ajoutez un champ de texte enrichi lors de la création d'un nouveau modèle en utilisant :

$ bin/rails generate model Message content:rich_text

NOTE : vous n'avez pas besoin d'ajouter un champ content à votre table messages.

Ensuite, utilisez rich_text_area pour faire référence à ce champ dans le formulaire du modèle :

<%# app/views/messages/_form.html.erb %>
<%= form_with model: message do |form| %>
  <div class="field">
    <%= form.label :content %>
    <%= form.rich_text_area :content %>
  </div>
<% end %>

Et enfin, affichez le contenu en texte enrichi nettoyé sur une page :

<%= @message.content %>

NOTE : Si une ressource jointe se trouve dans le champ content, elle peut ne pas s'afficher correctement à moins que vous n'ayez le package libvips/libvips42 installé localement sur votre machine. Consultez leur documentation d'installation pour savoir comment l'obtenir.

Pour accepter le contenu en texte enrichi, il vous suffit de permettre l'attribut référencé :

class MessagesController < ApplicationController
  def create
    message = Message.create! params.require(:message).permit(:title, :content)
    redirect_to message
  end
end

5 Rendu du contenu en texte enrichi

Par défaut, Action Text affiche le contenu en texte enrichi à l'intérieur d'un élément avec la classe .trix-content :

<%# app/views/layouts/action_text/contents/_content.html.erb %>
<div class="trix-content">
  <%= yield %>
</div>

Les éléments avec cette classe, ainsi que l'éditeur Action Text, sont stylisés par la feuille de style trix. Pour fournir vos propres styles, supprimez la ligne = require trix de la feuille de style app/assets/stylesheets/actiontext.css créée par l'installateur.

Pour personnaliser le HTML rendu autour du contenu en texte enrichi, modifiez la mise en page app/views/layouts/action_text/contents/_content.html.erb créée par l'installateur.

Pour personnaliser le HTML rendu pour les images intégrées et autres pièces jointes (connues sous le nom de blobs), modifiez le modèle app/views/active_storage/blobs/_blob.html.erb créé par l'installateur.

5.1 Rendu des pièces jointes

En plus des pièces jointes téléchargées via Active Storage, Action Text peut intégrer tout ce qui peut être résolu par un Signed GlobalID.

Action Text rend les éléments <action-text-attachment> intégrés en résolvant leur attribut sgid en une instance. Une fois résolue, cette instance est transmise à render. Le HTML résultant est intégré en tant que descendant de l'élément <action-text-attachment>.

Par exemple, considérons un modèle User :

# app/models/user.rb
class User < ApplicationRecord
  has_one_attached :avatar
end

user = User.find(1)
user.to_global_id.to_s #=> gid://MyRailsApp/User/1
user.to_signed_global_id.to_s #=> BAh7CEkiCG…

Ensuite, considérons un contenu de texte enrichi qui intègre un élément <action-text-attachment> qui fait référence au Signed GlobalID de l'instance User :

<p>Bonjour, <action-text-attachment sgid="BAh7CEkiCG…"></action-text-attachment>.</p>

Action Text utilise la chaîne "BAh7CEkiCG…" pour résoudre l'instance User. Ensuite, considérons la vue partielle users/user de l'application :

<%# app/views/users/_user.html.erb %>
<span><%= image_tag user.avatar %> <%= user.name %></span>

Le HTML résultant rendu par Action Text ressemblerait à ceci :

<p>Bonjour, <action-text-attachment sgid="BAh7CEkiCG…"><span><img src="..."> Jane Doe</span></action-text-attachment>.</p>

Pour rendre une autre vue partielle, définissez User#to_attachable_partial_path :

class User < ApplicationRecord
  def to_attachable_partial_path
    "users/attachable"
  end
end

Ensuite, déclarez cette vue partielle. L'instance User sera disponible en tant que variable locale partielle user :

<%# app/views/users/_attachable.html.erb %>
<span><%= image_tag user.avatar %> <%= user.name %></span>

Si Action Text ne parvient pas à résoudre l'instance User (par exemple, si l'enregistrement a été supprimé), une vue partielle de secours par défaut sera rendue.

Rails fournit une vue partielle globale pour les pièces jointes manquantes. Cette vue partielle est installée dans votre application à l'emplacement views/action_text/attachables/missing_attachable et peut être modifiée si vous souhaitez rendre un HTML différent.

Pour rendre une vue partielle différente pour les pièces jointes manquantes, définissez une méthode de niveau de classe to_missing_attachable_partial_path :

class User < ApplicationRecord
  def self.to_missing_attachable_partial_path
    "users/missing_attachable"
  end
end

Ensuite, déclarez cette vue partielle.

<%# app/views/users/missing_attachable.html.erb %>
<span>Utilisateur supprimé</span>

Pour intégrer le rendu de l'élément <action-text-attachment> d'Action Text, une classe doit :

inclure le module ActionText::Attachable
implémenter #to_sgid(**options) (disponible via le module GlobalID::Identification)
(facultatif) déclarer #to_attachable_partial_path
(facultatif) déclarer une méthode de niveau de classe #to_missing_attachable_partial_path pour gérer les enregistrements manquants

Par défaut, toutes les descendantes de ActiveRecord::Base incluent le module GlobalID::Identification et sont donc compatibles avec ActionText::Attachable.

6 Éviter les requêtes N+1

Si vous souhaitez précharger le modèle dépendant ActionText::RichText, en supposant que votre champ de texte enrichi s'appelle content, vous pouvez utiliser la portée nommée :

Message.all.with_rich_text_content # Précharge le corps sans les pièces jointes.
Message.all.with_rich_text_content_and_embeds # Précharge à la fois le corps et les pièces jointes.

7 API / Développement Backend

Une API backend (par exemple, en utilisant JSON) a besoin d'un point d'extrémité séparé pour télécharger des fichiers qui crée un ActiveStorage::Blob et renvoie son attachable_sgid :
```
{
  "attachable_sgid": "BAh7CEkiCG…"
}
```
Prenez ce attachable_sgid et demandez à votre frontend de l'insérer dans le contenu de texte enrichi en utilisant une balise <action-text-attachment> :
```
<action-text-attachment sgid="BAh7CEkiCG…"></action-text-attachment>
```

Cela est basé sur Basecamp, donc si vous ne trouvez toujours pas ce que vous cherchez, consultez cette documentation Basecamp.

Retour d'information

Vous êtes encouragé à contribuer à l'amélioration de la qualité de ce guide.

Veuillez contribuer si vous trouvez des fautes de frappe ou des erreurs factuelles. Pour commencer, vous pouvez lire notre contribution à la documentation section.

Vous pouvez également trouver du contenu incomplet ou des informations qui ne sont pas à jour. Veuillez ajouter toute documentation manquante pour la version principale. Assurez-vous de vérifier Edge Guides d'abord pour vérifier si les problèmes ont déjà été résolus ou non sur la branche principale. Consultez les Directives des guides Ruby on Rails pour le style et les conventions.

Si pour une raison quelconque vous repérez quelque chose à corriger mais ne pouvez pas le faire vous-même, veuillez ouvrir un problème.

Et enfin, toute discussion concernant la documentation de Ruby on Rails est la bienvenue sur le Forum officiel de Ruby on Rails.

Chapters

Retour d'information