README

基于国际劳工组织(ILO)设计系统的Drupal 10主题。项目结构如下

一个非常基础的基主题，目前内容不多。这将在未来发生变化，因为默认的Drupal模板（例如标签页、表单等）将越来越多地符合ILO设计系统。
一个主题伴侣模块 ilo_base_theme_companion，它将所有兼容的ILO设计系统组件作为Drupal模式公开。有关更多信息，请参阅UI Patterns和UI Patterns Settings模块。

主题需要启用伴侣模块，而可以启用伴侣模块而不启用基主题。

安装

推荐通过Composer安装ILO Base Theme。

在继续之前，请注意，主题版本是通过持续集成系统构建的，包括来自第三方库的代码，例如ILO Design System模板和其他资产。简单地运行composer require international-labour-organization/ilo_base_theme将下载原始主题源代码，缺少所需的第三方代码。

为了指示Composer下载实际构建的工件，您需要需要并配置Composer Artifacts项目。

要这样做，请运行

composer require openeuropa/composer-artifacts

然后在你项目的composer.json文件中添加以下部分

    "extra": {
        "artifacts": {
            "international-labour-organization/ilo_base_theme": {
                "dist": {
                    "url": "https://github.com/{name}/releases/download/{pretty-version}/{project-name}-{pretty-version}.zip",
                    "type": "zip"
                }
            }
        },
    }

完成后，运行

composer require international-labour-organization/ilo_base_theme

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

使用基础主题

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

启用ILO base theme companion模块
启用ILO base theme并将其设置为默认值

./vendor/bin/drush en ilo_base_theme_companion
./vendor/bin/drush theme:enable ilo_base_theme
./vendor/bin/drush config-set system.theme default ilo_base_theme

在不使用基础主题的情况下使用组件

如果您已经有了主题，只想使用设计系统组件，只需启用伴侣模块，无需启用主题，如下所示

./vendor/bin/drush en ilo_base_theme_companion

组件的完整列表可在/patterns中找到。

模式和缓存元数据

使用模式显示渲染数组需要仔细处理渲染数组的缓存元数据。例如，如果您想使用card模式渲染新闻内容类型的摘要，您通常会做以下操作

{{ pattern('card', {
  title: content.title,
  link: content.field_link['#url'],
  size: 'fluid',
}, 'feature') }}

上述方法的问题是缓存标签和上下文（例如来自field_link的链接）没有正确传递。

为了解决这个问题，建议明确传递渲染数组的缓存元数据。您可以通过使用Twig Tweak模块提供的|cache_metadata过滤器来实现，如下所示

{{ pattern('card', {
  title: content.title,
  link: content.field_link['#url'],
  size: 'fluid',
}, 'feature') }}

{{ content|cache_metadata }}

在处理图案时，另一个需要记住的推荐模块是Twig Field Value，它可以帮助在传递到图案时访问渲染数组和实体的属性和子字段。

本地运行演示网站

此项目还附带一个可构建的演示站点，允许开发者轻松预览基础主题。要这样做，请运行

make

这将构建一个默认启用ILO Base Theme的完全功能的Drupal站点。安装完成后，请访问

http://localhost:8080

注意：上面的命令构建了一个作为独立服务的演示站点。为此，它将在容器中执行以下命令

运行 npm install 以获取ILO设计系统资源
将所有相关的Drupal相关代码复制到/opt/drupal
构建并安装Drupal站点

这意味着，在获取新版本时，您可能需要从头开始重新构建演示站点。要这样做，请运行

make build-dist

以Docker服务运行演示网站

演示站点也发布在GitHub Docker注册表中。要运行站点，请使用以下命令

docker run -p 8082:80 ghcr.io/international-labour-organization/ilo_base_theme:0.x

然后，站点将在http://localhost:8082上可用。

为了运行上述命令，您需要经过认证，请查看相关的文档。

按需渲染图案

ilo_base_theme_preview 模块公开了一个 /pattern-preview?id=...&variant=...&fields=... 路由，允许用户通过传递其ID、其变体（可选）及其字段作为编码的JSON对象来按需渲染图案。

例如，要渲染一个按钮，可以传递以下字段作为JSON

{
  "label": "Button",
  "type": "primary",
  "kind": "button",
  "size": "medium"
}

编码后，将看起来像以下内容

http://localhost:8081/pattern-preview?id=button&fields=%7b%0a%22label%22%3a%20%22Button%22%2c%0a%22type%22%3a%20%22primary%22%2c%0a%22kind%22%3a%20%22button%22%2c%0a%22size%22%3a%20%22medium%22%0a%7d

图案设置需要在fields对象中传递。例如，要渲染tooltip图案，可以使用以下设置

{
  "label": "test",
  "settings": {
    "icon": true,
    "icontheme": "light",
    "theme": "dark"
  }
}

请注意，任何HTML都需要设置为Drupal的#markup。例如，要渲染richtext图案，可以将以下JSON传递给fields参数

{
  "content": {
    "#markup": "<b>this is bold</b>, this is not"
  }
}

上述测试模块在dev和dist Docker镜像中都默认启用，但并未包含在发布的包中。

开发

项目包含所有必要的代码和工具，以实现有效的开发过程，这意味着

所有PHP开发依赖项（包括Drupal核心）都在composer.json中要求
所有Node.js开发依赖项都在package.json中要求
多亏了与Task Runner项目的集成，项目设置和安装可以轻松处理。
所有系统要求都使用Docker Compose进行容器化。

可以通过Makefile的目标来设置开发环境，如下所示

通过运行make up-dev install启动开发环境。这将
- 从提供的Dockerfile的dev目标构建开发Drupal容器
- 在项目中构建Drupal目标站点
- 在目标站点内创建基础主题代码库的符号链接
- 在开发容器内挂载目标站点
- 安装目标站点
- 通过在节点容器中运行npm install来安装NodeJS依赖。
- 安装设计系统
- 将站点暴露在http://localhost:8081

在处理主题时，您可能需要通过运行以下命令来启用Drupal Twig调试：

make twig-debug-on

international-labour-organization / ilo_base_theme

维护者

详情