内容管理系统主题

• Introduction
• 目录结构
  • Subdirectories
• 模板结构
  • 配置部分
  • PHP代码部分
  • 树枝标记部分
• 主题日志
• 数据库驱动的主题

#Introduction

主题定义了使用 Winter 构建的网站或 Web 应用程序的外观。Winter主题完全由文件支持，可以使用任何版本控制系统进行管理，例如 Git。此页面为您提供Winter主题的高级描述。你会发现更多关于pages,partials,layouts 和内容文件 在相应的文章中。

NOTE: 主题可以将模板存储在数据库中，如果cms.databaseTemplates 已启用，请参阅数据库驱动的主题 部分了解更多信息。

主题是驻留在/themes 默认目录。主题可以包含以下对象：

#目录结构

下面，您可以看到一个示例主题目录结构。每个Winter主题都用一个单独的目录表示，通常，一个活动主题用于显示网站。此示例显示“example-theme”主题目录。

📂 themes
 ┗ 📂 example-theme
   ┣ 📂 assets                <-- Theme assets
   ┃ ┣ 📂 css
   ┃ ┣ 📂 fonts
   ┃ ┣ 📂 images
   ┃ ┣ 📂 javascript
   ┃ ┣ 📂 scss
   ┃ ┗ 📂 vendor
   ┣ 📂 content               <-- Static content files
   ┃ ┣ 📂 static-pages        <-- Content files from the Winter.Pages plugin
   ┃ ┃ ┗ 📜 index.htm
   ┃ ┗ 📜 welcome.htm
   ┣ 📂 layouts               <-- Theme Layouts (Page scaffolds / templates)
   ┃ ┣ 📜 default.htm
   ┃ ┗ 📜 sidebar.htm
   ┣ 📂 meta                  <-- Menu definitions and other plugin specific YAML files
   ┃ ┣ 📂 menus
   ┃ ┃ ┣ 📜 main-menu.yaml
   ┃ ┃ ┗ 📜 sitemap.yaml      <-- Meta file describing the sitemap
   ┃ ┗ 📜 static-pages.yaml   <-- Meta file describing the structure of the Winter.Pages static pages
   ┣ 📂 pages                 <-- Theme Pages (Contain the routing for the frontend)
   ┃ ┣ 📜 404.htm             <-- Page for 404 responses
   ┃ ┣ 📜 home.htm
   ┃ ┣ 📜 error.htm           <-- Page for 500 responses
   ┃ ┗ 📜 sitemap.htm         <-- Page for rendering the sitemap response
   ┣ 📂 partials              <-- Theme Partials (Reusable pieces of HTML markup)
   ┃ ┣ 📜 html-footer.htm
   ┃ ┣ 📜 html-header.htm
   ┃ ┗ 📜 navbar.htm
   ┣ 📜 theme.yaml            <-- Theme information file
   ┗ 📜 version.yaml          <-- Theme updates file

活动主题设置为activeTheme 中的参数config/cms.php 文件或使用系统 > CMS > 前端主题后端页面上的主题选择器。使用主题选择器设置的主题会覆盖config/cms.php 文件。

#Subdirectories

Winter 支持单级子目录pages,partials,layouts 和content 文件，而assets 目录可以有任何结构。这简化了大型网站的组织。在下面的示例目录结构中，您可以看到pages 和partials 目录包含blog 子目录，以及content 目录包含home 子目录。

📂 themes
 ┗ 📂 website
   ┣ 📂 pages
   ┃ ┣ 📜home.htm
   ┃ ┗ 📂 blog                  <=== Subdirectory
   ┃   ┣ 📜 archive.htm
   ┃   ┗ 📜 category.htm
   ┣ 📂 partials
   ┃ ┣ 📜 sidebar.htm
   ┃ ┗ 📂 blog                  <=== Subdirectory
   ┃   ┗ 📜 category-list.htm
   ┗ 📂 content
     ┣ 📜 footer-contacts.txt
     ┗ 📂 home                  <=== Subdirectory
       ┗ 📜 intro.htm

要引用子目录中的部分文件或内容文件，请在模板名称之前指定子目录的名称。从子目录渲染部分的示例：

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

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

#模板结构

页面、部分和布局模板最多可包含 3 个部分：configuration,PHP代码， 和树枝标记. 部分用== 顺序。 例如：

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;

#树枝标记部分

Twig 部分定义要由模板呈现的标记。在 Twig 部分，您可以使用函数、标签和过滤器Winter提供， 一切原生 Twig 功能, 或者那些由插件提供. Twig 部分的内容取决于模板类型（页面、布局或部分）。您可以在文档中进一步找到有关特定 Twig 对象的更多信息。

可以找到更多信息在标记指南中.

#主题日志

Winter CMS 带有一个非常有用的功能，默认情况下禁用，称为主题日志记录。

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

要启用主题日志记录，只需转到设置 -> 日志设置 并启用记录主题变化.现在记录了所有更改。

可以在以下位置查看主题更改日志设置 -> 主题日志.每个更改都有已添加/删除的内容的概述，以及前后更改文件的副本。您可以使用此信息来决定适当的操作，以在必要时帮助恢复这些更改。

#数据库驱动的主题

Winter CMS 带有另一个非常有用的功能，默认情况下禁用，称为数据库驱动主题。启用此功能时（通过设置cms.databaseTemplates 到true， 或者null 什么时候app.debug 是false);数据库层将所有修改过的 CMS 文件存储在数据库中。未修改的文件继续从文件系统加载。有一个theme:sync $themeDir 控制台命令，可用于同步文件系统和数据库之间的更改。

在数据库中修改的文件被缓存以指示它们应该从数据库中加载。

NOTE: 所有 CMS 模板对象（例如Layout,Page,Content,Partial,Meta等）在启用此功能并且对相关模板进行更改时存储在数据库中；但是主题资产文件将not 是。