README

View 包提供了与 Mustache 和 Twig 的集成，用于模板。

安装

composer require charcoal/view

对于 Charcoal 项目，可以从配置文件注册服务提供者

{
    "service_providers": {
        "charcoal/view/service-provider/view": {}
    }
}

用法

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

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;
use Slim\App;

$app = new App();
$container = $app->getContainer();
$container->register(new ViewServiceProvider());

$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'] 可用。

模块组件

View 包中的基本组件有

View，它为所有组件提供基本接口。
引擎，用于实际渲染模板。
加载器，用于加载模板文件。
可视化，允许任何对象通过 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 为 HTML，使用 {{#markdown}}# 这是 H1{{/markdown}}

Twig 辅助函数

Twig 可以通过 TwigExtension 扩展。这些辅助函数可以通过在容器中扩展 view/twig/helpers 来设置

$container['my/twig/helper'] = function (Container $container): MyTwigHelper {
    return new MyTwigHelper();
};

$container->extend('view/twig/helpers', function (array $helpers, Container $container): array {
    return array_merge(
        $helpers,
        $container['my/twig/helper']->toArray(),
    );
});

提供的辅助工具

调试辅助函数
- debug 函数 {{ debug() }}
- isDebug 函数是 debug 的别名

翻译辅助工具

trans 过滤器，使用 {{ "要翻译的字符串"|trans }}

transChoice 过滤器

    {{ '{0}First: %test%|{1}Second: %test%'|transChoice(0, {'%test%': 'this is a test'}) }}
    {# First: this is a test #}
    {{ '{0}First: %test%|{1}Second: %test%'|transChoice(1, {'%test%': 'this is a test'}) }}
    {# Second: this is a test #}

URL 辅助函数
- baseUrl 函数 {{ baseUrl() }}
- siteUrl 函数是 baseUrl 的别名
- withBaseUrl 函数 {{ withBaseUrl('/example/path') }}

加载器

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

模板

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

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

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

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

否则，调用 $view->renderTemplate($templateString, $context) 预期一个已经加载的模板字符串作为参数。

可渲染接口和特性

任何对象都可以通过实现 Charcoal\View\ViewableInterface 并使用 Charcoal\View\ViewableTrait 来使对象可渲染（可查看）。

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

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'] 中可用）动态设置。

Mustache 示例

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

Twig 示例

{
    "view": {
        "default_engine": "twig",
        "use_cache": false,
        "strict_variables": true,
        "paths": [
            "templates",
            "views"
        ]
    }
}

charcoal / view

维护者

详细信息