README

##SilverStripe 3.1 的 Twig 模板

##概述

SilverStripe Twig 允许在 SilverStripe 3.1 中使用 Twig 模板引擎。

如果你不熟悉 Twig，可以查看文档。

##安装

###Composer

在你的 SilverStripe 项目的根目录下创建或编辑一个 composer.json 文件，并确保以下内容存在。

{
    "require": {
        "camspiers/silverstripe-twig": "0.0.*",
		"camspiers/autoloader-composer-silverstripe": "1.0.*"
    }
}

完成此步骤后，在终端或类似环境中导航到 SilverStripe 根目录，并运行 composer install 或 composer update，具体取决于你是否已经使用 composer。

##入门

###命名和放置模板的位置

在你的当前主题中创建一个名为 twig 的文件夹。这是 Twig 查找模板的地方。默认情况下，Twig 期望你的模板使用 .twig 扩展名，但可以轻松配置为查找其他扩展名（请参阅 twig.extensions）。

SilverStripe Twig 决定使用哪个模板的方式与 SilverStripe 选择 .ss 模板的方式相同。

它根据当前控制器或数据记录的类名和要调用的操作创建一个候选模板的排名列表。使用模板列表，它选择它找到的第一个模板。

例如，对于 PageType Page 的页面。如果在 twig 文件夹中有一个 Page.twig 模板，它将使用该模板。

###如何启用 twig

通过扩展你的 SilverStripe 控制器的功能来启用 Twig 渲染。这可以通过两种方式实现，具体取决于你使用的 PHP 版本。

####PHP 5.3

如果你想为所有扩展自 Page_Controller 的控制器使用 twig，设置如下

Page.php

class Page_Controller extends TwigContentController
{
}

如果你想在一个 Controller 中使用 twig，设置如下

MyController.php

class MyController extends TwigController
{
}

####PHP 5.4

上面的 PHP 5.3 类实际上是来自一个 trait 的自动生成的。要使用这个 trait，在你的控制器中添加一个 use 语句，如下所示

class Page_Controller extends ContentController
{
	use TwigControllerTrait;	
}

或

class MyController extends Controller
{
	use TwigControllerTrait;	
}

###在 twig 中访问你的控制器

默认情况下，twig 通过变量 c 将你的控制器（以及你的数据记录）提供给你的模板。

{% for Page in c.Pages %}
	{{ Page.Title }}
{% endfor %}

<title>{{ c.Title }}</title>

<ul>
{% for Page in c.Menu(1) %}
	<li>{{ Page.Title }}</li>
{% else %}
	<li>No pages</li>
{% endfor %}
</ul>

###实际使用示例

使用 twig 实现类似于 SilverStripe 的 $Layout 变量的功能很简单。

Twig 有 extends 和 blocks 的概念，这使得灵活的模板重用成为可能。

Page.twig

{% extends "layouts/layout.twig" %}

{% block head %}
	{{ parent() }}
	{# add some extra assets here #}
{% endblock %}

{% block header %}
	{# add some header content here #}
{% endblock %}

{% block content %}
	<h1>{{ c.Title }}</h1>
{% endblock %}

layouts/layout.twig

<html>
	<head>
		{% block head %}
			{# default assets here #}
		{% endblock %}
	</head>
	<body>
		{% block header %}{% endblock %}
		{% block content %}{% endblock %}
	</body>
</html>

##配置

SilverStripe Twig 使用依赖注入容器（Pimple 的扩展）来允许配置和 DI 所有使用的对象。

选项

twig.environment_options
twig.extensions
twig.compilation_cache
twig.template_paths
twig.controller_variable_name

示例

mysite/_config.php

TwigContainer::extendConfig(array(
	'twig.environment_options' => array(
        'debug' => true
    ),
    'twig.extensions' => array(
    	'.twig',
    	'.html'
    ),
    'twig.compilation_cache' => BASE_PATH . '/silverstripe-cache',
    'twig.template_paths' => array(
    	THEMES_PATH . '/my-theme/templates'
    ),
    'twig.controller_variable_name' => 'controller'
));

可以通过实例化容器来访问 SilverStripe Twig 提供的任何服务。

$dic = new TwigContainer;
$dic['twig']->loadTemplate('template.twig')->render();

有关更多信息，请参阅 Pimple。

##同时使用 Twig 和 Haml SilverStripe twig 支持通过 SilverStripe haml 模块使用 haml。

安装 SilverStripe haml 模块，你就可以开始使用了。

现在你可以将文件命名为 .haml（尽管不一定要这样做）。

###使用

要使 Twig 将文件作为 Haml 处理，请添加以下内容

{% haml %}

到任何你想作为 haml 处理的模板的顶部。

示例

{% haml %}
!!!
%html
	%head
		%title #{ c.Title } | haml and twig
		- block head
			:javascript
				console.log('yay');
	%body
		- block content
			%h1 #{ c.Title }
			%p #{ c.Content|raw }
			%span.created #{ c.Created|date("d/m/Y") }

##贡献

###代码规范

本项目遵循以下标准定义：

PSR-1
PSR-2

##许可证

SilverStripe Twig 在 MIT 许可证下发布

camspiers / silverstripe-twig

维护者

详细信息

README