README

版本 1.2.0

功能和用法说明

在网站页面构建时，通常只有特定区域放置主要内容，其余部分由独立或与主要内容弱相关的块组成。为了方便描述块的位置，应使用“布局”机制。这样，块的列表及其顺序将记录在单独的XML文件中。

布局文件格式

<?xml version="1.0" encoding="UTF-8"?>
<layout xmlns="https://symfony.ac.cn/schema/dic/layouts" template="@SymfonyLayout/layout.html.twig">
	<stripe>
		<column>
			<block id="container">
				<arg name="comment" value="The place for content from main controller."/>
			</block>
		</column>
	</stripe>
</layout>

在此示例中，标准的模板 "@SymfonyLayout/layout.html.twig" 负责生成HTML代码，它通过水平条带（stripe）表示块的布局，这些条带被分成列（column），每列包含一个块。一个简单的示例显示了一个由一个条带和一个列组成的布局，其中放置了一个包含网站主要内容的块（块用于主要内容的指示是通过具有值 container 的 id 属性来实现的）。

在主要内容的块之前添加网站主菜单的块。

<?xml version="1.0" encoding="UTF-8"?>
<layout xmlns="https://symfony.ac.cn/schema/dic/layouts" template="@SymfonyLayout/layout.html.twig">
	<stripe>
		<column>
			<block uri="/.blocks/main-menu">
				<arg name="active" request="heading"/>
			</block>
			<block id="container"/>
		</column>
	</stripe>
</layout>

此块具有URI控制器，该控制器将被调用。同时，将添加一个名为 active 的GET参数，其值将从请求对象中的 heading 键获取。在示例中，这将是分类的字符代码。

为了更方便地使用，可以指定块描述的单独XML文件。

<?xml version="1.0" encoding="UTF-8"?>
<block xmlns="https://symfony.ac.cn/schema/dic/blocks" uri="/.blocks/main-menu">
	<arg name="active" request="heading"/>
</block>

那么布局的XML将具有以下形式。

<?xml version="1.0" encoding="UTF-8"?>
<layout xmlns="https://symfony.ac.cn/schema/dic/layouts" template="@SymfonyLayout/layout.html.twig">
	<stripe>
		<column>
			<block extends="block-main-menu.xml"/>
			<block id="container"/>
		</column>
	</stripe>
</layout>

在继承块时，可以重写任何参数或添加新的参数。可以按照以下方式设置参数值

<block>
	<arg name="from_request_object" request="key"/>
	<arg name="from_configuration" config="key"/>
	<arg name="specific_value" value="key"/>
	<arg name="boolean_value" flag="true"/>
	<arg name="array_value" array="item1, item2"/>
</block>

此外，还可以添加 default 和 optional 属性。使用第一个添加“默认值”，如果没有请求或配置中的适当键，则将其分配。在添加 optional 属性（其值是 true 或 false）的情况下，有两种情况：如果没有添加 default 属性，则当源中没有键时，将忽略该参数；否则，如果其值与默认值匹配，则忽略它。

将布局与控制器匹配

如果服务器响应中包含执行操作的控制器的打开和关闭 layout 标签，则它们将被布局的HTML代码替换，而它们之间的内容将被插入到具有 id 等于 container 的块的位置。

现在我们需要将控制器与适当的布局关联起来。

第一种方法 - 使用注解

<?php
use Moro\SymfonyLayout\Annotation\Layout;

class Controller {
	/**
	 * @Layout("layout_name")
	 */
	function action() {
		//...
	}
}

一个操作可以包含多个注解，此时部分注解需要满足条件才能使用。注解将按顺序和指定顺序进行检查。

@Layout("layout_name", active="from('2018/10/11 12:00:00', 'Europe/Moscow') and to('2018/10/12')")
@Layout("layout_name", from="2018/10/11 12:00:00, Europe/Moscow, to="2018/10/12")
@Layout("layout_name")

由于使用 \DateTime 类来转换日期，因此可以使用如 Monday this week 12:00 这样的结构。

第二种方法 - 使用服务

<?php
use Moro\SymfonyLayout\Manager\LayoutManager;
class Controller {
	function action(LayoutManager $manager) {
		$manager->setName("layout_name");
		//...
	}
}

在这种情况下，选择布局的逻辑完全由操作控制器的代码处理。