diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index cb099017..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,67 +0,0 @@ -# How to contribute to Laraberg - -## Reporting issues - -When you have an issue with Laraberg there are a few steps you can take to increase the probability that it will get - picked up as - soon as possible: - -1. Do you think you can fix the issue yourself? Give it a shot! Check out [how to set up a development environment below](#setting-up-a-development-environment). We're open to any pull requests from small bugfixes to new features. If you're not sure that your pull request will be accepted you can contact us through a Github issue or through -[Gitter](https://gitter.im/VanOns/laraberg) to discuss. -2. Create a Github issue. Make sure to use the issue templates that are available. Following those templates makes it - easier to pinpoint the issue and prevents miscommunication. If your issue does not fit into any of the issue templates - try to be very specific when describing your issue. Reported issue's that consist of only one line of text are very - hard to - work with. - -## Setting up a development environment - -Setting up a development environment for Laraberg is not as straightforward as it could be. -Laraberg is dependent on the Gutenberg packages from WordPress, and since those are currently not available as an - easy to install NPM package we have to jump through some hoops to make those packages available to Laraberg. - - To install Gutenberg: -1. Clone the Gutenberg repository in any directory. -`git clone git@github.com:WordPress/gutenberg.git` -2. CD into the directory -`cd gutenberg` -3. Checkout the latest (working) release (you can check the Laraberg release notes to see what Gutenberg verison is - being used). -`git checkout vX.X.X` -4. Install it's dependencies -`npm install` -5. Build it! -`npm run build` -6. Link it! -`(sudo) npm link` - -Now Gutenberg is symlinked to your global node_modules folder and we can use it for the development of Laraberg. -1. Clone Laraberg -`git clone git@github.com:VanOns/laraberg.git` -2. Install dependencies -`composer install` -`yarn install` -3. Link Gutenberg packages -`npm link gutenberg` -4. Start development mode -`npm start` - -Now you'll have a local installation of Laraberg that you can use in any Laravel project by adding it to the - `composer.json`: - - ```json -{ - ... - "repositories": [ - { - "type": "path", - "url": "{path_to_laraberg_directory}" - } - ], - "require": { - "van-ons/laraberg": "dev-{branch_name}" - }, - ... -} - -``` diff --git a/README.md b/README.md index 56d955cd..cc5c50f2 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![Gitter](https://badges.gitter.im/VanOns/laraberg.svg)](https://gitter.im/VanOns/laraberg?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) -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. A demo can be found at [demo.laraberg.io](http://demo.laraberg.io/). If you would like to see an example of how to implement Laraberg you can take a look at the code from the demo [over here](https://github.com/VanOns/laraberg-demo). +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](#installation) @@ -13,29 +13,11 @@ Laraberg aims to provide an easy way to integrate the Gutenberg editor with your - [Updating](#updating) - [Usage](#usage) - [Initializing the Editor](#initializing-the-editor) - - [Using the Editor Wihout a Form](#using-the-editor-wihout-a-form) - - [Setting the editor content](#setting-the-editor-content) - - [Configuration options](#configuration-options) + - [Configuration options](#configuration-options) - [Models](#models) - - [Renaming Gutenbergable method names](#renaming-gutenbergable-method-names) - - [Rendering Gutenberg Content](#rendering-gutenberg-content) - [Custom Blocks](#custom-blocks) - - [Registering Blocks](#registering-blocks) - - [Registering Categories](#registering-categories) - - [Events](#events) - - [Sidebar](#sidebar) - - [Checkbox](#checkbox) - - [Radio](#radio) - - [Select](#select) - - [Text](#text) - - [Textarea](#textarea) -- [Configuration](#configuration) - - [Styling](#styling) - - [API Routes](#api-routes) - - [Laravel File Manager](#laravel-file-manager) -- [Search Callback](#search-callback) -- [Missing Blocks](#missing-blocks) -- [Contributing](#contributing) + - [Server-side blocks](#server-side-blocks) + - [WordPress exports](#wordpress-exports) # Installation @@ -51,14 +33,6 @@ Add vendor files to your project (CSS, JS & Config): php artisan vendor:publish --provider="VanOns\Laraberg\LarabergServiceProvider" ``` -In order to store the data for the Gutenberg editor, Laraberg needs to run a database migration: - -``` -php artisan migrate -``` - -This will create the 'lb_contents' and 'lb_blocks' tables. - ## 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: @@ -74,9 +48,9 @@ The package provides a JS and CSS file that should be present on the page you wa 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: ```html - + - + ``` # Updating @@ -99,7 +73,7 @@ The Gutenberg editor should replace an existing textarea in a form. On submit th 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. ```html - + ``` 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 insde a DOMContentLoaded event. @@ -110,23 +84,7 @@ And that's it! The editor will replace the textarea in the DOM and on a form sub Laraberg.init('[id_here]') ``` -### Using the Editor Wihout a Form - -If you want to use the editor, but for some reason do not want to deal with submitting forms there is a way to get the content from the editor through JavaScript: - -```js -let content = Laraberg.getContent() -``` - -### Setting the editor content - -It's possible to set the the editor's content using JavaScript: - -```js -Laraberg.setContent('content') -``` - -### Configuration options +## Configuration options The `init()` function takes an optional configuration object which can be used to change Laraberg's behaviour in some ways. ```js @@ -134,91 +92,58 @@ const options = {} Laraberg.init('[id_here]', options) ``` -The `options` object can contain the following optional keys: - -|Key |Type |Description | -|---------------------------|-------------|---------------------------------------------------------------------------------------------| -|**sidebar** |Boolean |Enables the Laraberg sidebar if `true` | -|**prefix** |String |The API prefix to use for requests (only use this if you changed the API location manually) | -|**laravelFilemanager** |Bool/Object |Enables Laravel Filemanager for fileuploads if value is truth. Can be an object that contains configuration options. See [Laravel File Manager](#laravel-file-manager). | -|**sidebar** |Boolean |Enables the Laraberg sidebar if `true` | -|**searchCb** |Function |Will be called when using certain search fields within Gutenberg. See [Search Callback](#search-callback).| -|**height** |String |Sets the height of the editor. Value must be a valid css height value (e.g. '10px', '50%', '100vh').| -|**minHeight** |String |Sets the minHeight of the editor. Value must be a valid css min-height value (e.g. '10px', '50%', '100vh').| -|**maxHeight** |String |Sets the maxHeight of the editor. Value must be a valid css max-height value (e.g. '10px', '50%', '100vh').| +The `options` object should be a EditorSettings object. + +```typescript +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 'Gutenbergable' trait. +In order to add the editor content to a model Laraberg provides the 'RendersContent' trait. ```php -use VanOns\Laraberg\Models\Gutenbergable; +use VanOns\Laraberg\Traits\RendersContent; class MyModel extends Model { - use Gutenbergable; + use RendersContent; } ``` -This adds multiple attributes to your model that will help you with creating/updating/rendering the Gutenberg content. +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. ```php -$content // This is the raw content from the Gutenberg editor -$model = new MyModel; - -// Add or update the content -$model->lb_content = $content; - -// Save the model -$model->save(); - -// Get the rendered HTML -$model->lb_content; - -// Get the raw Gutenberg output, this should be in the target textarea when updating content -$model->lb_raw_content; -``` - -> Note: The old renderContent, getRawContent, getRenderedContent and setContent methods from v0.0.4-beta and lower are deprecated and will be removed in a future release. - -### Renaming Gutenbergable method names - -There is always the possibility that your model already implements a method with the same name as one of the Gutenbergable methods. Luckily PHP Traits provide an easy way to rename the methods from a trait: +use VanOns\Laraberg\Traits\RendersContent; -```php class MyModel extends Model { - use Gutenbergable { - renderContent as renderLBContent; - } + use RendersContent; - public function renderContent() { - // Your method - } + protected $contentColumn = 'my_column'; } ``` -In this example you can just call the 'renderLBContent' method to render the content. - -## Rendering Gutenberg Content -Rendering the Gutenberg content is very simple and happens like this: +Or by passing the column name to the render method. -```html -
- {!! $page->lb_content !!} -
-``` - -Keep in mind that in order to correctly display some of the Wordpress styling the Laraberg CSS has to be present on the page: - -```html - +```php +$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.](https://wordpress.org/gutenberg/handbook/designers-developers/developers/tutorials/block-tutorial/writing-your-first-block-type/) -### Registering Blocks - 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()`. ```js @@ -236,186 +161,38 @@ const myBlock = { } } -Laraberg.registerBlock('my-namespace/my-block', myBlock) -``` - -### Registering Categories - -If you want to add your custom block to a new category you need to add that category first: - -```js -let title = 'My Category' -let slug = 'my-category' -Laraberg.registerCategory(title, slug) -``` - -## Events - -Laraberg implements Laravel events that you can use to implement your own listeners. The events contain a 'content' attribute that contains the relevant Content object. For information on how Laravel events work you can read the [Laravel documentation](https://laravel.com/docs/5.8/events). - -- VanOns\Laraberg\Events\ContentCreated -- VanOns\Laraberg\Events\ContentRendered -- VanOns\Laraberg\Events\ContentUpdated - -## Sidebar - -Laraberg provides a way to put your form fields in a seperate sidebar in the Gutenberg editor. This way you can let the editor take the entire screen while still having a place for your form fields. This is done by putting the input element in a parent element with the `.laraberg-sidebar` class. This is currently supported for the following input types: -- Checkbox -- Radio -- Select -- Text -- Textarea - -For the labels Laraberg first checks if there is a label assigned to the element and will try to use that. If there is no label assigned it will check if there is a placeholder and use that as the label. - -To enable the sidebar set the `sidebar` option to true when initializing Laraberg: -```js -Laraberg.init('[id_here]', { sidebar: true }) -``` - -### Checkbox -```HTML -
- ... - - -
-``` - -### Radio - -```HTML -
- ... - - - - - - -
-``` - -### Select -```HTML -
- ... - - -
-``` - -### Text -```HTML -
- ... - -
-``` - -### Textarea -```HTML -
- ... - -
-``` - -# Configuration - -When initializing the editor there are a number of configuration options you can provide. This is still a work in progress! - -## Styling - -It is possible to set the height, maxHeight, and minHeight of the editor by providing the desired values in the options object: - -```js -Laraberg.init('[id_here]', { height: '500px' }) - -Laraberg.init('[id_here]', { maxHeight: '500px' }) - -Laraberg.init('[id_here]', { minHeight: '500px' }) -``` - -## Placeholder - -You can change the default Gutenberg placeholder by adding a placeholder attribute to your textarea: - -```html - +Laraberg.registerBlockType('my-namespace/my-block', myBlock) ``` -## API Routes +### Server-side blocks -After publishing the vendor files you can find the 'laraberg.php' file in your config folder. This file allows you to configure the API Routes. Here you can change the URL prefix and the middleware for the routes. - -When you change the route prefix you also have to provide the prefix when you initialize the editor like this: - -```js -Laraberg.init('[id_here]', { prefix: '/[prefix_here]' }) -``` - -If you wish to define the routes yourself you can do that by setting 'use_package_routes' to 'false' in the config. Then you can take the following routes and make changes as you see fit: +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. ```php -Route::group(['prefix' => 'laraberg', 'middleware' => ['web', 'auth']], function() { - Route::apiResource('blocks', 'VanOns\Laraberg\Http\Controllers\BlockController'); - Route::get('oembed', 'VanOns\Laraberg\Http\Controllers\OEmbedController'); -}); -``` - -## Laravel File Manager - -Laraberg supports [Laravel File Manager](https://unisharp.github.io/laravel-filemanager/) for uploading files. To enable uploading media through Laravel File Manager the laravelFilemanager field should be set to true. This will add a 'File Manager' button to the Gutenberg media blocks that will open Laravel File Manager for uploading and selecting media files. - -```js -Laraberg.init('[id_here]', { laravelFilemanager: true }) -``` - -If you are not using the default routes for Laravel File Manager you can provide the location of your Laravel File Manager endpoints in the options object like this: - -```js -Laraberg.init('[id_here]', { laravelFilemanager: { prefix: '/[lfm_prefix_here]' } }) -``` - -> Note: Laraberg does not do any configuration on your Laravel File Manager setup. By default a lot of media filetypes can not be uploaded unless they are whitelisted in the Laravel File Manager configuration file. For more information on this you can check the [Laravel File Manager documentation](https://unisharp.github.io/laravel-filemanager/config). - -# Search Callback - -The **button block** has a field that searches for pages or aritcles. In order to use this functionality you can pass a -callback function when initializing Laraberg. This callback functions will receive a `search`, `perPage` and `type` parameter. The callback should return an array of objects that contain a title and an URL or a promise that resolves to such an array. - -```javascript -let customSearch = (search, perPage, type) => { - return [ - { - title: 'Laraberg Demo', - url: 'demo.laraberg.io' +class BlockServiceProvider extends ServiceProvider { + public function boot() { + Laraberg::registerBlockType( + 'my-namespace/my-block', + [], + function ($attributes, $content) { + return view('blocks.my-block', compact('attributes', 'content')); + } + ); } - ] } - -Laraberg.init('content', { searchCb: customSearch }) ``` -# Missing Blocks - -Since we have disabled direct file uploading, some of the media blocks require a media library to operate. -This means that the following blocks will only be enabled when you're using Laravel Filemanager for now: - -- Cover -- Gallery -- Media & Text +## WordPress exports -# Contributing +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. -If you want to contribute to Laraberg checkout the [CONTRIBUTING.md](https://github.com/VanOns/laraberg/blob/master/CONTRIBUTING.md) +- `Laraberg.wordpress.blockEditor` +- `Laraberg.wordpress.blocks` +- `Laraberg.wordpress.components` +- `Laraberg.wordpress.data` +- `Laraberg.wordpress.element` +- `Laraberg.wordpress.hooks` +- `Laraberg.wordpress.serverSideRender`