主题

活跃主题可通过 config/cms.php 文件中的 active_theme 项设置，也可通过 设置 → 前端主题 后台面板设置。后台设置会覆盖 config/cms.php 文件中的值。

主题完全基于文件，并可以使用任何版本控制系统（例如 Git）进行管理。本页面为您提供 October CMS 主题的高级概述。您将在下方对应的文章中找到有关页面、局部、布局和内容文件的更多详细信息。

主题是默认情况下位于 themes 目录中的目录。主题可以包含以下对象：

目录结构

下面，您可以看到一个示例主题目录结构。每个主题都代表一个独立的目录，通常只有一个主题处于活动状态来显示网站。此示例展示了 website 主题目录。

├── themes
| └── website ← 主题从此处开始
| ├── pages
| │ └── index.htm
| ├── layouts
| │ └── default.htm
| ├── partials
| │ └── sidebar.htm
| ├── content
| │ └── footer-contacts.md
| └── assets
| ├── css
| | └── my-styles.css
| ├── js
| └── images

子目录

October CMS 支持五个子目录深度，用于页面、局部文件、布局和内容文件，而资产目录可以有无限深度。这种方法简化了大型网站的组织。在下面的示例目录结构中，页面和局部文件目录包含博客子目录，并且内容目录包含主页子目录。

├── themes
| └── website
| ├── pages
| │ ├── index.htm
| │ └── blog ← Page Subdirectory
| │ ├── index.htm
| │ └── category.htm
| ├── layouts
| │ └── default.htm
| ├── partials
| │ ├── sidebar.htm
| │ └── blog ← Partial Subdirectory
| │ └── category-list.htm
| ├── content
| │ ├── footer-contacts.md
| │ └── home ← Content Subdirectory
| │ └── intro.md
| └── assets

要引用子目录中的模板，请在模板名称之前指定子目录的名称。 例如，渲染 category-list 局部 来自 blog 子目录。

模板路径始终是绝对的。如果在局部视图中渲染同一子目录下的另一个局部视图，您仍然需要指定该子目录的名称。

{% partial "blog/category-list" %}

:::

模板结构

页面、部分和布局模板最多可以包含 3 个部分：配置、PHP 代码和Twig 标记。部分使用 == 序列分隔。

url = "/blog"
layout = "default"

function onStart()
{
    $this['posts'] = [...];
}

<h3>Blog archive</h3>
{% for post in posts %}
    <h4>{{ post.title }}</h4>
    {{ post.content }}
{% endfor %}

配置节

配置部分设置模板参数. 支持的配置参数因不同的 CMS 模板而异，并在其相应的文档文章中进行描述. 配置部分使用简单的 INI 格式, 其中字符串参数值用引号括起来. 页面模板的配置部分示例:

url = "/blog"
layout = "default"

[component]
parameter = "value"

PHP 代码部分

PHP 部分中的代码每次在模板渲染之前执行。PHP 部分对于所有 CMS 模板都是可选的，其内容取决于定义它的模板类型。PHP 代码部分可以包含可选的 PHP 起始和结束标记，以在文本编辑器中启用语法高亮显示。起始和结束标记应始终与节分隔符 == 在不同行上指定。

url = "/blog"
layout = "default"

<?
function onStart()
{
    $this['posts'] = [...];
}
?>

<h3>Blog archive</h3>
{% for post in posts %}
    <h4>{{ post.title }}</h4>
    {{ post.content }}
{% endfor %}

在 PHP 部分中，您只能定义函数，并使用 PHP 的 use 关键字引用命名空间。在 PHP 部分中不允许出现其他 PHP 代码。这是因为当页面被解析时，PHP 部分会被转换为一个 PHP 类。以下是使用命名空间引用的一个示例。

url = "/blog"
layout = "default"

<?
use Acme\Blog\Classes\Post;

function onStart()
{
    $this['posts'] = Post::get();
}
?>

作为设置变量的一般方法，您应该在 $this 上使用数组访问方法，尽管为了简化您可以使用只读的对象访问，例如：

// Write via array
$this['foo'] = 'bar';

// Read via array
echo $this['foo'];

// Read-only via object
echo $this->foo;

定义函数时，它们可以通过 PHP 中的 $this 属性和 Twig 中的 this 变量作为方法使用。下面的例子定义了一个 doSomething 函数，并在两个地方调用该方法。

url = "/"

function onStart()
{
    $this['foo'] = $this->doSomething();
}

function doSomething()
{
    return 'bar';
}

<h3>{{ this.doSomething() }}</h3>

Twig 标记部分

Twig 部分定义了模板要渲染的标记。在 Twig 部分中，您可以使用 October CMS 提供的函数、标签和过滤器，所有 原生的 Twig 功能，或者插件提供的功能。Twig 部分的内容取决于模板类型（页面、布局或局部）。您可以在文档中找到有关特定 Twig 对象的更多信息。

更多信息请参见标记指南。

主题日志

由于布局和页面将大部分数据存储在平面文件中，您或您的客户可能会意外丢失内容。例如，切换页面的布局将修改页面的脚手架，因此将导致数据丢失。

October CMS 可以记录对主题所做的每一次更改，这项功能名为主题日志，并且默认处于禁用状态。要启用主题日志，前往 设置 → 日志设置 并启用 记录主题更改。

您现在可以通过 设置 → 主题日志 查看主题更新日志，您可以在其中查看每次更改的概览。您可以使用这些信息来决定适当的措施，以便在必要时协助这些更改的回溯。

另请参阅

• CMS 标记指南