van-ons / laraberg
A Gutenberg implementation for Laravel
Installs: 299 587
Dependents: 15
Suggesters: 0
Security: 0
Stars: 1 334
Watchers: 49
Forks: 144
Open Issues: 2
Requires
- embed/embed: ^3.3
Requires (Dev)
- orchestra/testbench: ^3.7
- phpunit/phpunit: ^7.0
- dev-main
- v2.0.4
- v2.0.3
- v2.0.2
- v2.0.1
- v2.0.0
- v2.0.0-rc12
- v2.0.0-rc11
- v2.0.0-rc10
- v2.0.0-rc9
- v2.0.0-rc8
- v2.0.0-rc7
- v2.0.0-rc6
- v2.0.0-rc5
- v2.0.0-rc4
- v2.0.0-rc3
- v2.0.0-rc2
- v2.0.0-rc1
- v1.x-dev
- v1.1.1
- v1.1.0
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
- v1.0.0-rc
- v0.0.7-beta
- v0.0.6-beta
- v0.0.5-beta
- v0.0.4-beta
- v0.0.3-beta
- v0.0.2-beta
- v0.0.1-beta
- dev-lifecycle-to-php82
- dev-fix/oembed-service
- dev-dev
This package is auto-updated.
Last update: 2024-11-07 08:23:28 UTC
README
Laraberg aims to provide an easy way to integrate the Gutenberg editor with your Laravel projects. It takes the Gutenberg editor and adds all the communication and data it needs function in a Laravel environment.
Table of Contents
Installation
Install package using composer:
composer require van-ons/laraberg
Add vendor files to your project (CSS, JS & Config):
php artisan vendor:publish --provider="VanOns\Laraberg\LarabergServiceProvider"
JavaScript and CSS files
The package provides a JS and CSS file that should be present on the page you want to use the editor on:
<link rel="stylesheet" href="{{asset('vendor/laraberg/css/laraberg.css')}}"> <script src="{{ asset('vendor/laraberg/js/laraberg.js') }}"></script>
Dependencies
The Gutenberg editor expects React, ReactDOM, Moment and JQuery to be in the environment it runs in. An easy way to do this would be to add the following lines to your page:
<script src="https://unpkg.com/react@17.0.2/umd/react.production.min.js"></script> <script src="https://unpkg.com/react-dom@17.0.2/umd/react-dom.production.min.js"></script>
Updating
When updating Laraberg you have to publish the vendor files again by running this command:
php artisan vendor:publish --provider="VanOns\Laraberg\LarabergServiceProvider" --tag="public" --force
Usage
Initializing the Editor
The Gutenberg editor should replace an existing textarea in a form. On submit the raw content from the editor will be put in the 'value' attribute of this textarea.
<textarea id="[id_here]" name="[name_here]" hidden></textarea>
In order to edit content on an already existing model we have to set the value of the textarea to the raw content that the Gutenberg editor provided.
<textarea id="[id_here]" name="[name_here]" hidden>{{ $model->content }}</textarea>
To initialize the editor all we have to do is call the initialize function with the id of the textarea. You probably want to do this inside a DOMContentLoaded event.
And that's it! The editor will replace the textarea in the DOM and on a form submit the editor content will be available in the textarea's value attribute.
Laraberg.init('[id_here]')
Configuration options
The init()
function takes an optional configuration object which can be used to change Laraberg's behaviour in some ways.
const options = {} Laraberg.init('[id_here]', options)
The options
object should be a EditorSettings object.
interface EditorSettings { height?: string; mediaUpload?: (upload: MediaUpload) => void; fetchHandler?: FetchHandler; disabledCoreBlocks?: string[]; alignWide?: boolean; supportsLayout?: boolean; maxWidth?: number; imageEditing?: boolean; colors?: Color[]; gradients?: Gradient[]; fontSizes?: FontSize[]; }
Models
In order to add the editor content to a model Laraberg provides the 'RendersContent' trait.
use VanOns\Laraberg\Traits\RendersContent; class MyModel extends Model { use RendersContent; }
This adds the render
method to your model which takes care of rendering the raw editor content. By default the render
methods renders the content in the content
column, the column can be changed by changing the $contentColumn
property on your model to the column that you want to use instead.
use VanOns\Laraberg\Traits\RendersContent; class MyModel extends Model { use RendersContent; protected $contentColumn = 'my_column'; }
Or by passing the column name to the render method.
$model->render('my_column');
Custom Blocks
Gutenberg allows developers to create custom blocks. For information on how to create a custom block you should read the Gutenberg documentation.
Registering custom blocks is fairly easy. A Gutenberg block requires the properties title
, icon
, and categories
. It also needs to implement the functions edit()
and save()
.
const myBlock = { title: 'My First Block!', icon: 'universal-access-alt', category: 'my-category', edit() { return <h1>Hello editor.</h1> }, save() { return <h1>Hello saved content.</h1> } } Laraberg.registerBlockType('my-namespace/my-block', myBlock)
Server-side blocks
Server-side blocks can be registered in Laravel. You probably want to create a ServiceProvider and register your server-side blocks in it's boot
method.
class BlockServiceProvider extends ServiceProvider { public function boot() { Laraberg::registerBlockType( 'my-namespace/my-block', [], function ($attributes, $content) { return view('blocks.my-block', compact('attributes', 'content')); } ); } }
WordPress exports
Laraberg uses the WordPress Gutenberg packages under the hood, a lot of those packages expose functionality that let's you customize the editor. You can find these packages in Javascript in the global Laraberg
object.
Laraberg.wordpress.blockEditor
Laraberg.wordpress.blocks
Laraberg.wordpress.components
Laraberg.wordpress.data
Laraberg.wordpress.element
Laraberg.wordpress.hooks
Laraberg.wordpress.serverSideRender