README

基于欧洲组件库（ECL）的Drupal 10主题。

要求
安装
配套子模块
企业块
图像样式
开发
贡献
版本控制

要求

此项目依赖于以下软件

PHP 8.1或8.2

安装

安装OpenEuropa主题的推荐方式是使用Composer。

在继续之前，请注意，主题版本是通过持续集成系统构建的，包括来自第三方库的代码，例如ECL模板和其他资源。简单地运行composer require openeuropa/oe_theme将下载原始主题源代码，这将缺少必要的第三方代码。

为了指示Composer下载实际构建的工件，您需要要求并配置Composer Artifacts项目。要这样做，请运行

composer require openeuropa/composer-artifacts

然后，在您的项目composer.json中添加以下部分

    "extra": {
        "artifacts": {
            "openeuropa/oe_theme": {
                "dist": {
                    "url": "https://github.com/{name}/releases/download/{pretty-version}/{project-name}-{pretty-version}.tar.gz",
                    "type": "tar"
                }
            }
        },
    }

完成后，运行

composer require openeuropa/oe_theme

这将下载完全构建的工件，而不是原始主题源代码。

如果您没有使用Composer，则可以直接从这里下载发布工件（即oe_theme-[x.y.z].tar.gz文件）并按此处所述进行安装。

启用主题

要启用您项目中的主题，请执行以下步骤

启用OpenEuropa主题助手模块 ./vendor/bin/drush en oe_theme_helper
启用OpenEuropa主题并将其设置为默认主题

./vendor/bin/drush theme:enable oe_theme
./vendor/bin/drush config-set system.theme default oe_theme

步骤1是必要的，直到以下Drupal核心问题得到解决。或者，您可以使用此补丁修复Drupal核心，并启用主题：修复后的核心将启用所需的OpenEuropa主题助手模块。

OpenEuropa主题支持EC和EU组件库

对于托管在ec.europa.eu域下的欧洲委员会网站，请使用“欧洲委员会”组件库
对于托管在europa.eu域下的欧洲联盟网站，请使用“欧洲联盟”组件库

默认情况下，主题使用“欧洲委员会”组件库，您可以通过访问主题设置页面来更改它。

注意：开发者：更改组件库只会加载不同的CSS和JS资源，两个库之间的实际HTML相同。

每个组件库都可以使用以下ECL品牌之一

标准化：标准化网站托管特定DG/机构拥有的主题内容。这是托管特定DG内容的默认解决方案（政策），与核心站点紧密相关。
核心：核心网站托管不同网站或部门共享的通用信息，并作为进一步主题内容/特定服务的导航枢纽。例如，欧盟委员会的主要网站（https://ec.europa.eu）使用ECL核心品牌。

要了解更多关于EC/EU家族和ECL品牌的信息，请访问ECL网站。

升级到4.0.0

以下模式已被删除

banner_hero
banner_page
social_media_links_horizontal
social_media_links_vertical

以下按钮模式的变体已被删除

form
form_primary
splash_page

以下模式的language_switcher字段已被删除。以下模式的additional_information字段已被删除。banner模式的text_highlight和image_overlay变体已替换为单个变体text_overlay。

两个ECL组件已被替换

消息组件（twig-component-message）被通知组件（twig-component-notification）替换
语言列表组件（twig-component-language-list）被启动页面（twig-component-splash-page）替换

颜色

为了适应ECL 4.0.0中的颜色变化，我们添加了两个twig函数来根据组件库（欧盟或欧盟委员会）确定正确的边框和背景颜色

ecl_class_border_color
ecl_class_background_color 在印刷字体案例中使用的灰色颜色已被深色替换。

新模式

突出显示列表模式（highlighted_list）- 用于显示一个主要突出显示的项目以及放置在页面右侧的3个次要项目。所有项目都使用list_item模式的结构和default。
选项卡模式（tabs）- 主要用于导航链接。我们使用它来渲染Drupal本地任务。

内容显示更改

所有摘要模板都使用垂直变体来显示列表。

升级到3.0.0

页面标题模式

ECL v3将以下功能添加到页面标题组件中

在页面描述旁边显示缩略图的可能性
添加背景图像的可能性
在背景图像上添加叠加层，以补偿较差的文字对比度

为了适应这些更改，我们已向“页面标题”模式添加以下可选字段

thumbnail:
  type: "ImageValueObject"
  label: "Thumbnail"
  description: "Thumbnail displayed alongside the description."
background_image_url:
  type: "array"
  label: "Background image URL"
  description: "Background image URL, only displayed when the theme ECL branding is set to 'Core'."
overlay:
  type: "text"
  label: "Overlay"
  description: "Optional overlay on top of background image (can be 'light', 'dark'). Only used on EC sites"

我们还删除了以下弃用的字段

identity:
  type: "text"
  label: "Identity (deprecated)"
  description: "The site name. Deprecated from ECL 2.30."
infos:
  type: "array"
  label: "Infos (deprecated)"
  description: "A list of infos of the current page. Deprecated from ECL 2.30."

此外，允许在页面标题中渲染内容语言切换器的自定义已被弃用，转而使用新的ECL组合。相反，需要使用OpenEuropa Multilingual提供的OpenEuropa Content Language Switcher块。建议更新到OpenEuropa主题V3的站点在需要该功能的情况下，将此块放置在页面标题区域。

内容项目组合

我们已从我们的主题中删除以下组合

templates/compositions/ec-component-content-item/content-item-date.html.twig
templates/compositions/ec-component-content-item/content-item.html.twig

请考虑使用列表项模式及其变体。

带特色媒体的文本模式

以下模式的带特色媒体的文本现在支持以下4种变体

左侧简单 / left_simple：左侧的文本，简单的号召性用语。这是默认行为。
右侧简单 / right_simple：右侧的文本，简单的号召性用语。
左侧特色 / left_featured：左侧文本，特色行动呼吁。
右侧特色 / right_featured：右侧文本，特色行动呼吁。

如果没有设置变体，则将使用默认模式进行可视化。这保证了向后兼容性。

网站页眉

ECL v3 支持 Core 和标准化品牌中的水平菜单。为了适应这一点，我们移除了 主导航 块的可见性条件。

visibility:
  oe_theme_helper_current_branding:
    id: oe_theme_helper_current_branding
    branding: standardised
    negate: false
    context_mapping: {  }

升级到2.17.0

下拉 UI 模式

在 2.17.0 版本中，我们放弃了 下拉 模式的支持，该模式将在下一个主要版本中删除。虽然该模式仍然可用，但在模式概述页面上是隐藏的。新的 下拉 模式基于 ECL 可展开组件，应该可以作为旧模式的直接替代。

升级到2.15.0

社交媒体链接模式

在 2.15.0 版本中，我们引入了一个新的模式"社交媒体链接"，具有两种变体

horizontal：社交媒体链接将水平排列。
vertical：社交媒体链接将垂直排列。

因此，“社交媒体链接：水平”和“社交媒体链接：垂直”模式现在已弃用。请使用带有适当变体的“社交媒体链接”模式。

升级到2.10.0

ECL 页面页眉

在 2.10.0 版本中，我们放弃了在"页面页眉"模式中支持以下元素

identity：用于显示网站标识信息（例如网站名称）。
infos：用于显示次要元信息，在页面页眉介绍文本下方。

因此，如果您的 PageHeaderMetadata 插件提供此类数据，它将不再显示。

ECL 品牌

在 2.10.0 版本中，我们引入了对 ECL 品牌的支持（请参阅上述内容以获取更多信息）。OpenEuropa 主题将使用“Core”品牌，如果您需要更改品牌，请访问主题配置页面，并使用“标准化”品牌。

要了解您的网站应该使用哪个品牌，请检查ECL 网站。

升级到2.9.0

内容类型预告

如果您正在使用与 OpenEuropa 主题一起的 oe_content 模块，则更新到 2.9.0 或更高版本将影响您现有的预告显示。2.9.0 版本更新了大多数由 oe_content 提供的内容类型的预告显示，因此如果您想保留对网站所做的任何自定义，您将需要重新执行这些修改并覆盖您自己的自定义主题上的预告模板。

ECL 网站页眉

在 2.9.0 版本中，我们放弃了支持传统的 ECL 网站页眉。为了这样做，我们必须将语言切换器块移动到 site_header_secondary 主题区域。这意味着

如果您的网站没有使用子主题，那么您不用担心，因为我们将通过后更新钩子（如果我们找到它）将其移动到那里
如果您的网站使用子主题，该子主题显示语言切换器块，那么您需要自己将其移动到 site_header_secondary 区域

从1.x升级到2.x

以下模式在 2.x 中已被删除
- dialog
- file_link
在 field 模式中删除了 variant 字段。相反，使用 ui_patterns 变体定义。请参阅 ui_patterns 模式定义文档，了解其工作原理。
OpenEuropa 企业块 1.x 现在不再受支持，您应该使用版本 2.x。

配套子模块

企业块

当与OpenEuropa 企业块组件一起使用主题时，更改组件库将显示不同的页脚块，即

欧洲委员会页脚，附带一组必须存在于所有欧洲委员会网站上的链接和参考。
欧盟页脚，附带一组必须存在于所有欧盟网站上的链接和参考。

图像样式

OpenEuropa 主题附带一系列图像样式，这有助于用户遵循由 ECL 设定的指南。以下是所有可用的样式及其首选用法列表

列表项（oe_theme_list_item）：用于带有小缩略图的内容列表。
特色列表项（oe_theme_list_item_featured）：用于突出显示和带有大缩略图的内容列表。
中等尺寸（oe_theme_medium_no_crop）：中等尺寸图像，是主内容响应式图像样式的一部分。
小尺寸（oe_theme_small_no_crop）：小尺寸图像，是主内容响应式图像样式的一部分。
主内容（oe_theme_main_content）：响应式图像样式，用于任何在内容页内渲染的图像。
全宽（3840）（《oe_theme_full_width》）：全宽图像（3840px x 3840px）。

不同比例的横幅图像样式

全宽横幅 3:1（《oe_theme_full_width_banner_3_1》）
超大横幅 3:1（《oe_theme_extra_large_3_1_banner》）
大横幅 3:1（《oe_theme_large_3_1_banner》）
中横幅 3:1（《oe_theme_medium_3_1_banner》）
小横幅 3:1（《oe_theme_small_3_1_banner》）
全宽横幅 4:1（《oe_theme_full_width_banner_4_1》）
超大横幅 4:1（《oe_theme_extra_large_4_1_banner》）
大横幅 4:1（《oe_theme_large_4_1_banner》）
中横幅 4:1（《oe_theme_medium_4_1_banner》）
小横幅 4:1（《oe_theme_small_4_1_banner》）
全宽横幅 5:1（《oe_theme_full_width_banner_5_1》）
超大横幅 5:1（《oe_theme_extra_large_5_1_banner》）
大横幅 5:1（《oe_theme_large_5_1_banner》）
中横幅 5:1（《oe_theme_medium_5_1_banner》）
小横幅 5:1（《oe_theme_small_5_1_banner》）

开发

OpenEuropa 主题项目包含有效的开发过程所需的全部代码和工具，这意味着

所有 PHP 开发依赖项（包括 Drupal 核心在内）均要求在 composer.json 中
所有 Node.js 开发依赖项均要求在 package.json 中
由于与 Task Runner 项目的集成，项目设置和安装可以轻松处理。
所有系统要求均使用 Docker Composer 容器化。
将自动使用 Drone 测试对代码库的每次更改。

在使用主题之前，请务必阅读开发者文档。

项目设置

开发主题需要 ECL 资产的本地副本，包括 Twig 模板、SASS 和 JavaScript 源文件。

为了获取所需的代码，您需要在本地安装 Node.js (>= 8)。

要安装所需的 Node.js 依赖项，请运行

npm install

要构建最终工件，请运行

npm run build

这将编译所有 SASS 和 JavaScript 文件，并将它们编译成自包含的资产，作为 Drupal 库公开。

为了下载所有所需的 PHP 代码，请运行

composer install

这将构建一个在 ./build 目录下的完全功能性的 Drupal 网站，可用于开发和展示主题。

在设置和安装网站之前，请确保通过将 runner.yml.dist 复制到 ./runner.yml 并覆盖相关属性来自定义默认配置值。

要设置项目，请运行

./vendor/bin/run drupal:site-setup

这将

在 ./build/themes/custom/oe_theme 中创建主题的符号链接，使其对目标网站可用
使用 ./runner.yml.dist 中的值设置 Drush 和 Drupal 的设置
使用 ./runner.yml.dist 中的值设置 PHPUnit 和 Behat 配置文件

请注意：项目文件和目录通过使用 OpenEuropa Task Runner 的 Drupal 项目符号链接命令在测试站点内部进行符号链接。

如果您在项目的根目录中添加了新的文件或目录，您需要重新运行 drupal:site-setup 以确保它们被正确地符号链接。

如果您不想重新运行完整的网站设置，可以简单地运行

$ ./vendor/bin/run drupal:symlink-project

设置成功后，通过运行来安装网站

./vendor/bin/run drupal:site-install

这将

安装目标网站
将 OpenEuropa 主题设置为默认主题
启用 OpenEuropa 主题演示和配置开发模块

使用Docker Compose

或者，您可以使用提供的配置使用 Docker 和 Docker Compose 来构建开发网站。

Docker 提供了必要的服务和工具，如 Web 服务器和数据库服务器，无论您的本地主机配置如何，都可以使网站运行。

要求

配置

默认情况下，Docker Compose 读取两个文件，一个 docker-compose.yml 和一个可选的 docker-compose.override.yml 文件。按照惯例，docker-compose.yml 包含您的基配置，并且默认提供。覆盖文件，如其名称所示，可以包含对现有服务或完全新服务的配置覆盖。如果服务在两个文件中均定义，Docker Compose 将合并配置。

有关 Docker Compose 扩展机制的更多信息，请参阅官方 Docker Compose 文档。

用法

要开始，请运行

docker-compose up

建议不要将 docker-compose 守护，这样您可以在完成工作后快速关闭它（CTRL+C）。但是，如果您想守护它，您必须添加 -d 标志

docker-compose up -d

然后

docker-compose exec -u node node npm install
docker-compose exec -u node node npm run build
docker-compose exec web composer install
docker-compose exec web ./vendor/bin/run drupal:site-install

使用默认配置，开发网站文件应在 build 目录中，开发网站应在： http://127.0.0.1:8080/build。

运行测试

要运行 grumphp 检查

docker-compose exec web ./vendor/bin/grumphp run

要运行 phpunit 测试

docker-compose exec web ./vendor/bin/phpunit

要运行 behat 测试

docker-compose exec web ./vendor/bin/behat

步骤调试

要从命令行启用步骤调试，将任何值传递给容器的 XDEBUG_SESSION 环境变量

docker-compose exec -e XDEBUG_SESSION=1 web <your command>

请注意，从 XDebug 3 开始，如果设置了变量但您的客户端没有监听调试连接，将在控制台输出连接错误消息。错误消息将导致 PHPUnit 测试产生假阴性。

要从浏览器启动步骤调试，请使用浏览器扩展或像在 https://www.jetbrains.com/phpstorm/marklets/ 生成的书签工具设置正确的 cookie。

禁用Drupal 8缓存

手动禁用 Drupal 8 缓存是一个费力的过程，在这里有很好的描述。

或者，您可以使用以下Drupal控制台命令来禁用/启用Drupal 8缓存：

./vendor/bin/drupal site:mode dev  # Disable all caches.
./vendor/bin/drupal site:mode prod # Enable all caches.

注意：要完全禁用Twig缓存，需要以下额外的手动步骤：

打开./build/sites/default/services.yml
设置以下参数：

parameters:
  twig.config:
    debug: true
    auto_reload: true
    cache: false

重建Drupal缓存：./vendor/bin/drush cr

这是由于以下Drupal控制台问题。

与ECL组件一起工作

您可以通过以下方式使用ECL组件，在Twig模板中引用它们，如所示：

{% include '@ecl-twig/logos' with {
  'to': 'https://ec.europa.eu',
  'title': 'European Commission',
} %}

重要：并非所有ECL模板都可用于主题包含，每次需要包含新的ECL模板时，请务必将其添加到ecl-builder.config.js中的copy部分，并运行：

npm run build

更新ECL

要更新ECL组件，请在package.json中更改@ec-europa/ecl-preset-full的版本号，并运行：

npm install && npm run build

这将更新图像和字体等资产，并重新编译CSS。结果更改不应提交到本存储库。

监视和重新编译Sass和JS更改

为了监视Sass和JS文件更改（位于/sass文件夹），以便将它们重新编译到目标文件夹，请运行：

npm run watch

结果更改不应提交到本存储库。

修补ECL组件

可以使用patch-package NPM项目修补ECL组件。

要修补组件：

直接在./node_modules/@ecl/[component-name]中修改其源文件。
运行

npx patch-package @ecl-twig/[component-name]

或者，当使用Docker Compose时

docker-compose exec -u node node git config --global user.email "name@example.com"
docker-compose exec -u node node git config --global user.name "Name"
docker-compose exec -u node node npx patch-package @ecl/[component-name]

补丁将生成在./patches中，并在运行npm install时应用。

使用ECL的开发版本进行工作

要使用ECL的开发版本构建主题，请运行make ecl-dev而不是上述npm install过程，这将

从您在.env.dist中指定的分支检出ECL存储库的工作副本。
使用上述代码库构建ECL。
将Twig模板和CSS/JS资产复制到主题期望的位置。
使用ECL的开发版本编译主题的SASS文件。

如果您想使用开发版本的ECL创建发布版本，请确保在.env.dist中将ECL_BUILD设置为dev。然后，您可以通过在同一个文件中设置ECL_BUILD_REF和ECL_BUILD_REPO来控制ECL将从中构建哪个分支和存储库。

贡献

请阅读完整文档以了解我们的行为准则以及向我们提交拉取请求的流程。

版本控制

我们使用SemVer进行版本控制。有关可用版本，请参阅本存储库的标签。

openeuropa / oe_theme

维护者

详细信息