README

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

目录

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

安装

使用 Composer 安装包

composer require aruszala/laraberg:dev-master

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

php artisan vendor:publish --provider="aruszala\Laraberg\LarabergServiceProvider"

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

php artisan migrate

这将创建 'lb_contents' 和 'lb_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="aruszala\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 中的文本区域，在表单提交时，编辑器的内容将可用在文本区域的值属性中。

Laraberg.init('[id_here]')

在不使用表单的情况下使用编辑器

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

let content = Laraberg.getContent()

设置编辑器内容

可以使用 JavaScript 设置编辑器的内容

Laraberg.setContent('content')

配置选项

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

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

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

模型

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

use aruszala\Laraberg\Models\Gutenbergable;

class MyModel extends Model {
  use Gutenbergable;
}

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

$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;

注意：旧版本的 renderContent、getRawContent、getRenderedContent 和 setContent 方法从 v0.0.4-beta 及更低版本开始已弃用，将在未来的版本中删除。

重命名 Gutenbergable 方法名称

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

class MyModel extends Model {
  use Gutenbergable {
    renderContent as renderLBContent;
  }

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

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

渲染 Gutenberg 内容

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

<div id="your_container"> <!-- The element you want to render the content in -->
  {!! $page->lb_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 文档。

• aruszala\Laraberg\Events\ContentCreated
• aruszala\Laraberg\Events\ContentRendered
• aruszala\Laraberg\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' })

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', 'aruszala\Laraberg\Http\Controllers\BlockController');
  Route::get('oembed', 'aruszala\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的对象数组或解析为这种数组的Promise。

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

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

缺失的块

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

• 封面
• 相册
• 媒体和文本

贡献

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