Skip to content

Latest commit

 

History

History
152 lines (108 loc) · 5.28 KB

README.md

File metadata and controls

152 lines (108 loc) · 5.28 KB
Raw

Laravel Nova Editor JS Field

Latest Version on Github Total Downloads

A Laravel Nova implementation of Editor.js by @advoor.

Installation

Install via composer:

composer require advoor/nova-editor-js

Publish the config file

php artisan vendor:publish --provider="Advoor\NovaEditorJs\FieldServiceProvider"

Version Compatibility

Laravel Nova 4.x isn't backwards compatible with 3.x, so we had to make a version split. Please use the below table to find which versions are suitable for your installation.

Package version Nova Version Laravel Version PHP version
3.x 4.x 8.x - 10.x 8.1+
2.x 2.x - 3.x 5.x - 8.x 5.6 - 7.4

Note that we really pushed the PHP version up. If you're staying on new versions of Laravel and Nova, we're expecting your PHP version to match that behaviour.

Upgrade

See the upgrade guide.

Usage

To add EditorJS to your application, you'll need to modify your Nova resource. For ease-of-use we also recommend to update your models, but that's optional.

Updating your Nova resource

This package exposes a NovaEditorJsField that takes care of displaying the HTML contents and providing the user with the EditorJS field.

To use it, simply import the field,

use Advoor\NovaEditorJs\NovaEditorJsField;

use it in your fields array,

return [
    // …
    NovaEditorJsField::make('about'),
];

And boom, you've got yourself a fancy editor.

Updating your models (optional)

For ease-of-use, we recommend you add the NovaEditorJsCast to the $casts on your models. This will map the value to a NovaEditorJsData model, which can be returned in Blade (rendering HTML), or sent via API calls (rendering JSON, unless you call toHtml on it or cast it to a string).

use Advoor\NovaEditorJs\NovaEditorJsCast;

class User extends Model {
    protected $casts = [
        'about' => NovaEditorJsCast::class,
    ];
}

Since the NovaEditorJsData model is an Htmlable, Blade will recognize it as safe HTML. This means you don't have to use Blade "unescaped statements".

<article>
    <h1>About {{ $user->name }}</h1>
    {{ $user->about }}
</article>

Rendering HTML without model changes

You can also use the NovaEditorJs facade to render HTML from stored data.

NovaEditorJs::generateHtmlOutput($user->about);

The return value of generateHtmlOutput is an HtmlString, which is treated as safe by Blade. This means you don't have to use Blade "unescaped statements".

<article>
    <h1>About {{ $user->name }}</h1>
    {{ NovaEditorJs::generateHtmlOutput($user->about) }}
</article>

Customizing

You can configure the editor settings and what tools the Editor should use, by updating the editorSettings and toolSettings property in the config file respectively.

From the config, you can define the following editor settings:

  • placeholder (docs) - The placeholder to show in an empty editor
  • defaultBlock (docs) - The block that's used by default
  • autofocus (docs) - If the editor should auto-focus, only use if you never have multiple editors on a page and after considering the accessibility implications
  • rtl (docs) - Set to true to enable right-to-left mode, for languages like Arabic and Hebrew

Furthermore, you can customize the tools the editor should use. The following tools are enabled by default:

You can customize the views for each component, by changing the view in resources/views/vendor/nova-editor-js/.

† The Embeds tool is triggered by pasting URLs to embeddable content. It does not have an entry in the "Add" menu.

Registering custom components

Please refer to the extending Nova EditorJS guide on instructions on how to register custom components.