README

Charcoal\View 模块（locomotivemtl/charcoal-view）提供了渲染模板和向对象添加渲染器所需的一切。

它是在各种 渲染引擎 之上的一层薄薄的层，例如 mustache 或 twig，它可以作为任何框架的视图组件使用，也可以作为 PSR-7 渲染器（例如 Slim）

它是 charcoal-app 项目的默认视图层。

如何安装

安装 charcoal-view 的首选（且唯一支持）方式是使用 composer

$ composer require locomotivemtl/charcoal-view

要安装包括 charcoal-view 在内的完整 Charcoal 项目

$ composer create-project locomotivemtl/charcoal-project-boilerplate:@dev --prefer-source

依赖关系

PHP 7.1+
- 旧版本的 PHP 已被弃用，因此不支持。
psr/http-message
- Charcoal View 提供了 PSR7 渲染器。
locomotivemtl/charcoal-config
- 视图对象可以使用 \Charcoal\View\ViewConfig 进行配置。 locomotivemtl/charcoal-translator
- 翻译服务
erusev/parsedown
- 一个 markdown 解析器，它可以提供给引擎或作为服务使用。

可选依赖关系

mustache/mustache
- 默认渲染引擎是 mustache，因此通常应该包含在内。
- 所有默认 charcoal 模块都使用 mustache 模板。
twig/twig
- Twig 也可以用作视图的渲染引擎。
pimple/pimple
- 可以使用 Pimple ServiceProvider（\Charcoal\View\ViewServiceProvider）进行依赖关系管理
- 它实际上是 charcoal-app 的默认要求。

👉 开发依赖关系在本 README 文件的开发部分中描述。

基本用法

可以使用 View 渲染任何模板（可以从引擎加载），并将任何对象（或数组，对于 twig）作为上下文。

use Charcoal\View\Mustache\MustacheLoader;
use Charcoal\View\Mustache\MustacheEngine;
use Charcoal\View\GenericView;

$loader = new MustacheLoader([
    'base_path' => __DIR__,
    'paths'     => [
        'templates',
        'views
    ]
]);

$engine = new MustacheEngine([
    'loader' => $loader
]);

$view = new GenericView([
    'engine'  => $engine
]);

echo $view->render('foo/bar/template', $context);

// A template string can also be used directly, with `renderTemplate()`
$str = 'My name is {{what}}';
echo $view->renderTemplate($str, $context);

基本用法，使用服务提供商

可以使用 ViewServiceProvider 避免所有这些引导代码。此提供程序期望一个 config 对象

use Pimple\Container;
use Charcoal\View\ViewServiceProvider;

$container = new Container([
    'base_path' => __DIR__,
    'view' = [
        'default_engine' -> 'mustache',
        'paths' => [
            'views',
            'templates'
        ]
    ]
]);
$container->register(new ViewServiceProvider());

echo $container['view']->render('foo/bar/template', $context);

👉 那些示例中使用的默认视图引擎将是 mustache。

使用 Slim 中的渲染器

视图还可以隐式用作渲染服务。使用提供的 view/renderer 和 PSR7 框架（例如，Slim 3）

use Charcoal\View\ViewServiceProvider;

include 'vendor/autoload.php';

$app = new \Slim\App();
$container = $app->getContainer();
$container->register(new ServiceProvider());

$app->get('/hello/{name}', function ($request, $response, $args) {
    // This will render the "hello" template
    return $this->renderer->render($response, 'hello', $args);
});

$app->run();

就像视图一样，可以将所有依赖关系简单地注册到 Pimple 容器中（使用 ViewServiceProvider），以避免所有这些引导代码。渲染器可用作 $container['view/renderer']。

模块组件

charcoal-view 的基本组件包括

视图，它为所有组件提供基本接口。
引擎，用于实际渲染模板。
加载器，用于加载 模板文件。
可视，允许任何对象通过一个视图进行渲染。
渲染器，一个额外的助手，用于使用视图渲染PSR-7请求/响应对象。

视图

Charcoal\View\ViewInterface定义了通过视图引擎渲染模板所需的所有内容。

render($templateIdent = null, $context = null)
renderTemplate($templateString, $context = null)

抽象类Charcoal\View\AbstractView完全实现了ViewInterface并添加了以下方法：

通用视图

为了方便起见，\Charcoal\View\GenericView类通过扩展AbstractView基类实现了完整的接口。

视图引擎

Charcoal 视图支持不同的模板引擎，这些引擎负责加载适当的模板（通过一个加载器），并根据其内部规则使用给定的上下文渲染模板。每个视图引擎都应该实现\Charcoal\View\EngineInterface。

默认提供了3个引擎：

mustache（默认）
php
twig

Mustache 助手

可以使用helpers扩展Mustache。这些助手可以通过在容器中扩展view/mustache/helpers来设置。

$container->extend('view/mustache/helpers', function(array $helpers, Container $container) {
    return array_merge($helpers, [
        'my_extended_method' => function($text, LambdaHelper $lambda) {
            if (isset($helper)) {
                $text = $helper->render($text);
            }
            return customMethod($text);
        }
    ]);
});

提供以下助手：

资源助手
- purgeJs
- addJs
- js
- addJsRequirement
- jsRequirements
- addCss
- purgeCss
- css
- addCssRequirement
- cssRequirements
- purgeAssets
翻译助手
- _t使用{{#_t}}要翻译的字符串{{/_t}}翻译字符串
Markdown助手
- markdown使用{{#markdown}}# 这是H1{{/markdown}}将Markdown解析为HTML

加载器

每个引擎都附加了一个Loader服务。它的功能是加载指定的模板内容。

模板

模板是简单的文件，存储在文件系统中，包含主要视图（通常是HTML代码+模板标签，但也可以是文本数据）。

对于mustache引擎，它们是.mustache文件。
对于php引擎，它们是.php文件。

模板通过模板加载器加载。加载器实现Charcoal\View\LoaderInterface并简单地尝试将一个标识符（作为参数传递给load()方法）与文件系统中的一个文件匹配。

调用$view->render($templateIdent, $context)将自动使用引擎的Loader对象来查找模板$templateIdent。

否则，调用$view->renderTemplate($templateString, $context)期望参数是已加载的模板字符串。

可观察接口和特质

通过使用Charcoal\View\ViewableTrait，任何对象都可以通过实现Charcoal\View\ViewableInterface来变得可渲染（可视）。

该接口为其实现对象添加了以下方法：

setTemplateIdent($ident)
templateIdent()
setView($view)
view()
render($templateIdent = null)
renderTemplate($templateString)

示例

给定以下类

use \Charcoal\View\ViewableInterface;
use \Charcoal\View\ViewableTrait;

class MyObject implements ViewableInterface
{
    use ViewableTrait;

    public function world()
    {
        return 'world!';
    }
}

以下代码

$obj = new MyObject();
$obj->renderTemplate('Hello {{world}}');

将输出："Hello world!"

视图服务提供商

如上所述的各个示例所示，建议使用ViewServiceProvider来设置各种依赖项，并根据一个config在一个Pimple容器上。

服务提供者向容器添加以下服务：

view 基础视图实例。
view/renderer 一个PSR-7视图渲染器。
view/parsedown 一个parsedown服务，用于将markdown渲染为HTML。

其他服务/选项包括：

view/config 视图配置选项。
view/engine 当前使用的视图引擎。
view/loader 当前使用的模板加载器。

ViewServiceProvider期望在容器上设置以下服务/键：

config 应用程序配置。应包含一个“view”键来构建ViewConfig对象。

视图配置

大多数服务选项可以从配置对象中动态设置（在$container['view/config']中可用）。

示例

{
    "base_path":"/",
    "view": {
        "engine":"mustache",
        "paths":[
            "templates",
            "views"
        ]
    }
}

开发

要安装开发环境

$ composer install --prefer-source

使用以下命令运行测试

$ composer test

API 文档

自动生成的 phpDocumentor API 文档可在以下链接查看：https://locomotivemtl.github.io/charcoal-view/docs/master/
自动生成的 apigen API 文档可在以下链接查看：https://codedoc.pub/locomotivemtl/charcoal-view/master/

开发依赖关系

phpunit/phpunit
squizlabs/php_codesniffer
satooshi/php-coveralls
pimple/pimple
mustache/mustache
twig/twig

持续集成

编码风格

Charcoal-View 模块遵循 Charcoal 编码风格

PSR-1
PSR-2
PSR-4，因此自动加载由 Composer 提供。
phpDocumentor 注释。
有关代码风格的详细信息，请阅读 phpcs.xml 文件。

可以使用 composer phpcs 执行编码风格验证/强制执行。还可以使用 composer phpcbf 提供的自动修复器。

作者

Mathieu Ducharme mat@locomotive.ca
Locomotive

许可证

Charcoal 基于 MIT 许可证。有关详细信息，请参阅 LICENSE。

locomotivemtl / charcoal-view

维护者

详细信息