README

欢迎使用MG Press，这是一个使用Timber插件以支持Twig模板文件的WordPress启动主题。它允许开发者在创建WordPress主题时使用MVC模式（尤其是视图-控制器），将业务逻辑与视图逻辑分开。

安装主题

像安装其他主题一样安装此主题，并确保Timber插件已激活。但是，让我们将其分解成一些要点

确保您已安装了Timber Library插件（以及高级自定义字段 - 它们配合得相当好）。
下载此主题的zip文件（或克隆它），并将其移动到WordPress安装中的wp-content/themes。
在“外观”>“主题”中激活主题。
做你的事情！并阅读文档。

这里有什么？

*.php是正常的WordPress PHP模板文件，对应于模板层次结构，如index.php和single.php。这些文件充当控制器：系统（WordPress）根据URL确定加载哪个文件；运行必要的业务逻辑；将任何数据添加到视图层的$context变量中；确定要渲染的视图；通过传递$context变量并将输出发送到浏览器来渲染视图。在每个PHP模板的末尾，您会注意到一个Timber::render()函数，其第一个参数是Twig文件，第二个参数是$context变量。

views/包含所有您的Twig模板。PHP模板文件确定要渲染哪个视图。

views/base.twig是基本模板，提供通用的HTML文档结构。此模板不应直接渲染内容。
views/layout/包含应用于页面结构布局的模板，但不通常直接渲染内容，如full-width.twig和left-sidebar.twig
views/detail/包含用于渲染单个帖子类型和页面的视图，如post.twig和page.twig。
views/list/包含用于渲染帖子类型列表的视图，如post.twig、category.twig和search.twig。
views/template/包含用于渲染自定义模板的视图，只需在文件头部的注释中添加“模板名称：某些自定义名称”，就像正常的WordPress自定义模板一样。
views/summary/包含用于帖子类型和页面摘要的模板包含，用于列表视图，如post.twig和page.twig。
views/block/包含用于渲染块级元素的模板包含。
views/menu/包含用于渲染菜单的模板包含。
views/form/包含用于渲染表单的模板包含。
views/include/包含用于渲染各种HTML片段的模板包含，如header.twig和pagination.twig。
views/exception/ 目录包含异常处理的视图，例如 404.twig。

assets/ 目录包含静态资源，如CSS、JavaScript、图片、字体、静态HTML等。

lib/ 目录存储MGPress功能的PHP库，如处理评论或资产管理。除非你了解自己在做什么，否则最好别动这些。

custom/ 目录包含本主题的定制PHP代码 - 它与WordPress默认的functions.php功能相同。此目录中的PHP文件将由functions.php文件自动加载。你还可以在此处覆盖lib/中的类。

controllers/ 目录包含自定义控制器，用于提供PHP模板文件可能不提供的附加业务逻辑。可以通过添加名为list-{post-type}.php、detail-{post-type}.php或list-taxonomy-{taxonomy-slug}.php的文件来提供文章类型列表和详情视图以及分类列表视图。一个示例用例是在列表视图中修改Timber\PostQuery以更改列表顺序或限制。

models/ 目录包含注册自定义文章类型的自动加载类。每个自定义文章类型应该有自己的类来注册文章类型以及任何相关的分类和可选的属性定义，尽管通常通过Advanced Custom Fields插件定义属性更简单。

lang/ 目录是.mo翻译文件的存储位置，由lib/site.php中的load_theme_textdomain()指定。（可选）

这是如何工作的？

如果你期待的是一个普通的WordPress主题，这可能会看起来有点奇怪——别担心，实际上这样与WordPress一起工作更简单。为什么？首先，它将业务逻辑与表示层分开。此外，你可以使用Twig。而且——你不必与The Loop一起工作。

示例1

在你的WordPress 设置 > 阅读部分，你将文章页面设置为/blog。当访客访问/blog时，WordPress使用其模板层次结构来加载archive.php文件。在archive.php文件中是逻辑，它创建从views/list/目录的优先级列表的Twig模板，以尝试根据归档类型加载。在这种情况下，它是一个基本的博客列表页面，所以views/list/post.twig具有最高的优先级。

事实上，views/list/post.twig存在，因此Timber将数据（$context）传递给模板并渲染它。views/list/post.twig模板定义了content块，它包含包含遍历posts变量（来自$context）并渲染从views/summary/post.twig的总结模板包含的表示逻辑。此外，views/list/post.twig模板还扩展了views/layout/full-width.twig模板。

views/layout/full-width.twig模板应用页面布局的结构标记，显示content块，定义layout块，并扩展了views/base.twig模板。views/base.twig模板应用基本HTML文档结构，例如<html>和<body>标签，包含views/include/header.twig和views/include/footer.twig片段，并显示layout块。由于views/base.twig没有扩展任何模板，渲染完成并将输出发送到浏览器。

示例2

您的网站在路径 /products 下有一个名为产品的自定义文章类型。当访客访问 /products/product-1 的单个产品页面时，WordPress 使用模板层次结构来加载 single.php 文件。该文件从 views/detail/ 目录创建一个优先级列表，尝试加载Twig模板。列表中的第一个模板遵循格式 "{POST-TYPE}-{SLUG}.twig"，因此它变成 views/detail/product-product-1.twig。此模板不存在，因此它尝试下一个模板，views/detail/product.twig。这个模板存在，所以 single.php 将数据（$context）传递给模板并渲染视图。

views/detail/product.twig 显示产品1的内容，并扩展了 views/layout/left-sidebar.twig 模板。views/layout/left-sidebar.twig 模板应用页面布局的结构标记 - 包括在左侧列中渲染动态侧边栏 - 并扩展了 views/base.twig 模板，后者反过来提供HTML文档结构标记、页眉和页脚等，这些内容随后发送到浏览器。

视图层次结构

在选择要渲染的Twig模板时，系统密切遵循默认的 WordPress模板层次结构，并进行了一些修改

归档页面
- 作者归档
  - views/list/author-{nicename}.twig
  - views/list/author-{id}.twig
  - views/list/author.twig
  - views/list/archive.twig
  - views/list/post.twig
  - views/list/single.twig
  - views/index.twig
- 分类归档
  - views/list/category-{slug}.twig
  - views/list/category-{id}.twig
  - views/list/category.twig
  - views/list/archive.twig
  - views/list/post.twig
  - views/list/single.twig
  - views/index.twig
- 自定义文章类型归档
  - views/list/{post-type}.twig
  - views/list/archive.twig
  - views/list/post.twig
  - views/list/single.twig
  - views/index.twig
- 分类法归档
  - views/list/taxonomy-{slug}-{term}.twig
  - views/list/taxonomy-{slug}.twig
  - views/list/taxonomy.twig
  - views/list/archive.twig
  - views/list/post.twig
  - views/list/single.twig
  - views/index.twig
- 日期归档
  - views/list/date.twig
  - views/list/archive.twig
  - views/list/post.twig
  - views/list/single.twig
  - views/index.twig
- 标签归档
  - views/list/tag-{slug}.twig
  - views/list/tag-{id}.twig
  - views/list/tag.twig
  - views/list/archive.twig
  - views/list/post.twig
  - views/list/single.twig
  - views/index.twig
单页
- 附件文章
  - views/detail/{mimetype}-{subtype}.twig
  - views/detail/{subtype}.twig
  - views/detail/{mimetype}.twig
  - views/detail/attachment.twig
  - views/detail/post.twig
  - views/detail/single.twig
  - views/index.twig
- 自定义文章
  - views/detail/{posttype}-{slug}.twig
  - views/detail/{posttype}.twig
  - views/detail/post.twig
  - views/detail/single.twig
  - views/index.twig
- 博客文章
  - views/detail/post-{slug}.twig
  - views/detail/post.twig
  - views/detail/single.twig
  - views/index.twig
- 静态页面
  - views/template/{templatename}.twig
  - views/detail/page-{slug}.twig
  - views/detail/page-{id}.twig
  - views/detail/page.twig
  - views/index.twig
- 网站首页
  - 显示在首页的页面
    - views/detail/front-page.twig
    - views/template/{templatename}.twig
    - views/detail/page-{slug}.twig
    - views/detail/page-{id}.twig
    - views/detail/page.twig
    - views/index.twig
  - 显示在首页的文章
    - views/list/home.twig
    - views/list/post.twig
    - views/list/single.twig
    - views/index.twig
404错误页面
- views/exception/404.twig
- views/index.twig
搜索结果页面
- views/list/search.twig
- views/list/post.twig
- views/list/single.twig
- views/index.twig

自定义Twig扩展

除了标准的 Twig API 之外，以下自定义功能可以在模板中使用。

函数

资产管理

`add_stylesheet()`

将样式表添加到HTML输出。

* @param string  $handle        (required) A unique string ID to ensure the resource is loaded only once.
* @param string  $src           (required) The public path to the resource.
* @param array   $deps          Array of handles of any stylesheets that this stylesheet depends on.
* @param string  $ver           String specifying the stylesheet version number, if it has one.
* @param string  $media         String specifying the media for which this stylesheet has been defined. [Ex: 'all', 'screen', 'handheld', 'print']
* @param bool    $http2         True: load resource immediately in HTML; False: register resource with WordPress to load in the header or footer. Default is False.
* @param bool    $inline        True: print the contents of the file directly in HTML; False: load the file as an external resource. Default is False.
* @param array   $environments  Array of environments to restrict resource loading to, default is to load in all environments. ['dev', 'test', 'prod']
* @param string  $group         A group ID to aid resource grouping; assets can share groups.
* @param int     $priority      A priority weight given to the resource used during sorting when registered with WordPress: higher numbers will load sooner. Default is 0, loading by FIFO.
* @return null

`add_style()`

将样式添加到HTML输出。

* @param string  $handle        (required) A unique string ID to ensure the resource is loaded only once.
* @param string  $src           (required) String of CSS styles to output. [Ex: "p { color: #ff0000; }"]
* @param string  $media         String specifying the media for which this stylesheet has been defined. [Ex: 'all', 'screen', 'handheld', 'print']
* @param bool    $http2         True: print styles immediately in HTML; False: register styles with WordPress to load in the header or footer. Default is False.
* @param array   $environments  Array of environments to restrict style output to, default is to output in all environments. ['dev', 'test', 'prod']
* @param int     $priority      A priority weight given to the resource used during sorting when registered with WordPress: higher numbers will load sooner. Default is 0, loading by FIFO.
* @return null

`add_script_file()`

将脚本文件添加到HTML输出。

* @param string  $handle        (required) A unique string ID to ensure the resource is loaded only once.
* @param string  $src           (required) The public path to the resource.
* @param array   $deps          An array of registered script handles this script depends on.
* @param string  $ver           String specifying script version number, if it has one, which is added to the URL as a query string for cache busting purposes.
* @param bool    $http2         True: load resource immediately in HTML; False: register resource with WordPress to load in the header or footer. Default is False.
* @param bool    $inline        True: print the contents of the file directly in HTML; False: load the file as an external resource. Default is False.
* @param array   $environments  Array of environments to restrict resource loading to, default is to load in all environments. ['dev', 'test', 'prod']
* @param string  $group         A group ID to aid resource grouping; assets can share groups.
* @param int     $priority      A priority weight given to the resource used during sorting when registered with WordPress: higher numbers will load sooner. Default is 0, loading by FIFO.
* @return null

`add_script()`

将脚本添加到HTML输出。

* @param string  $handle        (required) A unique string ID to ensure the script is output only once.
* @param string  $src           (required) String of JavaScript to output. [Ex: "var foo = 'bar';"]
* @param bool    $http2         True: print script immediately in HTML; False: register script with WordPress to load in the header or footer. Default is False.
* @param array   $environments  Array of environments to restrict script output to, default is to output in all environments. ['dev', 'test', 'prod']
* @param int     $priority      A priority weight given to the resource used during sorting when registered with WordPress: higher numbers will load sooner. Default is 0, loading by FIFO.
* @return null

`localize_script()`

本地化脚本。

* @param string  $handle  (required) The registered script handle you are attaching the data for.
* @param string  $name    (required) The name of the variable which will contain the data.
* @param array   $data    (required) The data itself.
* @return null

`can_comment()`

检查用户是否可以评论文章或评论。

* @param \Timber\Post     $post     (required) The post to check if comments are allowed.
* @param \Timber\Comment  $comment  If using nested comments, the comment to check if comments are allowed.
* @return bool

`get_comments()`

从文章获取子评论列表。

* @param Timber\Post  $post  (required) The post to return comments for.
* @return array Timber\Comment

`next_comments_link()`

创建下一页评论的链接。

* @param \Timber\Post  $post   (required) The parent post of comments to paginate.
* @param string        $label  A label to use as the link anchor text.
* @return bool|string

`previous_comments_link()`

创建上一页评论的链接。

* @param \Timber\Post  $post   (required) The parent post of comments to paginate.
* @param string        $label  A label to use as the link anchor text.
* @return bool|string

过滤器

目前没有额外的自定义过滤器。

其他资源

Timber的主要Wiki 非常出色，因此经常参考。此外，查看以下文章和项目以获取更多信息。

此分支的入门主题包含一些带有ACF的示例代码和一些不同的设置。
Timber的Twig速查表
Timber 和 Twig 重燃了我对 WordPress 的热爱在 CSS-Tricks 上
一个真正的实时 Timber 主题.
Timber 视频教程以及一系列不完整的屏幕录制教程，用于从头开始构建 Timber 主题。

mindgruve / mg-press

维护者

详细信息