Skip to content

Commit 6de162c

Browse files
committed
Update README
1 parent f12a80b commit 6de162c

File tree

1 file changed

+13
-12
lines changed

1 file changed

+13
-12
lines changed

README.md

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,9 @@
11
<p align="center" style="margin-top: 2rem; margin-bottom: 2rem;"><img src="/art/rich-text-laravel-logo.svg" alt="Logo Rich Text Laravel" /></p>
22

33
<p align="center">
4-
<a href="https://github.com/tonysm/rich-text-laravel/workflows/run-tests/badge.svg">
5-
<img src="https://img.shields.io/github/actions/workflow/status/tonysm/rich-text-laravel/run-tests.yml?branch=main" />
6-
</a>
7-
<a href="https://packagist.org/packages/tonysm/rich-text-laravel">
8-
<img src="https://img.shields.io/packagist/dt/tonysm/rich-text-laravel" alt="Total Downloads">
9-
</a>
10-
<a href="https://packagist.org/packages/tonysm/rich-text-laravel">
11-
<img src="https://img.shields.io/github/license/tonysm/rich-text-laravel" alt="License">
12-
</a>
4+
<a href="https://github.com/tonysm/rich-text-laravel/workflows/run-tests/badge.svg"><img src="https://img.shields.io/github/actions/workflow/status/tonysm/rich-text-laravel/run-tests.yml?branch=main" /></a>
5+
<a href="https://packagist.org/packages/tonysm/rich-text-laravel"><img src="https://img.shields.io/packagist/dt/tonysm/rich-text-laravel" alt="Total Downloads"></a>
6+
<a href="https://packagist.org/packages/tonysm/rich-text-laravel"><img src="https://img.shields.io/github/license/tonysm/rich-text-laravel" alt="License"></a>
137
</p>
148

159
Integrates the [Trix Editor](https://trix-editor.org/) with Laravel. Inspired by the Action Text gem from Rails.
@@ -68,6 +62,7 @@ There are two ways of using the package:
6862
Below, we cover each usage way. It's recommended that you at least read the [Trix documentation](https://github.com/basecamp/trix) at some point to get an overview of the client-side of it.
6963

7064
### The RichText Model
65+
7166
<a name="rich-text-model"></a>
7267

7368
The recommended way is to keep the rich text content outside of the model itself. This will keep the models lean when you're manipulating them, and you can (eagerly or lazily) load the rich text fields only where you need the rich text content.
@@ -122,7 +117,7 @@ Similarly to the Content class, the RichText model will implement the `__toStrin
122117
{!! $post->body !!}
123118
```
124119

125-
*Note*: since the HTML output is NOT escaped, make sure you sanitize it before rendering. See the [sanitization](#sanitization) section for more about this.
120+
_Note_: since the HTML output is NOT escaped, make sure you sanitize it before rendering. See the [sanitization](#sanitization) section for more about this.
126121

127122
The `HasRichText` trait will also add an scope which you can use to eager load the rich text fields (remember, each field will have its own relationship), which you can use like so:
128123

@@ -221,6 +216,7 @@ Laravel's Encryption component relies on the `APP_KEY` master key. If you need t
221216
Additionally, the stored content attachments rely on the [Globalid Laravel](https://github.com/tonysm/globalid-laravel) package. That package generates a derived key based on your `APP_KEY`. When rotating the `APP_KEY`, you'll also need to update all stored content attachments's `sgid` attributes.
222217

223218
### The AsRichTextContent Trait
219+
224220
<a name="asrichtextcontent-trait"></a>
225221

226222
In case you don't want to use the recommended structure (either because you have strong opinions here or you want to rule your own database structure), you may skip the entire recommended database structure and use the `AsRichTextContent` custom cast on your rich text content field. For instance, if you're storing the `body` field on the `posts` table, you may do it like so:
@@ -267,13 +263,13 @@ To this minified version:
267263
<rich-text-attachment content-type="image/jpeg" filename="blue.png" filesize="1168" height="300" href="http://example.com/blue.jpg" url="http://example.com/blue.jpg" width="300" caption="testing this caption" presentation="gallery"></rich-text-attachment>
268264
```
269265

270-
And when it renders it again, it will re-render the remote image again inside the `rich-text-attachment` tag. You can render the content for *viewing* by simply echoing out the output, something like this:
266+
And when it renders it again, it will re-render the remote image again inside the `rich-text-attachment` tag. You can render the content for _viewing_ by simply echoing out the output, something like this:
271267

272268
```blade
273269
{!! $post->content !!}
274270
```
275271

276-
*Note*: since the HTML output is NOT escaped, make sure you sanitize it before rendering. See the [sanitization](#sanitization) section for more about this.
272+
_Note_: since the HTML output is NOT escaped, make sure you sanitize it before rendering. See the [sanitization](#sanitization) section for more about this.
277273

278274
When feeding the Trix editor again, you need to do it differently:
279275

@@ -284,6 +280,7 @@ When feeding the Trix editor again, you need to do it differently:
284280
Rendering for the editor is a bit different, so it has to be like that.
285281

286282
### Image Upload
283+
287284
<a name="image-upload"></a>
288285

289286
Trix shows the attachment button, but it doesn't work out-of-the-box, we must implement that behavior in our applications.
@@ -303,6 +300,7 @@ The package contains a demo application with basic image uploading functionality
303300
However, you're not limited to this basic attachment handling in Trix. A more advanced attachment behavior could create its own backend model, then set the `sgid` attribute on the attachment, which would let you have full control over the rendered HTML when the document renders outside the Trix editor.
304301

305302
### Content Attachments
303+
306304
<a name="attachments"></a>
307305

308306
With Trix we can have [content Attachments](https://github.com/basecamp/trix#inserting-a-content-attachment). In order to cover this, let's build a users mentions feature on top of Trix. There's a good [Rails Conf talk](https://youtu.be/2iGBuLQ3S0c?t=1556) building out this entire feature but with Rails. The workflow is pretty much the same in Laravel.
@@ -322,6 +320,7 @@ You may use Blade to render an HTML partial for the attachable. For a reference,
322320
You can later retrieve all attachments from that rich text content. See [The Content Object](#content-object) section for more.
323321

324322
### The Content Object
323+
325324
<a name="content-object"></a>
326325

327326
You may want to retrieve all the attachables in that rich text content at a later point and do something fancy with it, say _actually_ storing the User's mentions associated with the Post model, for example. Or you can fetch all the links inside that rich text content and do something with it.
@@ -427,6 +426,7 @@ class OpengraphEmbed implements AttachableContract
427426
You can see a full working implementation of this OpenGraph example in the Chat Workbench demo (or in [this PR](https://github.com/tonysm/rich-text-laravel/pull/56)).
428427

429428
### Plain Text Rendering
429+
430430
<a name="plain-text"></a>
431431

432432
Trix content can be converted to anything. This essentially means `HTML > something`. The package ships with a `HTML > Plain Text` implementation, so you can convert any Trix content to plain text by calling the `toPlainText()` method on it:
@@ -479,6 +479,7 @@ If you're attaching models, you can implement the `richTextAsPlainText(?string $
479479
|------------------------|
480480

481481
### Sanitization
482+
482483
<a name="sanitization"></a>
483484

484485
Since we're rendering user-generated HTML, you must sanitize it to avoid any security issues. Even though we control the input element, malicious users may tamper with HTML in the browser and swap it for something else that allows them to inject their own HTML.

0 commit comments

Comments
 (0)