mirror of
https://github.com/rails/rails.git
synced 2022-11-09 12:12:34 -05:00
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
This commit is contained in:
bogdanvlviv
parent
86517942e4
commit
0fb6c9011f
4 changed files with 122 additions and 60 deletions
|
|
@ -1,66 +1,8 @@
|
|||
# Action Text
|
||||
|
||||
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.
|
||||
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| %>
|
||||
…
|
||||
<div class="field">
|
||||
<%= form.label :content %>
|
||||
<%= form.rich_text_area :content %>
|
||||
</div>
|
||||
…
|
||||
<% 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.
|
||||
You can read more about Action Text in the [Action Text Overview](https://edgeguides.rubyonrails.org/action_text_overview.html) guide.
|
||||
|
||||
## License
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
99
guides/source/action_text_overview.md
Normal file
99
guides/source/action_text_overview.md
Normal file
|
|
@ -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| %>
|
||||
<div class="field">
|
||||
<%= form.label :content %>
|
||||
<%= form.rich_text_area :content %>
|
||||
</div>
|
||||
<% 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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue