README

简介

本模块扩展了页面类型，以便用可管理的元素列表替换内容区域，从而构成页面，而不是单个文本字段。支持的功能

元素的版本控制
根据每个元素区域添加、删除支持元素的能力

该模块为每个元素提供基本的标记，但您可能需要提供自己的样式。在您的页面模板中将 $Content 变量替换为 $ElementalArea，并依赖各个元素的标记。

有关使用本模块的更详细概述，请参阅用户帮助指南。

需求

Silverstripe CMS ^4.3
Versioned Admin ^1.0
GridFieldExtensions ^3.1

有关此模块与 Silverstripe CMS 4.1 或 4.2 兼容的版本，请参阅2.x 或 3.x 版本分支。

有关此模块与 Silverstripe CMS 3.x 兼容的版本，请参阅1 分支或 1.x 版本分支。

安装

composer require dnadesign/silverstripe-elemental ^4

以下 YAML 配置将启用每个 Page 对象上的元素，替换标准 Content 富文本字段。

mysite/_config/elements.yml

Page:
  extensions:
    - DNADesign\Elemental\Extensions\ElementalPageExtension

在您的页面类型布局模板中使用 $ElementalArea 将元素渲染到页面上（代替 $Content）。

获取更多元素

请注意，此模块默认包含基本元素和“内容”元素。如果您需要更多元素，请查看其他模块

Silverstripe CMS 支持的内容块模块

有关更多关于 Silverstripe CMS 支持的内容块类型的详细信息，请参阅创建新块。

dnadesign/silverstripe-elemental: 文本内容（内置）
silverstripe/silverstripe-elemental-fileblock: 文件和图片块
silverstripe/silverstripe-elemental-bannerblock: 带有号召性用语和内容的横幅
dnadesign/silverstripe-elemental-userforms: 嵌入用户自定义表单

社区构建的内容块模块示例（非详尽列表 - 可能尚未更新为 Elemental 4）

dnadesign/silverstripe-elemental-list: 元素的容器（允许布局）
dnadesign/silverstripe-elemental-virtual: 在页面间重用元素
dynamic/silverstripe-elemental-blocks: Elemental Blocks 将添加以下元素到您的网站上
- 手风琴：可折叠面板中的内容
- 倒计时：设置日期和时间前的剩余时间
- 客户服务：位置地图、路线和联系方式
- 嵌入式代码：嵌入代码如iframe、javascript
- 特色内容：大图、标题、描述、链接。每行一个
- 文件列表：可下载的文件列表
- Flexslider：Flexslider幻灯片
- 相册：显示一系列图片
- 图片：单个图片
- oEmbed：从YouTube、SoundCloud等嵌入内容
- 促销：小图、标题、描述、链接。每行3到4个
- 近期博客文章：特定博客的最新文章列表
- 章节导航：子页面或当前级别的页面列表
- 赞助商：一行中的赞助商标志
- 选项卡集：创建使用元素的选项卡界面
- 客户评价：客户评价列表，可按类别筛选

实用模块

这些模块可以扩展功能，并使元素与Silverstripe CMS中的其他方法更兼容

dnadesign/silverstripe-elemental-subsites：与silverstripe/subsites模块的兼容性
dnadesign/silverstripe-elemental-skeletons：创建可以用于CMS页面模板的元素模板

配置

限制特定页面类型

如果您想在传统页面类型旁边使用元素，可以定义一个“空”页面类型，并将扩展仅分配给此类型。

mysite/src/MyElementPage.php

<?php
class MyElementPage extends Page
{
}

mysite/_config/elements.yml

MyElementPage:
  extensions:
    - DNADesign\Elemental\Extensions\ElementalPageExtension

迁移现有页面内容

您可以使用提供的MigrateContentToElement BuildTask来帮助将内容从页面迁移到元素。有关使用此任务的更多信息，请参阅内容迁移文档。

自定义HTML和标记

基本元素区域被渲染到DNADesign/Elemental/Models/ElementalArea.ss模板中。此模板遍历每个元素控制器实例。每个控制器实例将渲染$ElementHolder，它表示容器内的元素div。包装div是ElementHolder.ss模板。

要在CMS中自定义ElementEditor，您需要使用Silverstripe CMS JS Injector来对必要的React组件应用转换。有关更多信息，请参阅此处。

限制允许的元素

您可能只想启用某些元素供CMS作者选择，而不是完整集。这可以根据各种页面类型来完成

Page:
  allowed_elements:
    - DNADesign\Elemental\Models\ElementContent

同样，您还可以排除某些元素的使用。

Page:
  disallowed_elements:
    - YourCompany\YourModule\Elements\ElementContact

在页面之间共享元素

默认情况下，页面到元素的关系是“一对一”，这意味着您不能在页面之间共享元素。如果需要此功能，您可以查看silverstripe-elemental-virtual模块，该模块有助于实现此功能。

定义自己的元素

一个元素就像一个扩展DNADesign\Elemental\Models\BaseElement的PHP类，以及相应的模板（除非您想使用默认模板）。添加类后，请确保已重建数据库并重新加载CMS。

<?php

use DNADesign\Elemental\Models\BaseElement;

class MyElement extends BaseElement
{
    private static $singular_name = 'my element';

    private static $plural_name = 'my elements';

    private static $description = 'What my custom element does';

	public function getCMSFields()
    {
        $fields = parent::getCMSFields();

        // ...

        return $fields;
    }

    public function getType()
    {
        return 'My Element';
    }
}

行内编辑

在CMS中，可以使用行内表单编辑元素，其中所有元素都会一起显示。对于更复杂的元素（例如使用自定义的FormField类），您可以通过在您的元素类中设置private static $inline_editable = false来禁用行内编辑表单。对于不能行内编辑的块，将使用GridFieldDetailForm进行编辑。或者，由于CMS元素编辑器现在由React驱动，可以通过定义自己的React组件来添加行内编辑功能。

注意：默认情况下，所有元素都是行内可编辑的。

如果未禁用行内编辑，且未定义自定义组件，则自定义字段将不会渲染，除非字段的schemaDataType被设置。请参阅框架的FormField定义。

在构建自己的React组件并将它们包含到CMS中后，可以通过设置该类的某些protected属性来修改适用于元素的PHP定义，以使用新的React组件。

    protected $schemaDataType = FormField::SCHEMA_DATA_TYPE_CUSTOM;
    protected $schemaComponent = 'BlockLinkField';

$schemaDataType不需要是CUSTOM，但不应是STRUCTURAL，因为结构类型不会被作为表单数据提交。
$schemaComponent是您创建并用于的React组件的名称。

以上示例取自silverstripe/elemental-bannerblock

定义自己的HTML

MyElement将被渲染到MyElement.ss模板中，并使用ElementHolder.ss包装器。可以通过YAML更改包装器模板，或在您的子类中使用$controller_template。

private static $controller_template = 'MyElementHolder';

要自定义现有块模板，如Content和Form模板，请将相关文件从vendor/dnadesign/silverstripe-elemental/templates复制到您的主题中。执行此操作时，请确保匹配文件夹结构（PHP类命名空间），以确保您的新的模板版本具有优先级。

注意：默认元素集遵循[BEM (Block Element Modifier)](http://getbem.com/)命名约定，这允许开发人员在不必要嵌套CSS的情况下对DOM的各个部分进行样式化。尽可能鼓励遵循此命名系统。

位置辅助器

在您的BaseElement模板中，您可以使用以下变量进行附加逻辑或样式辅助。它们的行为与传统SS_Viewer方法相同，返回一个Boolean、String或一个Int

$First（布尔值）
$Last（布尔值）
$Pos（整数）
$TotalItems（整数）
$EvenOdd（字符串 - 'even'或'odd'）

<div class="element element--{$EvenOdd} <% if First %>element--first<% end_if %> <% if Last %>element--last<% end_if %>">
    // ...
</div>

样式变体

通过YAML，您可以配置每个BaseElement子类的样式变体白名单。例如，如果您有内容块的不同dark和light变体，您将在YAML中输入以下内容（格式为'class: 'Description'）。该类将被添加到ElementHolder中。

DNADesign\Elemental\Models\ElementContent:
  styles:
    light: 'Light Background'
    dark: 'Dark Background'

禁用默认样式表

安装此模块时，可能会有一组默认的CSS样式表，用于为前端网站提供各种默认元素类型的示例。

您可以使用YAML配置来禁用此功能。

# File: mysite/_config/elements.yml
DNADesign\Elemental\Controllers\ElementController:
  include_default_styles: false

实现搜索

Elemental模块附带了一个Solr索引器（通过silverstripe-fulltextsearch模块）。您可以在搜索引擎中启用此索引，以确保页面的元素区域内容在页面数据下被索引。

有关配置Solr的信息，请参阅fulltextsearch文档。

注意：在使用此索引器时，请注意在索引之前将从内容中删除HTML标签。Solr搜索结果可能会在匹配的关键词周围添加强调标签或其他格式，因此您可能需要在搜索结果模板中允许未转义的HTML。您应使用$Excerpt属性（有关更多信息，请参阅SolrIndex::search）来显示相关的搜索匹配。

禁用CMS内容搜索

在安装此模块时，页面模型管理搜索将在每个元素页面的整个内容中查找一个词。这是通过渲染每个页面来完成的，这可能很消耗资源并导致搜索超时。

您可以使用YAML配置来禁用此功能。

# File: mysite/_config/elements.yml
DNADesign\Elemental\Controllers\ElementSiteTreeFilterSearch:
  search_for_term_in_content: false

GridField的使用

此模块以前使用GridField在CMS中创建和更新元素。现在这已被React的JavaScript界面所取代。但是，标记为不兼容行内编辑的元素仍然使用GridField方法。

构建elemental前端资源

此模块使用Silverstripe CMS Webpack模块，并继承自核心Silverstripe CMS 4模块，例如核心变量表和JavaScript组件。

当对SASS或JavaScript文件进行更改时，请确保更改client/src/中的源文件。

您可以使用yarn监控并重建您所做的增量更改（仅限开发使用）

yarn watch

当您准备好创建拉取请求时，您可以重建它们，这将也会进行压缩。请注意，watch将生成源映射文件，您不应该将其提交到最终的拉取请求中。要压缩和打包

yarn build

您需要在命令行中全局安装yarn。

注意：如果添加或修改颜色、间距、字体大小等，请尽量使用silverstripe/admin模块中可用的适当变量。

与其他模块的集成

升级

对于从Elemental 3升级到4的开发者，请参阅升级指南。

屏幕截图

版本控制

此库遵循Semver。根据Semver，您将能够升级到此库的任何次要或补丁版本，而无需对公共API进行任何破坏性更改。Semver还要求我们明确定义此库的公共API。

所有具有public可见性的方法都是公共API的一部分。所有其他方法都不是公共API的一部分。在可能的情况下，我们将尝试在次要/补丁版本中保持protected方法的向后兼容性，但如果您正在覆盖方法，请在升级之前测试您的作品。

报告问题

请创建一个问题，以报告您发现的任何错误或缺失的功能。

致谢

Silverstripe Elemental由DNA Design创建。

CMS图标块由Creative Stall从Noun Project提供。

dennisprins / silverstripe-elemental-grid

维护者

详细信息