README

Craft CMS Twig 基础模板，为任何基于 Craft CMS 的 Web 项目提供灵活的无缝布局模板。

它们提供了一个基础布局，其中包含内置的块来结构化 <head> 和 <body> HTML 标签的各个部分。

它们还自动处理同一页面的常规 Web 请求和 AJAX 请求，对于 AJAX 请求只返回内容，不包含 UX chrome。

这些模板通过 Twig Bundle Installer 自动安装，因此可以像任何 Composer 依赖项一样轻松更新。

要求

这些模板兼容 Craft CMS 3 或更高版本（完全兼容 Craft CMS 4 & 5）。

安装

要安装 Craft Twig Base Templates，请按照以下步骤操作

按照 Twig Bundle Installer Composer 插件安装说明将其安装到您的项目中
打开您的终端并转到您的 Craft 项目
```
 cd /path/to/project
```

然后告诉 Composer 需要 Craft Twig Base Templates 包

 composer require nystudio107/craft-twig-base-templates

然后，模板将被安装到您的 Twig templates/ 目录中 git 忽略的 vendor/ 目录中。

使用方法

布局有意保持简单，提供任何 Craft CMS 站点都可以构建的合理结构。提供的大部分价值是结构化和组织性的，以牺牲开箱即用的功能为代价。

您可以直接使用 html-page.twig，或者您可以用自己的布局模板来扩展它，该模板添加了您希望所有页面都可用到的功能。

扩展 `html-page.twig` 基础布局

在您的布局或页面模板中，按如下方式扩展 html-page.twig

{% extends "vendor/nystudio107/craft-twig-base-templates/templates/_layouts/html-page.twig" %}

基础布局块

布局定义了以下块，您可以根据需要覆盖它们

┌─────────────────────────────────────────────────────────────────────────────┐
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │                                headMeta                                 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │                                headLinks                                │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │                               headScripts                               │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │                               headStyles                                │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│                                 headContent                                 │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │                             preContent                              │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │                               content                               │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │                            postContent                              │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ │                                bodyHtml                                 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │                               bodyScripts                               │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│                                 bodyContent                                 │
└─────────────────────────────────────────────────────────────────────────────┘

以下是块的分解以及每个块的预期用途

headContent - 包裹 <head> 标签内所有内容的块
- headMeta - 用于 <meta> 标签，如 <meta charset="UTF-8">
- headLinks - 用于 <link> 标签，如 <link rel="stylesheet" href="style.css" />
- headScripts - 用于应出现在 <head> 标签内的 <script> 标签，如 <script type="module" src="app.js"></script>
- headStyles - 用于任何内联（关键）CSS <style></style> 标签
bodyContent - 包裹 <body> 标签内所有内容的块
- bodyHtml - 包裹出现在 <body> 标签内的 HTML 内容的块
  - preContent - 出现在主要 content 块之前（如导航栏或网站页眉）的 HTML 内容
  - content - 页面的主要 HTML 内容。这是 AJAX 请求渲染的唯一块
  - postContent - 出现在主要 content 块之后（如链接或网站页脚）的 HTML 内容
- bodyScripts - 用于应出现在 </body> 标签之前的 <script> 标签，如 <script tyoe="module" src="app.js"></script>

一般来说，只覆盖你需要的最具体的块。例如，要在扩展了 html-page 布局的模板中添加内容，只需覆盖 content 块

{% block content %}
    <h1>Some title</h1>
    <p>Some content</p>
{% endblock content %}

...而不是覆盖 bodyHtml 块。

然而，如果你需要提供包围 content 块的 HTML，你也可以这样做

{% block bodyHtml %}
    <div class="contaniner">
    {% block preContent %}
        <p>Site header</p>
    {% endblock preContent %}
    {% block content %}
        <h1>Content title</h1>
        <p>Some content</p>
    {% endblock content %}
    {% block postContent %}
        <p>Site footer</p>
    {% endblock postContent %}
    </div>
{% endblock bodyHtml %}

渲染父块内容

你会注意到，即使在这些非常基础的基布局模板中，一些块中也有内容，例如 headMeta 块

    {# -- Any <meta> tags that should be included in the <head> -- #}
    {% block headMeta %}
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width,minimum-scale=1">
    {% endblock headMeta %}

这是为了方便你，因为几乎每个网站都会希望在这些标签上。

如果你在自己的布局或页面模板中覆盖了一个块，你的内容将显示为父块的内容。

然而，你可以使用 {{ parent() }} 来渲染父块的内容，同时也可以添加你自己的内容

{% block headMeta %}
    {{ parent() }}
    <meta http-equiv="refresh" content="30">
{% endblock headMeta %}

上面的代码将渲染 html-page.twig 的 headMeta 块的内容，然后也会输出你的内容。

特殊的 AJAX `content` 块

content 块被特别处理，当传入的请求是网页请求时，它会像上面指定的各种块一样，正常渲染页面。

当传入的请求是 AJAX 请求时，则只渲染和返回 content 块。

这允许你轻松创建全网页内容（非常适合 SEO 和索引），同时也可以通过 JavaScript 和 AJAX 请求在模态或其他呈现中提供相同的内容。

高级定制

除了 html-page.twig 布局提供的块之外，还可以通过覆盖 web.twig 布局模板中的块（html-page.twig 布局从中扩展）来进一步自定义渲染的页面。

┌─────────────────────────────────────────────────────────────────────────────┐
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │                                 htmlTag                                 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │                                 headTag                                 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │                               headContent                               │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │                                 bodyTag                                 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │                               bodyContent                               │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│                                  htmlPage                                   │
└─────────────────────────────────────────────────────────────────────────────┘

所以，如果你需要具有特定属性的 <html>、<head> 或 <body> 标签，你可以轻松做到这一点

{% block htmlTag %}
    <html class="some-feature">
{% endblock htmlTag %}

{% block headTag %}
    <head class="some-feature">
{% endblock headTag %}

{% block bodyTag %}
    <body class="some-feature">
{% endblock bodyTag %}

你也可以完全替换 <head> 或 <body> 标签中包裹的内容

{% block headContent %}
    {# -- anything you like -- #}
{% endblock headContent %}

{% block bodyContent %}
    {# -- anything you like -- #}
{% endblock bodyContent %}

你甚至可以通过覆盖包含页面所有渲染内容的 htmlPage 块来完全替换页面上渲染的一切

{% block htmlPage %}
    {# -- anything you like -- #}
{% endblock htmlPage %}

路线图

一些要完成的事情以及潜在功能的想法

添加更多扩展 html-page.twig 的布局，以提供额外的有见地的功能

由 nystudio107 提供

nystudio107 / craft-twig-base-templates

维护者

详细信息

README

要求

安装

使用方法

扩展 `html-page.twig` 基础布局

基础布局块

渲染父块内容

特殊的 AJAX `content` 块

高级定制

路线图

nystudio107 / craft-twig-base-templates

维护者

详细信息

README

要求

安装

使用方法

扩展 html-page.twig 基础布局

基础布局块

渲染父块内容

特殊的 AJAX content 块

高级定制

路线图

扩展 `html-page.twig` 基础布局

特殊的 AJAX `content` 块