README

一个基于LivingDocs引擎构建的前端网站内容编辑工具。

借鉴了https://github.com/wolfv/silverstripe-livingdocsfield 和 https://github.com/guru-digital/frontend-admin 的部分工作。

概述

此模块允许您从网站前端编辑结构化HTML组件。这些组件可以通过可编辑区域定义，允许使用以下方式插入内容“指令”：

WYSIWYG html编辑
原始html编辑
图像选择
嵌入式项目（使用简码）
容器 - 其他组件的列表

组件可以在页面上移动并嵌套在其他组件内部，这意味着内容作者可以在原地定义完整的页面结构，而无需复杂的CMS管理对象结构。

入门指南

模块包含一个LivingPage页面类型，可以在CMS中创建。创建后，单击在原地编辑此页面链接，即可开始修改网站前端上的页面。

要启用全局简码配置，该配置可以添加到所有页面，请添加以下配置（根据您是否使用多站点而定）

---
Name: componentpage_config
---
SilverStripe\SiteConfig\SiteConfig:
  extensions:
    - Symbiote\Frontend\LivingPage\Extension\LivingPageSettingsExtension

页面模板

默认情况下，组件页面将在您网站的全局页面布局中渲染。要完全控制整个页面的渲染，定义一个顶级的templates/ComponentPage.ss文件，该文件从body标签中删除除$Layout关键字之外的所有内容。

为了使用户可以进一步配置，将ComponentPage.allow_full_page_mode: true配置属性设置为允许编辑器选择以控制整个页面布局，然后将您的ComponentPage.ss模板更改以检查是否设置了$FullPageMode变量，以确定是否仅输出$Layout关键字。

Symbiote\Frontend\LivingPage\Page\ComponentPage:
  allow_full_page_mode: true

<% if $FullPageMode %>
$Layout
<% else %>
<header>
    <nav><etc></nav>
</header>
<div class="container">
$Layout
</div>
<div class="Footer">

</div>
<% end_if %>

注意：为了正确使用可重复使用的组件，您可能需要定义一些简码以输出网站的重复部分（请参阅ShortcodeMenu示例），并通过CMS将它们包装在PageComponent对象中，或者使用User Templates模块并直接在CMS中定义这些模板。下面将详细介绍组件。

CMS功能

从CMS中，您可以定义一些内容以帮助页面编辑过程

嵌入页面内容的简码

这些可以在SiteConfig上配置，对于多站点用户，则是在Site对象上配置，这将贯穿整个网站。可以在每个页面上指定额外的简码；这些将覆盖全局级别上定义的任何简码。指定键值对，其中“键”是显示给用户的标签，“值”是要输出的简码。请注意，用户可能需要从网站前端添加简码的属性。

livingpage_childlist - 显示页面的子项列表（使用“当前”页面作为默认值）
livingpage_show_field - 显示对象的字段（默认为当前页面）。支持子字段和参数的解析
- `[livingpage_show_field field="OriginalPublishDate.format" args="Y/m/d"]

向系统中添加新简码是正常的SilverStripe方法，例如

ShortcodeParser::get('default')->register('listing', array('PageShortcodes', 'listing_content'));

在网站的前端，使用“嵌入”组件添加简码。

组件页面结构

为了给页面提供一些结构，您可以在CMS中在admin/componentpage定义“组件页面结构”。当创建此结构时，您可以选择一个现有的组件页面来从中提取内容结构。

然后，当您在站点树中创建组件页面对象时，您可以选择模板结构来提供初始内容。

页面组件和复合组件

在CMS中创建新组件比在设计文件中要直接一些。从组件页面部分创建一个新的页面组件

标题是用户在工具栏中看到的内容
名称将自动生成
“分组”是它在工具栏中的显示位置
标记是HTML，带有额外的指令（见下文）以突出显示可编辑区域

在许多情况下，可能更简单的是从页面上定义的现有结构创建可重用的组件。为此，创建一个新的复合组件。初始字段与页面组件的含义相同；然而，标记应从一组组件中复制。转到组件页面，选择某种容器，然后按ctrl+c。（您将在右下角看到一个小的通知）。将此粘贴到标记区域。

复合组件

图片粘贴

您可以在几个不同的上下文中粘贴剪贴板图片；

当在WYSIWYG段落中编辑时，新图像作为同级组件插入
当选中现有图像时，它将替换该图像
当选中容器时，新图像将插入该容器的末尾

自定义设计

该模块包含一个基本的“设计”，它是一组定义在JavaScript中的组件，这些组件定义了组件的HTML结构，以及哪些组件部分是可编辑的。

组件由纯HTML组成，包含几个特定的指令属性，这些属性指示livingdocs结构的可编辑区域。除了HTML结构外，组件还可以应用componentProperties，这些属性作为CSS类公开，以及任意的data字段。一个特定的data字段是data_attributes映射，它作为属性应用于元素。

一个示例组件

    {
        "name": "image",
        "html": "<figure>\n\
            <img doc-image=\"image\" class=\"img-responsive\">\n\
            <figcaption doc-editable=\"caption\">\n\
            Caption.\n\
            </figcaption>\n</figure>",
        "label": "Image"
    }

关键点是

顶级元素（<figure>）是任何CSS类将应用于的元素
使用了两个指令；doc-image和doc-editable
组件的html可以使用嵌套元素和指令

创建新设计

假设默认的base bootstrap-design.js文件被使用，您可以通过迭代设计对象来简单地更新这些定义；

$(document).on('updateLivingdocsDesign', function (e, design) { });

然后可以迭代design.components集合来更改现有定义，或将新定义推送到其列表中。

要指定自己的自定义设计，您可能希望从bootstrap设计开始进行更新，然后通过以下方式将其绑定到配置中

---
Name: custom_designs
---
Symbiote\Frontend\LivingPage\Extension\LivingPageExtension:
  living_designs:
    my_theme_name: 'path/to/my/design.js'

指令

页面编辑器支持几种指令类型

doc-editable：一个提供原地编辑内容、简单格式选项和内容插入（链接）插件的WYSIWYG编辑器。
doc-image：原地图像插入
doc-container：允许定义可以插入多个子组件的区域。例如，一个split-panel组件可能有两个'div'元素，每个元素都有自己的子元素，这将在每个元素中通过具有单独的容器来标记。<div class="col-md-6" doc-container="left-column"></div><div class="col-md-6" doc-container="right-column"></div>
doc-html：使用ACE编辑器的原始HTML编辑。存在一个特殊的Markdown组件，它允许使用Markdown进行更简单的内容输入。
doc-embeditem：这是一个仅适用于SilverStripe的指令，允许嵌入来自代码定义的短代码的内容。这些必须作为一个正常的基于SilverStripe PHP的短代码创建，并配置为可在页面上使用。

组件组

为了简化界面，组件可以共同放在一个公共标题下。请参阅设计文件中的groups键。

预定义的组件结构

在某些情况下，希望在创建特定类型的组件时自动创建特定的组件树。一个例子是table组件；几乎总是会在创建一个<table>时创建标题和行。

有两种机制可以定义这些，它们都使用相同的内部结构。

prefilledComponents：当创建特定类型的组件时，会自动创建子类型结构。例如，table会自动拥有tablehead和tablebody子容器，并填充内容。
structures：在UI中创建一个新的下拉菜单，允许选择命名的自定义结构。例如，在bootstrap设计中，一个Content section结构是一个填充了row组件的section组件，该row组件又填充了column组件，最后填充了p组件。

构建新包

cd vendor/nyeholt/silverstripe-frontend-livingdoc/app
yarn install
yarn watch

限制

当前实现的设计中的组件基于Bootstrap 4，所有可用组件都基于我当时需要的特定实现。

您可以通过hook到updateLivingdocsDesign JS事件并在它被加载之前更改事物。

关键API部分

获取当前选定的组件

LivingDocState.activeComponent

未来工作

更好地迁移更改的组件结构

nyeholt / silverstripe-frontend-livingdoc

维护者

详细信息