From 0fb6c9011f85425af2dbcea9de36d4d4059cb3fa Mon Sep 17 00:00:00 2001 From: bogdanvlviv Date: Sat, 5 Jan 2019 13:20:02 +0200 Subject: Add Action Text to guides [ci skip] - Move some actiontext/README.md content to Action Text Overview guide - I added WIP label to that guide since we definitely want to complement it. - Add Action Text to Major Features of Rails 6.0 Similar approach was used in #34812 --- guides/source/6_0_release_notes.md | 16 ++++++ guides/source/action_text_overview.md | 99 +++++++++++++++++++++++++++++++++++ guides/source/documents.yaml | 5 ++ 3 files changed, 120 insertions(+) create mode 100644 guides/source/action_text_overview.md (limited to 'guides') diff --git a/guides/source/6_0_release_notes.md b/guides/source/6_0_release_notes.md index 9716132156..6f1db126c3 100644 --- a/guides/source/6_0_release_notes.md +++ b/guides/source/6_0_release_notes.md @@ -6,6 +6,7 @@ Ruby on Rails 6.0 Release Notes Highlights in Rails 6.0: * Action Mailbox +* Action Text * Parallel Testing These release notes cover only the major changes. To learn about various bug @@ -37,6 +38,21 @@ Major Features to route incoming emails to controller-like mailboxes. You can read more about Action Mailbox in the [Action Mailbox Basics](action_mailbox_basics.html) guide. +### Action Text + +[Pull Request](https://github.com/rails/rails/pull/34873) + +[Action Text](https://github.com/rails/rails/tree/6-0-stable/actiontext) +brings rich text content and editing to Rails. It includes +the [Trix editor](https://trix-editor.org) that handles everything from formatting +to links to quotes to lists to embedded images and galleries. +The rich text content generated by the Trix editor is saved in its own +RichText model that's associated with any existing Active Record model in the application. +Any embedded images (or other attachments) are automatically stored using +Active Storage and associated with the included RichText model. + +You can read more about Action Text in the [Action Text Overview](action_text_overview.html) guide. + ### Parallel Testing [Pull Request](https://github.com/rails/rails/pull/31900) diff --git a/guides/source/action_text_overview.md b/guides/source/action_text_overview.md new file mode 100644 index 0000000000..08ec35e52a --- /dev/null +++ b/guides/source/action_text_overview.md @@ -0,0 +1,99 @@ +**DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON https://guides.rubyonrails.org.** + +Action Text Overview +==================== + +This guide provides you with all you need to get started in handling +rich text content. + +After reading this guide, you will know: + +* How to configure Action Text. +* How to handle rich text content. +* How to style rich text content. + +-------------------------------------------------------------------------------- + +Introduction +------------ + +Action Text brings rich text content and editing to Rails. It includes +the [Trix editor](https://trix-editor.org) that handles everything from formatting +to links to quotes to lists to embedded images and galleries. +The rich text content generated by the Trix editor is saved in its own +RichText model that's associated with any existing Active Record model in the application. +Any embedded images (or other attachments) are automatically stored using +Active Storage and associated with the included RichText model. + +## Trix compared to other rich text editors + +Most WYSIWYG editors are wrappers around HTML’s `contenteditable` and `execCommand` APIs, +designed by Microsoft to support live editing of web pages in Internet Explorer 5.5, +and [eventually reverse-engineered](https://blog.whatwg.org/the-road-to-html-5-contenteditable#history) +and copied by other browsers. + +Because these APIs were never fully specified or documented, +and because WYSIWYG HTML editors are enormous in scope, each +browser's implementation has its own set of bugs and quirks, +and JavaScript developers are left to resolve the inconsistencies. + +Trix sidesteps these inconsistencies by treating contenteditable +as an I/O device: when input makes its way to the editor, Trix converts that input +into an editing operation on its internal document model, then re-renders +that document back into the editor. This gives Trix complete control over what +happens after every keystroke, and avoids the need to use execCommand at all. + +## Installation + +Run `rails action_text:install` to add the Yarn package and copy over the necessary migration. + +## Examples + +Adding a rich text field to an existing model: + +```ruby +# app/models/message.rb +class Message < ApplicationRecord + has_rich_text :content +end +``` + +Then refer to this field in the form for the model: + +```erb +<%# app/views/messages/_form.html.erb %> +<%= form_with(model: message) do |form| %> +
+ <%= form.label :content %> + <%= form.rich_text_area :content %> +
+<% end %> +``` + +And finally display the sanitized rich text on a page: + +```erb +<%= @message.content %> +``` + +To accept the rich text content, all you have to do is permit the referenced attribute: + +```ruby +class MessagesController < ApplicationController + def create + message = Message.create! params.require(:message).permit(:title, :content) + redirect_to message + end +end +``` + +## Custom styling + +By default, the Action Text editor and content is styled by the Trix defaults. +If you want to change these defaults, you'll want to remove +the `app/assets/stylesheets/actiontext.css` linker and base your stylings on +the [contents of that file](https://raw.githubusercontent.com/basecamp/trix/master/dist/trix.css). + +You can also style the HTML used for embedded images and other attachments (known as blobs). +On installation, Action Text will copy over a partial to +`app/views/active_storage/blobs/_blob.html.erb`, which you can specialize. diff --git a/guides/source/documents.yaml b/guides/source/documents.yaml index 0f836bdf48..25e4fdb4e6 100644 --- a/guides/source/documents.yaml +++ b/guides/source/documents.yaml @@ -80,6 +80,11 @@ work_in_progress: true url: action_mailbox_basics.html description: This guide describes how to use Action Mailbox to receive emails. + - + name: Action Text Overview + work_in_progress: true + url: action_text_overview.html + description: This guide describes how to use Action Text to handle rich text content. - name: Active Job Basics url: active_job_basics.html -- cgit v1.2.3