By accessing the website and accepting the Cookie Policy, you agree to use the cookies provided by the Site in accordance with to analyze traffic, remember your preferences, and optimize your experience.
OctoberCMS官方文档 8-组件 (Components)
October CMS    2018-10-22 18:54:42    73    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)

73 人读过
文档导航