contextualcode/ezplatform-custom-attributes

eZ Platform 扩展包，提供在线编辑器中管理自定义属性的界面

维护者

详细信息

gitlab.com/contextualcode/ezplatform-custom-attributes

主页

源代码

问题

安装次数: 42,294

依赖: 0

建议者: 0

安全性: 0

星星: 1

分支: 3

类型:ezplatform-bundle

1.2.4 2019-08-13 14:30 UTC

Requires

Conflicts

GPL-2.0-only b8ec9c8cd03fae9aa86e5c77ab9609eb761e877f

  • Serhey Dolgushev <serhey.woop@contextualcode.com>

ezplatformalloy-editorezplatform-online-editorezplatform-content

This package is auto-updated.

Last update: 2024-09-07 21:33:22 UTC

README

eZ Platform 2.x 版本经历了许多变化 - 许多优秀的改进。但仍然缺少一个关键特性：自定义 CSS 类和自定义属性。这可能会阻止大量 eZ Publish 5.4 网站迁移到最新的 eZ Platform 版本。

因此，我们决定通过提交几个拉取请求来提供帮助。其中之一是

  1. EZP-29301: 在元素上添加了对自定义属性的支持，这扩展了 eZ Platform 架构并允许存储自定义属性。它已在 eZ Platform 2.5.1 中合并。
  2. 处理将 XmlText 转换为 RichText 时的自定义属性，允许在迁移过程中不丢失自定义属性从 eZ Publish 5.4 到 eZ Platform。它将很快合并和发布。

因此，现在可以存储自定义属性，并且很快就可以从 eZ Publish 5.4 迁移它们。但在 eZ Platform 中无法管理它们。eZ Systems 计划在即将到来的 3.x 版本中发布此功能。

在此期间，ezplatform-custom-attributes 解决了这个问题。它提供了一种设置自定义类和属性的方法。它还在在线编辑器中为它们带来了新的 UI。

安装

没有特别之处；你知道怎么做

  1. 使用 composer 需要 contextualcode/ezplatform-custom-attributes
     composer require contextualcode/ezplatform-custom-attributes
  2. 在 app/AppKernel.php 中激活该扩展包
     $bundles = [
    ...
    new ContextualCode\EzPlatformCustomAttributesBundle\EzPlatformCustomAttributesBundle(),
 ];
  3. 清除缓存
     php bin/console cache:clear
  4. 使用 JavaScript 翻译，因此您需要导出它们并运行 encore
     php bin/console bazinga:js-translation:dump web/assets --merge-domains
 yarn encore dev

完成上述步骤后，安装完成。现在您应该能在在线编辑器中看到新的“元素路径”块。您可以在该块中点击任何元素；如果点击的元素被定义为至少可以有一个自定义类或属性，将显示新的 UI 以进行编辑。

下一步是配置自定义类和自定义属性。

配置

自定义类和属性是在 yml 配置文件中的每个 HTML 元素上设置的。以下是一个配置示例

ezrichtext_extension:
    custom_classes:
        p: [p-class-1, p-class-2, p-class-3]
        table: [table-class-1, table-class-2]
        a: [a-class-1, 'icon icon--upload']
    custom_attributes:
        tr:
            hide:
                type: checkbox
        p:
            max-length:
                type: text
                default: 80
        pre:
            language:
                type: select
                options: [javascript, php, java]
    embed_views: [embed, list, block, custom-1, custom-2]

自定义类

对于 custom_classes，您只需指定一个 HTML 元素及其自定义 CSS 类的数组。管理员可以从下拉菜单中选择多个选项。您可以将多个类（通过空格分隔）定义为单个选择选项。

自定义属性

同样，对于 custom_attributes，需要为每个 HTML 元素定义自定义属性设置。以下是一些 选项

  • 可能的type值有： text、textarea、select、checkbox
  • default属性仅适用于text和textarea属性
  • options仅用于select属性，它包含一个可能的选项数组

嵌入视图类型

对于embed_views，您只需指定一个可能的嵌入视图类型数组。

迁移

如果您是从eZ Publish 5.4迁移，并且您的内容包含大量自定义类和属性，则配置所有这些可能非常耗时。为了简化此任务，最好使用ezplatform:generate-custom-attributes-configuration命令。此脚本将根据数据库中存储的内容生成配置。示例用法

php bin/console ezplatform:generate-custom-attributes-configuration --config-file=src/AppBundle/Resources/config/custom_attributes.yml

Extracting Custom Classes from Rich Text fields
===============================================

 2/2 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

Extracting Custom Attributes from Rich Text fields
==================================================

 4/4 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

Extracting Embed Views from Rich Text fields
============================================

 3/3 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

 ! [NOTE] Found 2 elements with custom classes: table, p
 ! [NOTE] Found 3 elements with custom attributes: tr, pre, p
 ! [NOTE] Found 2 elements with embed views: line, embed

 [OK] Configurations are saved into "src/AppBundle/Resources/config/custom_attributes.yml"

完成自定义类/属性和嵌入视图类型的配置后，您应该能够在线编辑器中查看并编辑它们。此时，您可能希望使它们的标签更加适合编辑。这可以通过翻译来实现。

翻译

我们使用JavaScript翻译（custom_attributes翻译域）。因此，所有自定义类和属性的标签都在客户端进行翻译。

要设置自定义标签，请从在您的包中创建一个custom_attributes.<LANGUAGE-CODE>.yaml翻译文件开始。一个好的例子是src/AppBundle/Resources/translations/custom_attributes.en.yaml。

然后您需要在其中添加实际的标签。支持的类型包括

自定义类

  1. 类标签，其翻译消息密钥应遵循options.<css-class-name>.label模式。示例
     options.p-class-1.label: 'Paragraph Class 1'
 options.p-class-2.label: 'Paragraph Class 2'
 options.p-class-3.label: 'Paragraph Class 3'
 options.table-class-1.label: 'Table Class 1'
 options.table-class-2.label: 'Table Class 2'

自定义属性

  1. 属性标题，模式为attributes.<name>.label。示例
     attributes.hide.label: 'Hide'
 attributes.max-length.label: 'Maximal Length'
 attributes.language.label: 'Language'
  2. 选项标签（仅适用于select类型属性），其密钥模式为options.<option>.label。示例
     options.javascript.label: 'JavaScript'
 options.php.label: 'PHP'
 options.java.label: 'Java'

嵌入视图类型

  1. 视图类型标签，模式为embed.view..<view-identifier>。示例
     embed.view.list: 'List'
 embed.view.block: 'Block'
 embed.view.custom-1: 'Custom 1'
 embed.view.custom-2: 'Custom 2'

更新翻译

请注意，每次更改自定义属性翻译后，您都需要导出它们并运行encore

php bin/console bazinga:js-translation:dump web/assets --merge-domains
yarn encore dev

因此，剩下的部分将是处理前端上的自定义类和属性。

渲染

自定义类

前端上自定义类的渲染没有特别之处。它们被设置为相应HTML元素的class属性。

自定义属性

默认情况下，自定义属性以具有ezattribute-前缀的data属性进行渲染。因此，如果某个元素的max-length设置为10，则在前端上，它将渲染为具有data-ezattribute-max-length="10"属性的属性。这在大多数情况下都适用，但有一些方法可以自定义它。

XSL样式表

实现自定义属性高级渲染的一种可能方法是使用自定义XSL样式表。此选项是性能最好的选项，但需要一些广泛的XSL知识。此外，您还需要熟悉eZ Platform Rich Text架构。在这种情况下，Rich Text内容在从存储在数据库中的格式转换为HTML5的过程中进行修改。

示例实现

  1. 定义自定义XSL样式表
     <?xml version="1.0" encoding="UTF-8"?>
 <xsl:stylesheet
         xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
         xmlns:docbook="http://docbook.org/ns/docbook"
         exclude-result-prefixes="docbook"
         version="1.0">
   <xsl:output indent="yes" encoding="UTF-8"/>
   <xsl:template match="docbook:tr[docbook:ezattribute[docbook:ezvalue[@key='hide' and text()='true']]]"/>
 </xsl:stylesheet>
  2. 通过ezpublish.system.default.fieldtypes.ezrichtext.output_custom_tags配置参数通知eZ Platform有关自定义XSL样式表。

富文本转换器

或者，您可以使用富文本转换器来实现自定义属性的高级渲染。在这种情况下，富文本内容在PHP中进行操作，这使得开发和调试更加容易。基本操作是定义一个新的服务，使用ezpublish.ezrichtext.converter.output.xhtml5标签，该标签实现了EzSystems\EzPlatformRichText\eZ\RichText\Converter接口。就这样！

示例实现

  1. 创建一个新的富文本转换器
  2. 定义它为一个服务，使用ezpublish.ezrichtext.converter.output.xhtml5标签

嵌入视图类型

在设置自定义嵌入视图类型后，将其设置添加到ezsettings.default.content_view_defaults哈希表中。就这样。

示例

您可以从ezplatform-custom-attributes获取eZ Platform的工作示例，地址是https://gitlab.com/contextualcode/ezplatform-custom-attributes-example。请查看那里的AppBundle，它包含所有可能的配置和自定义示例，包括自定义类和属性。

重点

现在没有理由不开始使用ezplatform-custom-attributes，然后使用即将在eZ Platform 3中发布的官方自定义属性功能。

  • 首先，我们想强调的是，ezplatform-custom-attributes不会修改富文本模式。这意味着在您升级eZ Platform 3期间，不需要对您的数据进行任何更改。也不需要运行任何迁移脚本。

  • 自定义类和属性的渲染是通过使用内置的eZ Platform功能完成的。所以，如果您现在实施它，它应该会在eZ Platform 3中保持相同。

  • 在eZ Platform 3中将发生变化的唯一部分是管理UI。到那时，您可以简单地禁用此捆绑包，并将选择新的UI。

  • 在eZ Platform 3迁移过程中可能需要更改的唯一部分是自定义类和属性的配置。这将取决于eZ Platform 3中自定义类和属性配置的格式。

所以请尝试ezplatform-custom-attributes。我们非常希望听到您的反馈。PR和评论非常受欢迎！