README

基于 Europa 组件库 (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 核心问题被解决。或者，您可以应用此补丁并启用主题：修补后的核心将启用所需的 OpenEuropa 主题助手模块：[链接至补丁文件]

OpenEuropa 主题支持 EC 和 EU 组件库

对于在 ec.europa.eu 域名下托管的欧洲委员会网站，使用 "European Commission" 组件库
对于在 europa.eu 域名下托管的欧洲联盟网站，使用 "European Union" 组件库

默认情况下，主题使用 "European Commission" 组件库，您可以通过访问主题设置页面来更改它。

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

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

标准化：标准化的网站托管特定局/机构拥有的主题内容。这是托管特定局（政策）内容的默认解决方案，与核心网站紧密一致。
核心：核心网站托管不同网站或部门共享的通用信息，并作为导航到更多主题内容/特定服务的枢纽。例如，欧盟委员会的主网站（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

page_header模式的language_switcher字段已被删除。 list_item模式的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内容语言切换器块。建议升级到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主题将使用“核心”品牌，如果您需要更改这一点，请访问主题配置页面并使用“标准化”品牌。

要检查您的网站应使用哪个品牌，请查看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 Console 命令来禁用/启用 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 Console 问题。

与 ECL 组件协同工作

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

{% 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）进行版本管理。有关可用的版本，请参阅此存储库中的标签。

ec-europa / oe_theme

维护者

详细信息