October CMS 使用多种标准来处理标记、模板和配置。每种标准都经过精心选择,以使其在简化您的开发过程和学习曲线方面发挥作用。举例来说,[主题中找到的对象](../../cms/themes/themes.md) 使用 Twig 和 INI 格式作为其模板结构。每个解析器都将在下面详细描述。
Markdown 允许您编写易于阅读和易于编写的纯文本格式,然后将其转换为 HTML。 Markdown 门面用于解析 Markdown 语法,并基于 GitHub 风格的 Markdown。 Markdown 的一些快速示例:
This text is **bold**, this text is *italic*, this text is ~~crossed out~~.
# The largest heading (an <h1> tag)
## The second largest heading (an <h2> tag)
...
###### The 6th largest heading (an <h6> tag)使用 Markdown::parse 方法将 Markdown 渲染为 HTML:
$html = Markdown::parse($markdown);您还可以使用 |md 过滤器来在前端标记中解析 Markdown。
{{ '**Text** is bold.'|md }}Markdown 是 HTML 的超集,因此你可以在同一个模板中结合使用 HTML 和 Markdown。当 Markdown 遇到任何块级 HTML 标签时,其中的所有内容都将停用 Markdown 语法。
<div>
This **text** won't be parsed by *Markdown*
</div>值得注意的是,Markdown 解析器每行只接受一个 HTML 节点。 在下面的示例中,第二个节点不包含在输出中。
<!-- Output: <p>Foo</p> -->
<p>Foo</p><p>Bar</p>在显示复杂 HTML 时,尤其通过 Twig 变量时,您应该将该变量包裹在一个单一的 HTML 节点中,以确保捕获所有输出。
<div>
{{ messageBody|raw }}
</div>如果您有意在块级标签内启用 Markdown,可以通过添加 markdown 属性到该标签,并将其值设置为 1。
<div markdown="1">
This **text** is now bold.
</div>Twig 是一个简单但功能强大的模板引擎,它解析 HTML 模板为优化的 PHP 代码,它是 前端标记、视图内容 和 邮件消息内容 的驱动力。
该 Twig 门面 是 使用 于 解析 Twig 语法, 您 可以 使用 该 Twig::parse 方法 来 渲染 Twig 为 HTML。
$html = Twig::parse($twig);第二个参数可用于将变量传递给 Twig 标记。
$html = Twig::parse($twig, ['foo' => 'bar']);Twig 解析器可以通过 插件注册文件 扩展以注册自定义功能。
October CMS 还附带一个简单的方括号模板解析器,作为 Twig 解析器的替代方案,目前用于将变量传递给主题内容块。该引擎渲染 HTML 更快,并且设计为更适合非技术用户。这个解析器没有外观模式,因此应该将完全限定的 October\Rain\Parse\Bracket 类与 parse 方法一起使用。
use October\Rain\Parse\Bracket;
$html = Bracket::parse($content, ['foo' => 'bar']);语法使用单个花括号来渲染变量:
<p>Hello there, {foo}</p>
你也可以传递一个待解析的对象数组作为变量。
$html = Template::parse($content, ['likes' => [
['name' => 'Dogs'],
['name' => 'Fishing'],
['name' => 'Golf']
]]);该数组可以使用以下语法进行迭代:
<ul>
{likes}
<li>{name}</li>
{/likes}
</ul>
YAML ("YAML不是标记语言") 是一个配置格式,类似于Markdown它被设计成一个易于阅读和易于编写的格式,能够转换为一个PHP数组。它在October CMS的后端开发中几乎随处可见,例如表单字段定义。一些YAML的示例:
receipt: Acme Purchase Invoice
date: 2015-10-02
user:
name: Joe
surname: Blogs此 Yaml 门面用于解析 YAML,你可以使用 Yaml::parse 方法将 YAML 渲染为 PHP 数组:
$array = Yaml::parse($yamlString);使用 parseFile 方法来解析文件的内容:
$array = Yaml::parseFile($filePath);解析器还支持反向操作,从 PHP 数组输出 YAML 格式。为此,您可以使用 render 方法:
$yamlString = Yaml::render($array);INI 文件格式是定义简单配置文件的一种标准,常用于 主题模板中的组件。它可被视为 YAML 格式的近亲,尽管与 YAML 不同,它极其简单,对拼写错误的敏感度较低,并且不依赖于缩进。它支持带有节的基本键值对,例如:
receipt = "Acme Purchase Invoice"
date = "2015-10-02"
[user]
name = "Joe"
surname = "Blogs"Ini 门面用于解析 INI,您可以使用 Ini::parse 方法将 INI 渲染为 PHP 数组:
$array = Ini::parse($iniString);使用 parseFile 方法解析文件内容:
$array = Ini::parseFile($filePath);解析器也支持逆向操作,从 PHP 数组输出 INI 格式。您可以使用 render 方法用于此:
$iniString = Ini::render($array);传统上,PHP 函数 parse_ini_string 使用的 INI 解析器仅限于深度为 3 级的数组。例如:
level1Value = "foo"
level1Array[] = "bar"
[level1Object]
level2Value = "hello"
level2Array[] = "world"
level2Object[level3Value] = "stop here"October 已经通过 October 风格的 INI 扩展了此功能,以允许无限深度的数组,其灵感来源于 HTML 表单的语法。 承接上述示例,支持以下语法:
[level1Object]
level2Object[level3Array][] = "Yay!"
level2Object[level3Object][level4Value] = "Yay!"
level2Object[level3Object][level4Array][] = "Yay!"
level2Object[level3Object][level4Object][level5Value] = "Yay!"
; ... to infinity and beyond!动态语法是 October 独有的一种模板引擎,它根本上支持两种渲染模式。解析模板会产生两种结果,要么是 视图 模式,要么是 编辑器 模式。以这段模板文本为例,{text}...{/text} 标签的内部部分表示 视图 模式的默认文本,而内部属性 name 和 label 则用作 编辑器 模式的属性。
<h1>{text name="websiteName" label="Website Name"}Our wonderful website{/text}</h1>
此解析器没有门面,因此应使用完全限定的 October\Rain\Parse\Syntax\Parser 类并配合 parse 方法。parse 方法的第一个参数接受模板内容作为字符串,并返回一个 Parser 对象。
use October\Rain\Parse\Syntax\Parser as SyntaxParser;
$syntax = SyntaxParser::parse($content);假设我们使用上面第一个例子作为模板内容,仅调用 render 方法本身将会使用默认文本渲染模板:
echo $syntax->render();
// <h1>Our wonderful website</h1>就像任何模板引擎一样,将一个变量数组传递给 render 的第一个参数将替换模板内部的变量。在这里,websiteName 的默认值被我们的新值替换:
echo $syntax->render(['websiteName' => 'October CMS']);
// <h1>October CMS</h1>作为一项额外特性,调用 toTwig 方法将输出处于预备状态的模板,供 Twig 引擎渲染。
echo $syntax->toTwig();
// <h1>{{ websiteName }}</h1>截至目前,Dynamic Syntax 解析器与普通模板引擎并无太大区别,然而,编辑器模式才是 Dynamic Syntax 实用性更显的地方。编辑器模式解锁了新的可能性,例如,布局将自定义表单字段注入到属于它们的页面,或者用于电子邮件营销活动的动态构建表单。
为了承接上述示例,在 Parser 对象上调用 toEditor 方法将返回一个 PHP 属性数组,该数组定义了变量应如何填充,例如通过表单构建器。
$array = $syntax->toEditor();
// 'websiteName' => [
// 'label' => 'Website name',
// 'default' => 'Our wonderful website',
// 'type' => 'text'
// ]您可能会注意到这些属性与表单字段定义中找到的选项非常相似。这是有意为之,以便这两个特性能够相互补充。我们现在可以轻松地将上述数组转换为 YAML,并写入到一个 fields.yaml 文件中:
$form = [
'fields' => $syntax->toEditor()
];
File::put('fields.yaml', Yaml::render($form));有各种标签类型可与 Dynamic Syntax 解析器一起使用,这些旨在匹配常见的表单字段类型。
单行输入用于较小的文本块
{text name="websiteName" label="Website Name"}Our wonderful website{/text}多行输入用于较大的文本块。
{textarea name="websiteDescription" label="Website Description"}
This is our vision for things to come
{/textarea}渲染一个下拉表单字段。
{dropdown name="dropdown" label="Pick one" options="One|Two"}{/dropdown}渲染一个下拉表单字段,具有独立的值和标签。
{dropdown name="dropdown" label="Pick one" options="one:One|two:Two"}{/dropdown}渲染一个下拉表单字段,使用一个由静态类方法返回的数组(该类必须是完全命名空间的类)。
{dropdown name="dropdown" label="Pick one" options="Path\To\Class::method"}{/dropdown}渲染一个单选表单字段。
{radio name="radio" label="Thoughts?" options="y:Yes|n:No|m:Maybe"}{/radio}按照 type 属性中定义的表单字段类型进行渲染。此标签将仅设置一个变量,并在视图模式下渲染为空字符串。
{variable type="text" name="name" label="Name"}John{/variable}富文本(WYSIWYG)输入框。
{richeditor name="content" label="Main content"}Default text{/richeditor}在 Twig 中渲染为
{{ content|raw }}Markdown 内容的文本输入
{markdown name="content" label="Markdown content"}Default text{/markdown}在 Twig 中渲染为
{{ content|md }}媒体库项目的文件选择器。此标签值将包含该文件的相对路径。
{mediafinder name="logo" label="Logo"}defaultlogo.png{/mediafinder}在 Twig 中渲染为
{{ logo|media }}文件上传输入,用于文件。这个标签值将包含文件的完整路径。
{fileupload name="logo" label="Logo"}defaultlogo.png{/fileupload}颜色选择器小部件,用于颜色选择。此标签将包含选定的十六进制值。您可以选择提供一个 availableColors 属性来定义可供选择的颜色。
{colorpicker name="bg_color" label="Background colour" allowEmpty="true" availableColors="#ffffff|#000000"}{/colorpicker}渲染一个包含其他字段的重复部分。
{repeater name="content_sections" prompt="Add another content section"}
<h2>{text name="title" label="Title"}Title{/text}</h2>
<p>{textarea name="content" label="Content"}Content{/textarea}</p>
{/repeater}在 Twig 中渲染为
{% for fields in repeater %}
<h2>{{ fields.title }}</h2>
<p>{{ fields.content|raw }}</p>
{% endfor %}调用 $syntax->toEditor 将为一个中继器字段返回一个不同的数组:
'repeater' => [
'label' => 'Website name',
'type' => 'repeater',
'fields' => [
'title' => [
'label' => 'Title',
'default' => 'Title',
'type' => 'text'
],
'content' => [
'label' => 'Content',
'default' => 'Content',
'type' => 'textarea'
]
]
]中继器字段也支持分组模式,结合动态语法解析器使用,用法如下:
{variable name="sections" type="repeater" prompt="Add another section" tab="Sections"
groups="$/author/plugin/repeater_fields.yaml"}{/variable}这是 repeater_fields.yaml 组配置文件的示例:
quote:
name: Quote
description: Quote item
icon: icon-quote-right
fields:
quote_position:
span: auto
label: Quote Position
type: radio
options:
left: Left
center: Center
right: Right
quote_content:
span: auto
label: Details
type: textarea有关中继器组模式的更多信息,请参阅中继器小部件。