README

ServiceProvider，为KodiApp提供Twig（带有一些扩展）。

安装

$ composer require kodi-app/kodi-twig-provider

关于Twig

查看官方文档

支持的Twig版本：v2.4.*

我们使用原始的Twig_Environment进行渲染，因此你可以使用它提供的所有功能，但我们通过新的render()函数和内容提供者扩展了它，以使其更易于使用。

Twig（通过TwigServiceProvider）的初始化

一个连接的初始化

$application->run([
    // ...
    KodiConf::SERVICES => [
        // List of Services
        [
            "class_name" => TwigServiceProvider::class,
            "parameters" => [
                // [Mandatory] Absolute path to directory which contains the *.twig files
                Twig::TWIG_PATH             => PATH_BASE."/src/KodiTest/View",
                
                // [Optional] Relative path to page template
                Twig::PAGE_TEMPLATE_PATH    => "/frame/frame.twig",
                
                // [Optional] List of ContentProviders
                Twig::CONTENT_PROVIDERS     => [
                    [
                        "class_name" => PageTitleProvider::class,
                        "parameters" => [
                            "name"  => "page_title",
                            "title" => "Hello world!"
                        ]
                    ],
                    // ...
                ]
            ]
        ]
        // ...
    ],
    // ...
]);

Twig的使用

获取Twig实例

/** @var Twig $twig You can get Twig via Application singleton instance */
$twig = Application::get("twig")->getTwigEnvironment;

/** @var Twig_Environment $twig If you want to use the original Twig_Environment */
$twig = $twig->getTwigEnvironment();

关于我们的Twig扩展

在我们的扩展中，我们提供了另一种HTML内容渲染的概念（基于原始twig），以减少服务器和浏览器之间的通信开销。我们定义了一个所谓的page_template，它包含你页面的所有“静态”部分。例如，page_template可以包含页面标题、侧边栏、页脚、菜单等。

TODO：完成page_template的解释。

渲染函数

/**
 * Renders the html content to string based on parameter. If the HTTP request is an AJAX request it will render only the template
 * in other cases it renders also the page_template and puts the template content to the appropriate position of the page_template.
 *
 * If you want to prevent the usage of page_template you have to set the $forceRawTemplate parameter to true.
 *
 *
 * @param string $templateName Relative path to *.twig template file
 * @param array $parameters Parameters for twig template file
 * @param bool $forceRawTemplate Prevents the rendering of page template of it is true.
 * @param null $pageTemplate Relative path to a page_template file if you dont want to use the default one.
 * @return string
 * @throws HttpInternalServerErrorException When the pageTemplate does not exist.
 */
public function render($templateName, array $parameters = [], bool $forceRawTemplate = false,$pageTemplate = null) {
    // ...
}

在page_template twig文件中，你必须放置以下行。Twig将在此位置渲染你的模板。

    {% include app.content_template_name %}

内容提供者

你可以将所谓的ContentProvider附加到app变量上。您可以通过Twig::CONTENT_PROVIDERS配置设置定义使用的提供者列表。

使用示例：配置

Twig::CONTENT_PROVIDERS => [
    [
        "class_name" => PageTitleProvider::class,
        "parameters" => [
            "name"  => "page_title",
            "title" => "Hello world!"
        ]
    ],
    // ...
]

在twig中

<title>{{app.page_title}}</title>

请注意，你必须使用（配置中的）name参数来引用ContentProvider。

重要：在扩展中，app变量名是保留的，用于在twig文件中传递内容提供者！

如果你想创建自己的ContentProvider，你必须实现抽象ContentProvider类。

kodi-app / kodi-twig-provider

维护者

详细信息