deepaspl/theme-bundle

为 Symfony4 Bundles 提供主题支持

维护者

详细信息

github.com/deepaspl/LiipThemeBundle

源代码

安装: 50

依赖者: 0

建议者: 0

安全: 0

星标: 0

关注者: 1

分支: 76

类型:symfony-bundle

1.0 2021-01-13 06:21 UTC

Requires

Requires (Dev)

Conflicts

MIT cb9a428d076e19d909ac02e72b80bb25432365fe

themestheming

This package is not auto-updated.

Last update: 2024-10-03 22:47:38 UTC

README

该项目由 LiipThemeBundle 为 twig 3.* 创建

此包为您提供将主题添加到每个包的功能。在您的包目录中，它将位于 Resources/themes/<themename> 或在没有找到匹配文件时回退到正常的 Resources/views。

安装

安装是一个快速（我保证！）的 3 步过程

  1. 下载 LiipThemeBundle
  2. 启用 Bundle
  3. 导入 LiipThemeBundle 路由

步骤 1：使用 composer 安装 LiipThemeBundle

运行以下 composer require 命令

$ php composer.phar require liip/theme-bundle

步骤 2：启用 Bundle

最后，在 kernel 中启用此 Bundle

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new Liip\ThemeBundle\LiipThemeBundle(),
    );
}

步骤 3：导入 LiipThemeBundle 路由文件

现在您已经激活并配置了 Bundle，剩下要做的就是导入 LiipThemeBundle 路由文件。

在 YAML 格式下

# app/config/routing.yml
liip_theme:
    resource: "@LiipThemeBundle/Resources/config/routing.xml"
    prefix: /theme

或者如果您喜欢 XML 格式

<!-- app/config/routing.xml -->
<import resource="@LiipThemeBundle/Resources/config/routing.xml" prefix="/theme" />

配置

您必须设置可能的主题和当前活动的主题。要求活动主题是主题列表的一部分。

# app/config/config.yml
liip_theme:
    themes: ['standardTheme', 'winter_theme', 'weekend']
    active_theme: 'standardTheme'

针对特定设备的主题/模板

您可以提供针对不同设备（如：桌面、平板、手机、纯文本）的特定主题或甚至模板。将 autodetect_theme 选项设置为 true，以根据用户代理设置 current_device 参数。

# app/config/config.yml
liip_theme:
    autodetect_theme: true

然后在 path_patterns 中，您可以使用 %%current_device%% 参数（您的设备类型作为值）

# app/config/config.yml
liip_theme:
    path_patterns:
        app_resource:
            - %%app_path%%/themes/%%current_theme%%/%%current_device%%/%%template%%
            - %%app_path%%/themes/fallback_theme/%%current_device%%/%%template%%
            - %%app_path%%/views/%%current_device%%/%%template%%

可选地，autodetect_theme 也可以设置为实现 Liip\ThemeBundle\Helper\DeviceDetectionInterface 接口的 DIC 服务 ID。

从 cookie 获取活动主题信息

如果您想根据 cookie 选择活动主题，可以添加

# app/config/config.yml
liip_theme:
    cookie:
        name: NameOfTheCookie
        lifetime: 31536000 # 1 year in seconds
        path: /
        domain: ~
        secure: false
        http_only: false

禁用基于控制器的主题切换

如果您的应用程序不允许用户切换主题，您可以禁用与 Bundle 一起提供的控制器

# app/config/config.yml
liip_theme:
    load_controllers: false

主题级联顺序

当检查位于 Bundle 中的模板（例如，@BundleName/Resources/template.html.twig，主题名为 phone）时，以下顺序被应用

  1. 覆盖主题目录：app/Resources/themes/phone/BundleName/template.html.twig
  2. 覆盖视图目录：app/Resources/BundleName/views/template.html.twig
  3. Bundle 主题目录：src/BundleName/Resources/themes/phone/template.html.twig
  4. Bundle 视图目录：src/BundleName/Resources/views/template.html.twig

例如，如果您想集成有关您主题架构的某些 TwigBundle 自定义错误页面，您必须使用此目录结构： app/Resources/themes/phone/TwigBundle/Exception/error404.html.twig

当检查应用程序范围的基础模板（例如，::template.html.twig，主题名为 phone）时，以下顺序被应用

  1. 覆盖主题目录：app/Resources/themes/phone/template.html.twig
  2. 覆盖视图目录：app/Resources/views/template.html.twig

更改主题级联顺序

您可以通过配置指令更改级联顺序：path_patterns.app_resource、path_patterns.bundle_resource、path_patterns.bundle_resource_dir。例如

# app/config/config.yml
liip_theme:
    path_patterns:
        app_resource:
            - %%app_path%%/themes/%%current_theme%%/%%template%%
            - %%app_path%%/themes/fallback_theme/%%template%%
            - %%app_path%%/views/%%template%%
        bundle_resource:
            - %%bundle_path%%/Resources/themes/%%current_theme%%_%%current_device%%/%%template%%
            - %%bundle_path%%/Resources/themes/%%current_theme%%/%%template%%
            - %%bundle_path%%/Resources/themes/fallback_theme/%%template%%
        bundle_resource_dir:
            - %%dir%%/themes/%%current_theme%%/%%bundle_name%%/%%template%%
            - %%dir%%/themes/fallback_theme/%%bundle_name%%/%%template%%
            - %%dir%%/%%bundle_name%%/%%override_path%%
级联顺序模式占位符

更改活动主题

有关此问题，请参阅 ThemeRequestListener。

如果在请求周期早期且尚未渲染模板，您仍然可以无问题地更改主题。为此，主题服务存在于

$activeTheme = $container->get('liip_theme.active_theme');
echo $activeTheme->getName();
$activeTheme->setName("phone");

主题特定控制器

在某些情况下，不同的模板不够，您需要为特定主题使用不同的控制器。我们在A/B测试中遇到了这种情况。不要滥用此功能，并检查您的用例是否仍然被视为主题。

此功能默认不激活，因为涉及到额外的请求监听器。通过在您的配置中设置 theme_specific_controllers 来启用它

# app/config/config.yml
liip_theme:
    # ...
    theme_specific_controllers: true

现在您可以在路由文件中按主题配置控制器

my_route:
    path: /x/y
    defaults:
        _controller: my_service:fooAction
        theme_controllers:
            a: my_other_service:fooAction
            b: App:Other:foo

像往常一样，您可以使用服务符号或命名空间符号来表示控制器。只需在键 theme_controllers 下指定主题控制器即可。

Assetic集成

由于LiipThemeBundle覆盖了模板定位器服务的方式，Assetic只会输出活动主题的资产。

为了输出所有主题的资产，启用 assetic_integration 选项

# app/config/config.yml
liip_theme:
    # ...
    assetic_integration: true

这将覆盖Twig公式加载器，遍历所有主题，确保输出所有资产。

注意，这仅适用于AsseticBundle 2.1或更高版本。

覆盖设备检测

可以覆盖用于设备检测的服务。请确保扩展 DeviceDetection 或实现 DeviceDetectionInterface

# app/config/config.yml
services:
    my_devcice_detection:
        class: SomeClass

liip_theme:
    # ...
    device_detection: my_devcice_detection

迁移到SyliusThemeBundle

这将向您展示如何从 LiipThemeBundle 切换到 SyliusThemeBundle。

删除旧的主题包并安装SyliusThemeBundle

# Remove old theme-bundle
composer remove liip/theme-bundle --no-update

# Install new theme-bundle
composer require sylius/theme-bundle:"^2.0"

删除旧配置

需要删除旧的 liip_theme.yaml 配置

-liip_theme:
-    themes: ['awesome']
-    active_theme: 'awesome'

在下一步中，您将看到如何使用SyliusThemeBundle配置 awesome 主题。

配置SyliusThemeBundle

为了使用该包，您必须添加以下默认配置

# ./config/packages/sylius_theme.yaml

sylius_theme:
    sources:
        filesystem: ~

默认情况下，该包在 %kernel.project_dir%/themes 目录中查找主题，并查找名为 composer.json 的配置文件。这可以通过yaml配置进行更改

sylius_theme:
    sources:
        filesystem:
            filename: theme.json

转换主题配置

在SyliusThemeBundle中，每个主题都必须以 theme.json 的形式拥有自己的配置文件。添加一个 theme.json 文件，并添加以下最小配置

{
    "name": "app/awesome"
}

有关配置选项的详细文档，请参阅 主题配置参考。

您可能需要更改主题名称。重要的是，name 与composer的命名约定（vendor/name）相匹配。此外，theme.json 必须移动到特定主题的目录。

例如：%kernel.project_dir%/themes/awesome/theme.json

更新项目结构

您的模板必须放在与 theme.json 文件相邻的 templates 目录中。

例如：%kernel.project_dir%/themes/<theme-name>/templates

这导致以下项目结构

ProjectName
├── composer.json
├── assets
├── bin
├── config
├── templates
├── themes
│   ├── awesome
│   │   ├── templates
│   │   │   └── base.html.twig
│   │   └── theme.json
│   └── <theme-name-2>
│       ├── templates
│       │   └── base.html.twig
│       └── theme.json
├── ...
└── ...

如您在项目结构中所见，每个主题都必须在其模板目录旁边有自己的 theme.json 配置文件。

创建ThemeRequestListener

您需要创建一个ThemeRequestListener来根据当前 $request 数据设置主题

use Sylius\Bundle\ThemeBundle\Context\SettableThemeContext;
use Sylius\Bundle\ThemeBundle\Repository\ThemeRepositoryInterface;
use Symfony\Component\HttpKernel\Event\GetResponseEvent;
use Symfony\Component\HttpKernel\HttpKernelInterface;

final class ThemeRequestListener
{
    /** @var ThemeRepositoryInterface */
    private $themeRepository;

    /** @var SettableThemeContext */
    private $themeContext;

    public function __construct(ThemeRepositoryInterface $themeRepository, SettableThemeContext $themeContext)
    {
        $this->themeRepository = $themeRepository;
        $this->themeContext = $themeContext;
    }

    public function onKernelRequest(GetResponseEvent $event): void
    {
        if (HttpKernelInterface::MASTER_REQUEST !== $event->getRequestType()) {
            // don't do anything if it's not the master request
            return;
        }

        $themeName = 'app/awesome';

        // here you can set the $themeName based on $event->getRequest() object

        $this->themeContext->setTheme(
            $this->themeRepository->findOneByName($themeName)
        );
    }
}

还可以查看 SyliusThemeBundle 文档。

贡献

积极贡献和补丁非常受欢迎。为了保持项目质量，我们有一大堆单元测试。如果您提交拉取请求，请确保它们仍然通过，如果您添加了功能，请也查看覆盖率，它应该相当高：）

首先安装依赖项

   composer.phar install --dev

这将给出正确的结果

phpunit --coverage-text