主题开发

主题目录可以包括 theme.yaml，version.yaml和assets/images/theme-preview.png文件。 这些文件对于本地开发是可选的，但对于在OctoberCMS Marketplace上发布的主题是必需的。

主题信息文件

主题信息文件theme.yaml包含主题描述，作者姓名，作者网站的URL和一些其他信息。 该文件应放在主题根目录中：

  1. themes/
  2.   demo/
  3.     theme.yaml    <=== 主题信息文件

theme.yaml文件支持以下字段：

字段 描述
name 指定主题名称，必需。
author 指定作者姓名，必填。
homepage 指定作者网站URL。
description 主题描述，必填。
previewImage 自定义预览图像，相对于主题目录的路径，例如：assets/images/preview.png，可选。
code 主题代码，可选。 该值在OctoberCMS市场上用于初始化主题代码值。 如果未提供主题代码，则主题目录名称将用作代码。 从Marketplace安装主题时，代码将用作新的主题目录名称。
form 表单字段定义文件的配置数组或引用，用于主题自定义，可选。
require 用于主题依赖项的插件名称数组，可选。

主题信息文件的示例：

  1. name: "OctoberCMS Demo"
  2. description: "Demonstrates the basic concepts of the front-end theming."
  3. author: "OctoberCMS"
  4. homepage: "http://octobercms.com"
  5. code: "demo"

版本文件

主题版本文件version.yaml定义当前主题版本和更改日志。 该文件应放在主题根目录中：

  1. themes/
  2.   demo/
  3.     ...
  4.     version.yaml    <=== 版本文件

文件格式如下：

  1. 1.0.1: Theme initialization
  2. 1.0.2: Added more features
  3. 1.0.3: Some features are removed

主题预览图片

主题预览图像用于后端主题选择器。 图像文件theme-preview.png应放在主题的assets/images目录中：

  1. themes/
  2.   demo/
  3.     assets/
  4.       images/
  5.         theme-preview.png    <=== 预览图片

图像宽度应至少为600px。 理想的宽高比为1.5，例如600x400px。

主题定制

主题可以通过在主题信息文件中定义form键来支持配置值。 此键应包含配置数组或对表单字段定义文件的引用，有关详细信息，请参阅表单字段。

以下是如何定义名为site_name的网站名称配置字段的示例：

  1. name: My Theme
  2. # [...]
  4. form:
  5.     fields:
  6.         site_name:
  7.             label: Site name
  8.             comment: The website name as it should appear on the front-end
  9.             default: My Amazing Site!

然后可以使用名为this.theme的默认页面变量在任何Theme模板中访问该值。

  1. <h1>Welcome to {{ this.theme.site_name }}!</h1>

您还可以在单独的文件中定义配置，其中路径相对于主题。 以下定义将从主题内的文件config/fields.yaml中获取表单字段。

  1. name: My Theme
  2. # [...]
  4. form: config/fields.yaml

组合变量

使用|theme 过滤器和组合器组合的资源可以将值传递给支持过滤器，例如LESS过滤器。 在定义表单字段时，只需指定assetVar选项，该值应包含所需的变量名称。

  1. form:
  2.     fields:
  3.         # [...]
  5.         link_color:
  6.             label: Link color
  7.             type: colorpicker
  8.             assetVar: 'link-color'

在上面的例子中，选择的颜色值将在less文件中作为@link-color使用。 假设我们有以下样式表参考：

  1. <link href="{{ ['assets/less/theme.less']|theme }}" rel="stylesheet">

使用themes/yourtheme/assets/less/theme.less中的一些示例内容：

  1. a { color: @link-color }

主题依赖

主题可以通过在主题信息文件中定义require选项来依赖于插件，该选项应该提供一系列被认为是需求的插件名称。 依赖于Acme.Blog和Acme.User的主题可以像这样定义这个要求：

  1. name: "OctoberCMS Demo"
  2. # [...]
  4. require:
  5.     - Acme.User
  6.     - Acme.Blog

首次安装主题时，系统将尝试同时安装所需的插件。