README

Laraberg 编辑器旨在提供一个简单的方式来集成 Gutenberg 编辑器到您的 Laravel 项目中。它将 Gutenberg 编辑器及其在 Laravel 环境中运行所需的所有通信和数据添加进来。可以在 demo.laraberg.io 找到演示。如果您想看看如何实现 Laraberg 的示例，可以查看演示的代码 在这里。

目录

• 安装
  • JavaScript 和 CSS 文件
  • 依赖
• 更新
• 用法
  • 初始化编辑器
    • 不使用表单使用编辑器
    • 设置编辑器内容
    • 配置选项
  • 模型
    • 重命名 Gutenbergable 方法名称
  • 渲染 Gutenberg 内容
  • 自定义块
    • 注册块
    • 注册分类
  • 事件
  • 侧边栏
    • 复选框
    • 单选按钮
    • 选择
    • 文本
    • 文本域
• 配置
  • 样式
  • API 路由
  • Laravel 文件管理器
• 搜索回调
• 缺少的块
• 贡献

安装

使用 composer 安装包

composer require van-ons/laraberg

将供应商文件添加到您的项目（CSS、JS 和配置）

php artisan vendor:publish --provider="MarcAndreAppel\LarabergNG\LarabergNGServiceProvider"

为了存储 Gutenberg 编辑器的数据，Laraberg 需要运行一个数据库迁移

php artisan migrate

这将创建 'editor_contents' 和 'editor_blocks' 表。

JavaScript 和 CSS 文件

该软件包提供了一个 JS 和 CSS 文件，应包含在您想要使用编辑器的页面上

<link rel="stylesheet" href="{{asset('vendor/laraberg/css/laraberg.css')}}">

<script src="{{ asset('vendor/laraberg/js/laraberg.js') }}"></script>

依赖

Gutenberg 编辑器期望 React、ReactDOM、Moment 和 JQuery 在其运行的环境中。一种简单的方法是将以下行添加到您的页面上

<script src="https://unpkg.com/react@16.8.6/umd/react.production.min.js"></script>

<script src="https://unpkg.com/react-dom@16.8.6/umd/react-dom.production.min.js"></script>

更新

当更新 Laraberg 时，您必须通过运行此命令重新发布供应商文件

php artisan vendor:publish --provider="VanOns\Laraberg\LarabergServiceProvider" --tag="public" --force

用法

初始化编辑器

Gutenberg 编辑器应替换表单中的现有文本区域。在提交时，编辑器的原始内容将放入此文本区域的 'value' 属性中。

<textarea id="[id_here]" name="[name_here]" hidden></textarea>

为了编辑已存在的模型上的内容，我们必须将文本区域的值设置为 Gutenberg 编辑器提供的原始内容。

<textarea id="[id_here]" name="[name_here]" hidden>{{$model->getRawContent()}}</textarea>

要初始化编辑器，我们只需要调用带有文本区域 ID 的 initialize 函数。您可能想在 DOMContentLoaded 事件中这样做。

编辑器将替换 DOM 中的文本区域，并在表单提交时，编辑器内容将可用在 textarea 的值属性中。

Laraberg.init('[id_here]')

不使用表单使用编辑器

如果您想使用编辑器，但出于某些原因不想处理表单提交，有一种方法可以通过 JavaScript 获取编辑器的内容

let content = Laraberg.getContent()

设置编辑器内容

可以通过 JavaScript 设置编辑器的内

Laraberg.setContent('content')

配置选项

init() 函数接受一个可选的配置对象，可以用来以某种方式更改 Laraberg 的行为。

const options = {}
Laraberg.init('[id_here]', options)

options 对象可以包含以下可选键

模型

为了将编辑器内容添加到模型中，Laraberg 提供了 HasEditor 特性。

use MarcAndreAppel\LarabergNG\Models\Concerns\HasEditor;

class MyModel extends Model
 {
  use HasEditor;
  
}

这为您模型添加了多个属性，有助于您创建/更新/渲染 Gutenberg 内容。

$content = '...'; // This is the raw content from the Gutenberg editor
$model = new MyModel;

// Add or update the content
$model->editor_content = $content;

// Save the model
$model->save();

// Get the rendered HTML
$model->editor_content;

// Get the raw Gutenberg output, this should be in the target textarea when updating content
$model->editor_raw_content;

重命名 HasEditor 方法名称

总有可能您的模型已经实现了一个与 Gutenbergable 方法同名的方法。幸运的是，PHP Traits 提供了一种简单的方法来重命名特

class MyModel extends Model 
{
  use HasEditor {
    renderContent as renderEditorContent;
  }

  public function renderContent() {
    // Your method
  }
}

在这个例子中，您只需调用 renderEditorContent 方法来渲染内容。

渲染 Gutenberg 内容

渲染 Gutenberg 内容非常简单，过程如下

<div id="your_container"> <!-- The element you want to render the content in -->
  {!! $page->editor_content !!}
</div>

请注意，为了正确显示一些 WordPress 风格，页面中必须存在 Laraberg CSS。

<link rel="stylesheet" href="{{asset('vendor/laraberg/css/laraberg.css')}}">

自定义块

Gutenberg 允许开发者创建自定义块。有关如何创建自定义块的信息，应阅读 Gutenberg 文档。

注册块

注册自定义块相对简单。Gutenberg 块需要具有 title、icon 和 categories 属性。它还需要实现 edit() 和 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.registerBlock('my-namespace/my-block', myBlock)

注册分类

如果您想将自定义块添加到新类别，需要先添加该类别。

let title = 'My Category'
let slug = 'my-category'
Laraberg.registerCategory(title, slug)

事件

Laraberg 实现了 Laravel 事件，您可以使用它们来实施自己的监听器。事件包含一个 'content' 属性，其中包含相关的 Content 对象。有关 Laravel 事件如何工作的信息，您可以阅读 Laravel 文档。

• MarcAndreAppel\LarabergNG\Events\ContentCreated
• MarcAndreAppel\LarabergNG\Events\ContentRendered
• MarcAndreAppel\LarabergNG\Events\ContentUpdated

侧边栏

Laraberg 提供了一种将表单字段放入 Gutenberg 编辑器单独侧边栏的方法。这样，您可以让编辑器占据整个屏幕，同时仍有空间放置您的表单字段。这是通过将输入元素放入具有 .laraberg-sidebar 类的父元素中实现的。目前，这适用于以下输入类型

• 复选框
• 单选按钮
• 选择
• 文本
• 文本域

对于标签，Laraberg 首先检查元素是否分配了标签，并尝试使用它。如果没有分配标签，它将检查是否有占位符，并使用它作为标签。

要启用侧边栏，在初始化 Laraberg 时将 sidebar 选项设置为 true。

Laraberg.init('[id_here]', { sidebar: true })

复选框

<div class="laraberg-sidebar">
  ...
  <label for="article-public">Public</label>
  <input id="article-public" name="public" type="checkbox">
</div>

单选按钮

<div class="laraberg-sidebar">
  ...
  <label for="letter-a">A</label>
  <input type="radio" name="letter" id="letter-a" value="a" checked> 
  <label for="letter-b">B</label>
  <input type="radio" name="letter" id="letter-b" value="b"> 
  <label for="letter-c">C</label>
  <input type="radio" name="letter" id="letter-c" value="c">
</div>

选择

<div class="laraberg-sidebar">
  ...
  <label for="article-month">Month</label>
  <select id="article-month" name="month" class="uk-select uk-form-large ">
      <option value="1">January</option>
      <option value="2">February</option>
      <option value="3">March</option>
      <option value="4">April</option>
      ...
  </select>
</div>

文本

<div class="laraberg-sidebar">
  ...
  <input id="article-title" type="text" name="title" placeholder="Title" />
</div>

文本域

<div class="laraberg-sidebar">
  ...
  <textarea name="excerpt" id="article-excerpt" placeholder="Excerpt"></textarea>
</div>

配置

在初始化编辑器时，您可以提供一些配置选项。这仍是一个正在进行中的项目！

样式

您可以通过在选项对象中提供所需的值来设置编辑器的高度、最大高度和最小高度。

Laraberg.init('[id_here]', { height: '500px' })

Laraberg.init('[id_here]', { maxHeight: '500px' })

Laraberg.init('[id_here]', { minHeight: '500px' })

占位符

您可以通过向您的 textarea 添加占位符属性来更改默认的 Gutenberg 占位符。

<textarea placeholder="[placeholder_here]" id="[id_here]" name="[name_here]" hidden></textarea>

API 路由

发布供应商文件后，您可以在配置文件夹中找到 'laraberg.php' 文件。此文件允许您配置 API 路由。在这里，您可以更改路由的前缀和中间件。

当您更改路由前缀时，您还必须在初始化编辑器时提供该前缀，如下所示

Laraberg.init('[id_here]', { prefix: '/[prefix_here]' })

如果您希望自己定义路由，您可以在配置中将 'use_package_routes' 设置为 'false'。然后，您可以按照以下方式修改以下路由

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 文件管理器

Laraberg 支持 Laravel 文件管理器 以上传文件。要启用通过 Laravel 文件管理器上传媒体，应将 laravelFilemanager 字段设置为 true。这将向 Gutenberg 媒体块添加一个 '文件管理器' 按钮，用于打开 Laravel 文件管理器以上传和选择媒体文件。

Laraberg.init('[id_here]', { laravelFilemanager: true })

如果您没有使用 Laravel 文件管理器的默认路由，您可以在选项对象中提供 Laravel 文件管理器端点的位置，如下所示

Laraberg.init('[id_here]', { laravelFilemanager: { prefix: '/[lfm_prefix_here]' } })

注意：Laraberg 不会对您的 Laravel 文件管理器设置进行任何配置。默认情况下，许多媒体文件类型无法上传，除非它们在 Laravel 文件管理器配置文件中列入白名单。有关此信息，您可以查看 Laravel 文件管理器文档。

搜索回调

按钮块 有一个搜索页面或文章的字段。为了使用此功能，您可以在初始化 Laraberg 时传递一个回调函数。此回调函数将接收一个 search、perPage 和 type 参数。回调应返回包含标题和 URL 的对象数组或解析为这种数组的承诺。

let customSearch = (search, perPage, type) => {
  return [
    {
      title: 'Laraberg Demo',
      url: 'demo.laraberg.io'
    }
  ]
}

Laraberg.init('content', { searchCb: customSearch })

缺少的块

由于我们已禁用直接文件上传，一些媒体块需要媒体库才能操作。这意味着以下块目前只有在您使用Laravel Filemanager时才会启用

• 封面
• 画廊
• 媒体 & 文本

贡献

如果您想为Laraberg做出贡献，请查看CONTRIBUTING.md