README

编辑器模块（editor）提供管理和使用编辑器的API，并附带多个编辑器。

不同的编辑器用于输入CMS Icybee 的内容。无论是文章的主体或摘要，文件的描述，页面的内容……从最简单的字符串到模式的不同元素，或者某些具有丰富文本的元素。这些编辑器允许用户输入各种类型的内容。它们还用于选择图像、记录、表单、作为页面主体的视图，以及许多其他事物。

模块提供的以下编辑器

• rte - 一个富文本编辑器。
• textmark - 用于TextMark/Markdown语法的编辑器。
• image - 管理图像的选择器。
• node - 节点的选择器。
• patron - Patron模板引擎的编辑器。
• php - PHP代码的编辑器。
• raw - 允许您使用HTML代码。
• tabbable - 具有选项卡内容的编辑器，其中每个选项卡都可以使用自己的编辑器。
• widgets - 允许您选择和排序小部件的编辑器。

编辑器

模块提供的API定义了所有编辑器的公共接口。它们必须能够序列化和反序列化它们所支持的内容类型。它们还必须提供用于编辑该内容的UI元素。例如，这是提供text编辑器的TextEditor类

<?php

namespace ICanBoogie\Modules\Editor;

class TextEditor implements Editor
{
	public function serialize($content)
	{
		return $content;
	}

	public function unserialize($serialized_content)
	{
		return $serialized_content;
	}

	public function render($content)
	{
		return $content;
	}

	public function from(array $attributes)
	{
		return new TextEditorElement($attributes);
	}
}

由于此编辑器支持的内容类型非常基本，因此序列化和渲染方法非常简单。支持更复杂内容类型的编辑器可能使用数组并使用JSON序列化其内容。

序列化和反序列化

使用serialize()方法将编辑器支持的内容类型的内部表示转换为可以轻松存储在数据库中的普通字符串

<?php

namespace ICanBoogie\Modules\Editor;

$content = "Madonna!";
$editor = new TextEditor;
$serialized_content = $editor->serialize($content);

// the serialized content can be stored in the database 

编辑器仅与反序列化内容一起工作。如果内容要渲染或用作UI元素的值，则需要对其进行反序列化

<?php

namespace ICanBoogie\Modules\Editor;

// $serialized_content is coming from the database

$editor = new TextEditor;
$content = $editor->unserialize($serialized_content);
$rendered_content = $editor->render($content);

渲染内容

使用render()方法渲染内容，该方法返回一个字符串，或可以用作字符串的对象。例如，image编辑器的render()方法接受图像的标识符，并在用作字符串时将其渲染为IMG元素。

因此，如果编辑器被要求渲染内容，则返回一个活动记录。用作字符串时，活动记录被渲染为HTML字符串。但它也可以用来获取缩略图

<?php

namespace ICanBoogie\Modules\Editor;

$editor = new ImageEditor;
$image = $editor->render('12');

if ($image)
{
    echo $image->thumbnail('article-view');
}

GUI元素

每个编辑器都提供了一个用于编辑所支持内容类型的GUI元素。该元素是通过使用from()方法创建的。例如，TextEditor创建TextEditorElement的实例

<?php

namespace ICanBoogie\Modules\Editor;

class TextEditor implements Editor
{
    // …

    public function from(array $attributes)
    {
        return new TextEditorElement($attributes);
    }
}

<?php

namespace ICanBoogie\Modules\Editor;

class TextEditorElement extends \Brickrouge\Text implements EditorElement
{
    public function __construct(array $attributes = [])
    {
        parent::__construct($attributes + [
        
            'class' => 'editor editor--raw'
            
        ]);
    }
}

UI元素必须是Element类的实例或其子类之一。例如，TextEditorElement扩展了Text，而Text扩展了Element。可以使用Element类的许多属性来获得满意的结果

<?php

use Brickrouge\Element;
use Brickrouge\Group;

$editor = new TextEditor;
$element = $editor->from([

    Group::LABEL => 'Title',
    Element::REQUIRED => true,
    
    'name' => 'title',
    'value' => $editor->unserialize($serialized_content)
    
]);

请注意，内容是通过value属性指定给GUI元素的。

编辑器集合

编辑器集合包含了可用编辑器的定义。它用于实例化编辑器，以及它们的GUI元素。

<?php

namespace Icybee\Modules\Editor;

use Brickrouge\Group;
use Brickrouge\Element;

$editors = new Collection([
	
	'rte' => RTEEditor::class,
	'textmark' => TextmarkEditor::class,
	'raw' => RawEditor::class,

]);

$editor = $editors['rte'];

$editor_element = $editors['rte']->from([

	Group::LABEL => "Body",
	Element::REQUIRED => true

]);

编辑器定义可以在被用于实例化编辑器之前进行修改。如果尝试修改已用于实例化编辑器的定义，则会抛出EditorAlreadyInstantiated异常。如果尝试获取定义未定义的编辑器，则会抛出EditorNotDefined异常。

核心集合

尽管可以创建自定义集合来管理编辑器，但建议使用通过懒加载获取器附加到核心对象的核心集合。

<?php

$app->editors;

$editor = $app->editors['rte'];

$editor_element = $app->editors['rte']->from([
	Group::LABEL => "Body",
	Element::REQUIRED => true
]);

此集合从editors配置创建，可以通过附加到Icybee\Modules\Editor\Collection::alter事件来更改。

定义核心集合的编辑器

使用editors配置来定义核心集合的编辑器。建议这样定义编辑器，除非您不希望编辑器对整个CMS可用。

<?php

namespace Icybee\Modules\Editor;

return [

	'rte' => RTEEditor::class,
	'textmark' => TextmarkEditor::class,
	'raw' => RawEditor::class,
	'text' => TextEditor::class,
	'patron' => PatronEditor::class,
	'php' => PHPEditor::class,
	'image' => ImageEditor::class,
	'node' => NodeEditor::class,
	'widgets' => WidgetsEditor::class,
	'tabbable' => TabbableEditor::class

];

修改核心集合

第三方可以使用Icybee\Modules\Editor\Collection::alter事件（由Icybee\Modules\Editor\Collection\AlterEvent类提供）来修改已使用editors配置创建的核心集合。

<?php

use Icybee\Modules\Editor\Collection;

$app->events->attach(function(Collection\AlterEvent $event, Collection $target) {

	$target['rte'] = 'MyRTEEditor';

});

多编辑器

拥有这么多编辑器来使用是非常好的，如果用户更愿意使用Markdown编辑器或纯HTML编辑器，而不是RTE编辑器，那么只提供一个RTE编辑器将会很遗憾。为了应对这种情况，模块提供了一个多编辑器，一个可以切换编辑器来编辑内容的壳。

内容模块使用此编辑器，以便用户可以选择用于编辑和渲染其内容的编辑器。

<?php

namespace Icybee\Modules\Contents;

// …

use Icybee\Modules\Editor\MultiEditorElement;

class EditBlock extends \Icybee\Modules\Nodes\EditBlock
{
	protected function get_children()
	{
		// …
		
		Content::BODY => new MultiEditorElement($values['editor'] ? $values['editor'] : $default_editor, [
			
			Element::LABEL_MISSING => 'Contents',
			Element::GROUP => 'contents',
			Element::REQUIRED => true,

			'rows' => 16
			
		])
		
		// …
	}
}

tabbable编辑器为每个标签页使用此编辑器，允许用户在第一个标签页中使用RTE编辑器，第二个标签页中使用Markdown编辑器，第三个标签页中使用tabbable编辑器（即《盗梦空间》中的“ inception”）。

目前，使用多编辑器需要一个额外的字段来存储用户配置的编辑器。其名称可以使用SELECTOR_NAME属性指定，默认为editor。

要求

该软件包要求PHP 5.5或更高版本。

安装

推荐通过Composer安装此软件包。创建一个composer.json文件，并运行php composer.phar install命令来安装它。

$ composer require icybee/module-editor

注意：此模块是Icybee所需模块的一部分。

克隆仓库

该软件包可在GitHub上找到，其仓库可以使用以下命令行进行克隆：

$ git clone git://github.com/Icybee/module-editor.git editor

测试

测试套件使用make test命令运行。Composer会自动安装以及运行套件所需的所有依赖。可以使用make clean命令清理软件包目录。

该软件包由Travis CI持续测试。

文档

该软件包作为 Icybee CMS 的文档的一部分进行说明。软件包及其依赖项的文档可以通过执行 make doc 命令生成。文档使用 ApiGen 在 docs 目录下生成。之后，可以使用 make clean 命令清理软件包目录。

许可证

该模块遵循新BSD许可证 - 详细信息请参阅LICENSE文件。