OctoberCMS官方文档 8-组件 (Components)
October CMS    2018-10-22 18:54:42    72    0    0
emengweb   October CMS

Components

Components这里我们称之为组件。

组件是可以配置的构建元素。可以附加到Pages(页面)、Layouts(布局)、Partials(部件)中。组件是October的核心特性。每个组件都可以对网站的功能进行扩展。组件可以在页面上输出HTML代码,但是这不是主要的,组件的一个重要功能是处理Ajax请求、处理表单提交回调,处理页面执行周期。允许向页面注入变量或者实现网站安全性。

介绍

启用组件,如果是后端管理系统中,可以选择组件面板,将组件拖动添加到页面、部件和布局中。如果是采用文本编辑模式,则可以将组件的对应模板的名称添加到对应的模板的配置部分。比如:下面的例子演示了如何将todolist组件添加到页面中。

title = "Components demonstration"
url = "/components"

[demoTodo]
maxItems = 20
==
...

当您引用Components时,它会自动创建一个与Components名称匹配的Page变量(在前面的示例中为demoTodo)。提供HTML标记的Components可以使用标记在Page上呈现{% component %},如下所示:

{% component 'demoTodo' %}

如果具有相同名称的两个组件分配给Page和Layout,Page中的组件将覆盖布局中的组件。

组件的别名

如果有两个注册Components的名称相同,则可以使用完全限定的名称引用组件,并为其指定一个别名:

[October\Demo\Components\Todo demoTodoAlias]
maxItems = 20

第一个参数是类名,第二个参数是注入到Page时使用的组件的别名。如果您指定了组件的别名,那么在引用组件时,可以页面代码中的任何地方使用。下一个示例引用Components别名:

{% component 'demoTodoAlias' %}

允许给同一个组件定义多个别名,以实现在同一个页面上使用一个组件的多个实例

[demoTodo todoA]
maxItems = 10
[demoTodo todoB]
maxItems = 20

组件使用外部属性值

默认情况下,属性值在定义组件的配置部分会进行初始化,这时候属性值是静态的,如下所示:

[demoTodo]
maxItems = 20
==
...

不过有一个办法可以使用外部的参数为组件属性进行初始化。可以是URL参数,Partial部件参数。使用{{ paramName }}从外部变量加载的值的语法:

[demoTodo]
maxItems = {{ maxItems }}
==
...

假设在上面的示例中,组件 demoTodo 在部件中使用,则部件的变量maxItems将为组件的变量进行初始化:

{% partial 'my-todo-partial' maxItems='10' %}

如果是URL参数,则使用的方式略有不同:使用{{ :paramName }}名称以冒号(:)开头的语法

[demoTodo]
maxItems = {{ :maxItems }}
==
...

组件对应的页面在配置部分,应该具有相应的URL参数定义:

url = "/todo/:maxItems"

在October的后端,您可以使用Inspector工具将外部值分配给Components属性。在Inspector中,您不需要使用大括号输入参数名称。Inspector中的每个字段在右侧都有一个图标,用于打开外部参数名称编辑器。输入paramName部分变量或:paramNameURL参数的参数名称。

将变量传递给组件

组件可以设计为在呈现时使用变量,类似于部分变量,可以在{%component%}标记中的组件名称之后指定它们。
指定的变量将显式覆盖组件属性的值,包括外部属性值。
在此示例中,组件的maxItems属性在呈现组件时将设置为7:
{% component 'demoTodoAlias' maxItems='7' %}​
注意:渲染时并非所有组件都支持传递变量。

自定义默认标记

组件提供的标记通常用作组件的使用示例。在某些情况下,您可能希望修改组件的外观和输出。将默认标记移动到主题部分适合于彻底检查组件。覆盖组件部分对于要定制的区域非常有用。

将默认标记移动到部件中

每个组件都可以有一个名为default.htm的入口点部分,在调用{%component%}标记时呈现,在下面的示例中,我们假设该组件名为blogPost

url = "blog/post"

[blogPost]
==
{% component "blogPost" %}​
输出结果将从插件目录components/blogpost/default.htm渲染。
您可以复制此文件中的所有标记,并将其直接粘贴到页面中,或者粘贴到名为blog-post.htm的新部分中。
<h1>{{ __SELF__.post.title }}</h1>
<p>{{ __SELF__.post.description }}</p>​

在标记内部,您可能会注意到一个名为__SELF__的变量的引用,这是指组件对象,应该替换为页面上使用的组件别名,在本例中它是blogPost

<h1>{{ blogPost.post.title }}</h1>
<p>{{ blogPost.post.description }}</p>​
这是允许默认组件标记在主题内的任何位置工作所需的唯一更改。
现在可以使用主题部件来自定义和呈现组件标记。
{% partial 'blog-post.htm' %}​

可以对组件部分目录中找到的所有其他部分重复此过程。

覆写组件部件

可以使用主题部件覆写所有组件部件。如果名为 channel 的组件使用 title.htm 部件。
url = "mypage"

[channel]
==
{% component "channel" %}​

我们可以通过在我们的主题中创建一个名为 partials/channel/title.htm 的文件来覆盖部件。

文件路径段分解如下:

分段描述
partials此主题的部件目录
channel组件别名 (部件的子目录)
title.htm需要覆写的组件部件
 
通过简单地为组件分配同名别名,可以将部分子目录名称自定义为任何名称。
例如,通过为 channel 组件分配不同的别名foobar,这样还会更改覆写目录:
[channel foobar]
==
{% component "foobar" %}​
现在我们可以通过在我们的主题中创建一个名为 partials/foobar/title.htm 的文件来覆写 title.htm 部件。

View Bag 组件

October有一个名为 viewBag 的特殊组件,可用于任何页面或布局。它允许在标记区域内轻松定义和访问 ad hoc 属性作为变量。
一个很好的用法示例是在页面内定义活动菜单项:
title = "About"
url = "/about.html"
layout = "default"

[viewBag]
activeMenu = "about"
==

<p>Page content...</p>​
然后,使用viewBag变量在页面,布局或部分标记内部为组件定义的任何属性都可用。
例如,在此布局中,如果viewBag.activeMenu值设置为 about ,则将活动类添加到列表项:
description = "Default layout"
==
[...]

<!-- Main navigation -->
<ul>
    <li class="{{ viewBag.activeMenu == 'about' ? 'active' }}">About</li>
    [...]
</ul>​
注意:viewBag组件隐藏在后端,仅适用于基于文件的编辑。它也可以被其他插件用来存储数据。

上一篇: October CMS官方文档 1-安装 (Setup)

下一篇: OctoberCMS官方文档 7-内容块 (Content Blocks)

72 人读过
文档导航