devgeniem/dustpress

WordPress 主题框架。

维护者

详细信息

github.com/devgeniem/dustpress

源代码

问题

安装次数: 76,341

依赖项: 15

建议者: 0

安全性: 0

星标: 53

关注者: 32

分支: 22

开放问题: 28

1.36.5 2023-03-08 12:09 UTC

Requires

Conflicts

GPL-3.0 5be360b6dae915d2483f83aad78c4641f817316a

frameworkjavascriptthemewordpressdustjsdustpress

This package is auto-updated.

Last update: 2024-09-08 16:15:50 UTC

README

geniem-github-banner

DustPress

目录

描述

Dust.js 模板引擎和数据模型分离的 WordPress 主题框架。

安装

我们建议您使用 Composer 安装 DustPress，但也可以手动进行。

Composer

使用 Composer 安装

$ composer require devgeniem/dustpress

或将它添加到您的 composer.json

{
  "require": {
    "devgeniem/dustpress": "*"
  }
}

DustPress 支持Composer的自动加载功能。如果您已启用，则无需执行其他操作即可使用 DustPress。如果没有，您需要在 functions.php 中引入 dustpress.php。

手动

  • 将此存储库克隆到项目的某个位置，并在 functions.php 中引入 dustpress.php 文件。

外部资源

还有其他几个存储库包含 DustPress 材料

使用

您需要在 functions.php 中调用 dustpress(); 来启用 DustPress。如果您没有使用 Composer 的自动加载功能，则必须自然地在引入库之后进行此操作。

要在主题中使用 DustPress，必须在主题中存在两个名为 models 和 partials 的目录。它们的作用将在本文件后面的部分进行解释。

使用 DustPress 的基本方法非常简单。与传统的 WordPress 主题开发不同，DustPress 依赖于 MVVM 架构，其中获取数据和向用户显示数据被分为不同的模块。

文件命名和位置

数据模型

尽管 DustPress 对 WordPress 主题开发者来说是一个几乎全新的开发模式，但它仍然使用了一些 WordPress 核心功能。数据模型和视图部分的命名遵循传统 WordPress 主题的命名约定。单个帖子的模型应命名为 single.php 等。

在 WordPress 中，您的自定义页面模板可以命名为任何名称，只要您在文件开头注释中声明模板的名称即可。这在 DustPress 中也是如此，但是您为模型编写的类名应遵循一定模式。例如，如果您有一个名为 Frontpage 的模板，其文件名为 page-frontpage.php，则您的类名应为 PageFrontpage。类名是区分大小写的。这同样适用于自定义内容类型单例，其中单个 person 文件应命名为 single-person.php，相应的类名为 SinglePerson。

您仍然需要在起始注释中声明模板的名称，就像在传统 WordPress 主题中做的那样。这允许用户选择用于页面的模板文件，并指示 DustPress 核心在加载页面时加载正确的模型。

模型必须位于 models 目录中。然而，它们可以组织在任何类型的子目录树中，因此请随意保持您喜欢的结构。请注意，WordPress 也需要找到您的模板文件才能使其正常工作。

视图

Dust 模板是我们设计模式中的视图。DustPress 使用 Geniem 的 DustPHP 库的分支来解析 Dust 模板。

您的模型公共函数收集和返回的所有数据都自动传递到视图中。DustPress 在主题根目录下的 partials 目录中查找 Dust 模板。就像模型一样，它们可以组织在任何类型的子目录层次结构中，因此请随意使用您需要的任何结构。

默认情况下，Dust 模板文件的命名遵循模型的命名。single.php 应与 single.dust 配对。这种命名约定可以在您的模型中通过调用 set_template() 函数来覆盖。在模型的任何公共函数中写入 $this->set_template("partial_name")，它将使用默认模板。不需要 .dust 文件扩展名。

数据模型

DustPress 的数据模型由与文件同名但使用驼峰命名法的类组成。page-frontpage.php 应具有名为 PageFrontpage 的类，它扩展了 \DustPress\Model 类

<?php
/*
Template name: Frontpage
*/

class PageFrontpage extends \DustPress\Model {
  //
}
?>

自动构建和模块化使用

如上所述，DustPress 自动定位主模型，遵循 WordPress 主题的命名约定和结构。主模型自动加载和构建。在 Model 类的 __construct 方法中发生了很多幕后的事情。请勿在没有在构造函数开头调用 parent::__construct(); 的情况下覆盖它。

除了自动加载之外，您还可以在任何您能想到的模块化用例中使用DustPress模型。一个例子是在名为api.php的文件中构建一个自定义API，该文件包含一个扩展类Model的名为API类（由于该类不是自动构建的，因此不需要遵循命名约定），运行各种公共函数并渲染多个自定义模板。是的，有了DustPress，您可以在WordPress项目中任何地方进行Dust渲染！（查看示例）（用DustPressJS增强您的API）

绑定数据

DustPress有一个自己的全局数据对象，当所有操作完成并需要渲染页面时，它会传递给视图。通过公开访问函数中的return语句将数据绑定到对象。在自动加载主模型及其子模型时，所有公共函数将自动运行。如果您想在函数中加载数据但不想将其包含到全局数据对象中，将函数的可视性设置为private或protected。

public function last_posts() {
    $args = [ 'posts_per_page' => 3 ];
    return get_posts( $args );
}

DustPress数据对象包含多种用户定义模型的其他对象。例如，如果您有一个包含页眉、内容块、侧边栏和页脚的前页，数据对象看起来像这样

object(stdClass)#1 (5) {
  ["PageFrontpage"]=>
  object(stdClass)#2 (0) {
  }
  ["Header"]=>
  object(stdClass)#2 (0) {
  }
  ["Sidebar"]=>
  object(stdClass)#2 (0) {
  }
  ["Footer"]=>
  object(stdClass)#2 (0) {
  }
}

子模型

应将重复出现的元素（如页眉或页脚）作为子模型创建，以便可以将其包含在任何页面中。子模型有自己的模型，它们位于models目录中自己的文件中。它们通过前面提到的bind_sub()方法附加到主模型。前页模型可能如下所示

<?php
/*
Template name: Frontpage
*/

class PageFrontpage extends \DustPress\Model {

  public function init() {
    $this->bind_sub("Header");
    $this->bind_sub("Sidebar");
    $this->bind_sub("Footer");
  }
}
?>

此代码检索所有三个模型并将它们的数据绑定到全局数据层次结构中的相应对象。请注意，我们已经创建了一个公共函数init，DustPress会自动运行，因此子模型将被包含。由于我们的函数中没有返回任何内容，因此数据树中不会创建init块。

子模型绑定可以在模型的任何地方运行，例如在if语句中。子模型是递归的，因此子模型可以绑定更多的子模型。

bind_sub()还可以接受一个第二参数，即传递给子模型的参数数组。然后在子模型中全局访问它，通过调用$this->get_args()。

绑定数据

数据实际上传递到方法内部是通过用户定义的函数完成的。DustPress会遍历模型中的所有公共方法，并将它们的返回数据放置在全局数据对象中当前模型的树分支下。它以方法名称命名的对象中。

public function SomeData() {
  return "This is data.";
}

如果此代码位于我们的PageFrontpage类中，数据对象中的结果如下

object(stdClass)#1 (5) {
  ["PageFrontpage"]=>
    array(1) {
      ["SomeData"]=>
      string(13) "This is data."
    }
  }
  ["Header"]=>
  object(stdClass)#2 (0) {
  }
  ["Sidebar"]=>
  object(stdClass)#2 (0) {
  }
  ["Footer"]=>
  object(stdClass)#2 (0) {
  }
}

模型类中还有一个名为bind的函数。如果您想在单个方法中绑定多个数据块，可以这样使用它

public function SomeMethod() {
  $data = "This is another piece of data.";

  $this->bind( $data, "SomethingElse" );
}

结果如下

object(stdClass)#1 (5) {
  ["PageFrontpage"]=>
    array(1) {
      ["SomethingElse"]=>
      string(13) "This is another piece of data."
    }
  }
  ["Header"]=>
  object(stdClass)#2 (0) {
  }
  ["Sidebar"]=>
  object(stdClass)#2 (0) {
  }
  ["Footer"]=>
  object(stdClass)#2 (0) {
  }
}

bind还可以接受第三个参数来创建新的主数据块

public function SomeMethod() {
  $data = "This is yet another piece of data.";

  $this->bind( $data, "Method", "PrimaryBlock" );
}

结果如下

object(stdClass)#1 (5) {
  ["PageFrontpage"]=>
  object(stdClass)#2 (0) {
  }
  ["PrimaryBlock"] =>
  array(1) {
    ["SomethingElse"]=>
    string(13) "This is yet another piece of data."
  }
  ["Header"]=>
  object(stdClass)#2 (0) {
  }
  ["Sidebar"]=>
  object(stdClass)#2 (0) {
  }
  ["Footer"]=>
  object(stdClass)#2 (0) {
  }
}

保留的模型名称

WP

WP保留用于始终在所有模板中可访问的WordPress基本数据。它存储在数据对象的根目录中，键为WP，包含WordPress原生get_bloginfo()会返回的所有字段。

它还包含关于当前用户的信息在WP->user中，以及用户是否登录的布尔值WP->loggedin。

wp_head()和wp_footer()函数的内容可用于分别在助手wphead和wpfooter中。它们应在模板文件中的相应位置插入。

{@wphead /}

缓存

方法缓存

DustPress原生支持WordPress瞬态缓存。它在方法级别工作，因此您可以为不同的方法提供不同的TTL，它们将自动缓存。

默认情况下，方法缓存是禁用的。可以通过在functions.php中的过滤器启用它，如下所示

add_filter( "dustpress/settings/cache", "__return_true" );

然而，这个设置本身并不能做什么。您还必须定义您想要缓存的方法的TTL。TTL是“生存时间”的缩写。它定义了方法缓存存活的时间，在它需要更新之前，即它的代码再次运行之前。

这些TTL在一个名为$ttl的公共属性的关联数组中设置，如下所示：

class Model extends \DustPress\Model {
  public $ttl = [
    "Method" => 60
  ];

  public function Method() {
    // something

    return $data;
  }
}

在示例中，返回的数据Method被缓存60秒。缓存也适用于DustPress.js请求。

部分和最终结果缓存

DustPress还使用WordPress对象缓存来缓存其部分和最终的HTML缓存。与方法缓存不同，这些功能默认启用，如果您不想使用它们，则必须禁用它们。

部分缓存

部分缓存缓存了Dust模板的编译版本，这样在页面加载时就不需要从头开始编译，因为这在大型操作中是一个相对繁重的操作。

部分缓存是永久的，这意味着每次您更改它们时，您可能希望运行wp_cache_flush()或相应的WP CLI命令，以便它们得到更新。

您可能希望在您的开发环境中完全关闭缓存。这意外地通过以下过滤器实现：

add_filter( "dustpress/cache/partials", "__return_false" );

您还可以仅针对某些部分关闭部分缓存

add_filter( "dustpress/cache/partials/partial_name", "__return_false" );

最终结果缓存

DustPress还缓存了提供给最终用户的最终HTML。它使用用于渲染HTML的数据和部分生成缓存键，因此每当数据更改时，缓存都会更新。它仅用于节省DustPHP使用数据渲染模板的时间。对于更复杂的模板，操作可能需要时间，因此建议在生产环境中至少保持缓存开启。

您可以通过与部分缓存相同的方式关闭最终结果缓存

add_filter( "dustpress/cache/rendered", "__return_false" );

注意！当启用时，DustPress调试器会关闭部分和最终结果缓存。

菜单缓存

菜单助手使用WP对象缓存来缓存每个菜单加载的菜单项。菜单ID（更具体地说，菜单的术语ID）用于构建缓存键。不使用缓存组。菜单助手还处理在菜单更新时自动删除缓存。要启用持久缓存，您必须安装第三方插件，例如Redis对象缓存WordPress。

配置常量

您可以定义以下PHP常量来控制菜单助手缓存：

  • DUSTPRESS_MENU_HELPER_CACHE_EXPIRE : int：菜单项缓存过期时间（以秒为单位）。如果未设置此常量，则使用默认值15分钟（900）。
  • DUSTPRESS_MENU_HELPER_CACHE_DISABLE : bool：如果您想禁用缓存，请将其设置为true。默认情况下启用缓存。

Dust 模板

DustPHP模板与Dust.js模板100%兼容。有关文档，请参阅官方Dust.js网站或LinkedIn Dust教程。

所有模板都应该有一个以当前模型名称命名的上下文块，以便变量可以在模板中使用。就我们之前的示例模型而言，非常简化的模板可能看起来像这样

{>"shared/header" /}

{#PageFrontpage}
  <h1>{WP.name}</h1>
  <h2>{WP.description}</h2>

  <p>{SomeString}</p>

  {SomeHTML|s}

  {">shared/sidebar" /}
{/PageFrontpage}

{>"shared/footer" /}

此模板包括从子目录 partials/shared/ 中的 header.dust、sidebar.dust 和 footer.dust 模板。在 PageFrontpage 块的末尾，我们回显 SomeHTML 变量的 HTML 并使用 s 过滤器来获取它 未转义 的形式。有关部分和上下文的信息，请参阅 Dust 教程。

DustPress 辅助工具

辅助函数扩展了 Dust.js 模板语言的功能，而不仅仅是数据插入（参见：上下文辅助函数，Dust 辅助函数）。使用 DustPress，您可以在 Dust 模板中使用所有 Dust.js 辅助函数。我们还进一步扩展了它，包括了一些您可以使用的好东西。如上所述，有用于将头部和尾部数据回显到模板中的辅助函数，但以下是 DustPress 包含的辅助函数的完整列表

contains

contains 是一个条件辅助函数。它可以用来确定数组是否包含所需的项目，所以它的工作方式类似于 PHP 的 in_array。它还可以有 else 条件。

示例

{@contains key=haystack value="needle"}
  Found it! :)
{:else}
  Didn't find it. :(
{/contains}

content

content 辅助函数有两个功能。如果没有参数运行，它模拟了 WordPress 本地 the_content() 函数的使用，并显示当前帖子的内容。

它也可以传递一个参数 data（{@content data=string /}）。然后它的行为就像运行了 apply_filters( 'the_content', $string )。

示例

{@content data=fields.some_content.value /}

image

image 辅助函数返回具有正确 srcset 和 sizes 属性的 img 标记的标记，以支持响应式使用。该辅助函数的完整说明可以在此处找到：这里。

menu

menu 辅助函数按照其名称所暗示的创建菜单。它有几个参数，下面将进行说明

  • menu_id / menu_name：定义要显示的菜单。两个参数中必须有一个是必需的。
  • depth：只显示到该参数定义的级别的子菜单。默认为无限（或 PHP_INT_MAX）。
  • parent：如果定义了父参数，菜单只显示具有参数值的 ID 的帖子的子页面。默认为 0 - 显示所有项目。
  • override：使用此参数可以覆盖作为活动菜单项（WordPress 默认的 current-menu-item 类）显示的菜单项（帖子 ID）。默认为当前帖子的 ID。
  • ul_classes：将类赋予 ul 元素，用空格分隔。默认为空。
  • ul_id：赋予 ul 元素的 ID。默认为空。
  • show_submenu：一个布尔值，表示是否显示子菜单。默认为 true。
  • menu_partial：使用另一个部分代替默认的 menu.dust。您可以通过在主题中创建自己的 menu.dust 来使用自定义部分，并且 DustPress 将使用该部分而不是其核心中的部分。
  • menuitem_partial：使用另一个部分代替默认的 menuitem.dust。您可以通过在主题中创建自己的 menuitem.dust 来使用自定义部分，并且 DustPress 将使用该部分而不是其核心中的部分。
  • data：传递给菜单模板的自定义数据对象。可以在 menu.dust 或 menuitem.dust 中的 {data} 下使用。

示例

{@menu menu_name="main-menu" ul_id="main-menu" ul_classes="menu primary-menu" show_submenu=false /}

pagination

pagination 辅助函数在模板中打印出基本的分页。它将模型的数据作为参数，根据 per_page 值计算页数。然后它打印出包含页面链接的 ul 元素，对应页作为查询参数。该辅助函数接受以下参数

  • page：当前活动页面。默认为 1。
  • per_page：单页应包含的项目数量。
  • items：数据集中的项目数量。例如，这可以是帖子计数。
  • page_var：分页链接的查询参数。默认为 paged。
  • hash：要添加到分页链接末尾的哈希链接。
  • neighbours：在当前页两侧显示的页面编号数量。默认为 3。
  • strings：要翻译和操作导航链接中的文本的字符串数组。传递以下具有翻译值的数组键
    • 上一页
    • 下一页
    • 开始
    • 结束

示例

{@pagination page=current_page per_page=10 items=item_count page_var="paged" hash="posts-section-id" /}

页面链接格式化

助手默认的分页链接格式为：{page_link}{last_page}{hash}。在没有自定义 WordPress URL 处理的情况下，链接将输出为 https://domain.com/something/?paged=2。要更改链接格式，请使用 dustpress/pagination/page_link 过滤器过滤 page_link 值，并在您的主题中将 pagination.dust 替换为您自定义的模板。

格式化示例
/**
 * Change the pagination link format from '?paged=' to 'page/'.
 * This works only on pages with no other GET parameters.
 */
custom_pagination_link( $page_link ) {
    return str_replace( '?paged=', 'page/', $page_link );
}
add_filter( 'dustpress/pagination/page_link', 'custom_pagination_link' );

password

password 实现了 WordPress 的原生密码保护功能。它接受一个参数 id，告诉它需要要求哪个帖子的密码。默认为当前帖子的 id。

将您的受密码保护的内容放在 password 上下文中，直到给出正确的密码，它将替换为密码表单。

示例

{@password}
  <p>This content is password protected.</p>
{/password}

与原生的 WordPress 不同，其中可以通过过滤器更改表单布局，您可以使用自己的 Dust 模板来覆盖它。默认模板可以在 DustPress 核心中的 partials/ 目录下找到。将其复制到您的主题的 partials/ 目录下的某个位置，并对其进行所需的修改。

permalink

permalink 助手模拟了 WordPress 的原生 get_permalink() 函数。它接受一个参数 id，告诉它提供哪个帖子的永久链接。默认为当前帖子的 id。

示例

{@permalink id=featured_post.ID /}

s

s 助手模拟了 WordPress 的原生 __ 或 _x 函数，并用于国际化。它接受一到三个参数：s 是要翻译的字符串，这是唯一必需的参数。td 是文本域，x 是提供翻译的上下文。

请注意，使用 s 助手不会使字符串可用于例如 WPML 的字符串扫描功能。

示例

{@s s="Home page" td="my-page" /}

您可以使用 翻译解析脚本 来查找所有使用 {@s} 定义的字符串，并将它们写入一个可以由 POedit 扫描的格式的文件。

sep

sep 助手是 Dust 的原生 sep 助手的扩展。它的行为相同，但它也可以给出两个额外的参数：start 和 end。它们作为函数的偏移量。默认情况下，start 为 0，end 为 1。

示例

The participants are {#names}{@last}and {/last}{.}{@sep start=0 end=2}, {/sep}{/names}

结果可能是

The participants are Bob, Samantha, Michael and Alice.

set and unset

set 助手可用于设置和修改 Dust 模板中的数据树。您可以创建自己的变量并将值赋给它，无论是硬编码的还是从数据中获取的。您还可以在它们上执行多个数学运算。

参数

  • key：此参数是必需的。它是您想要创建或修改的变量的名称。
  • value：如果您想要创建新变量或覆盖另一个变量的值，请在此处提供您想要赋予它的值。
  • add：用于对变量的值执行数学 加 操作。
  • subtract：用于对变量的值执行数学 减 操作。
  • multiply：用于对变量的值执行数学 乘 操作。
  • divide：用于对变量的值执行数学 除 操作。
  • mod：用于对变量的值执行数学 取模 操作。

示例

{@set key="my_variable" value="some_value" /}
{@set key="another_variable" value=path.to.data /}
{@set key="saved_index" value=$idx /}
{@set key="counter" add=1 /}

unset 用于取消变量。用法

{@unset key="my_variable" /}

strtodate

strtodate 将给定的日期格式化为指定的格式。它接受三个参数：value、format 和 now。该函数模拟 PHP 代码的行为：date( $format, strtotime( $value, $now ) )。

如果没有提供格式参数，将使用网站默认的日期格式（get_option( 'date_format' )）。

示例

{@strtodate value=post_date format="d.m.Y H:i:s" /}

title

标题 作为 WordPress 的原生 the_title() 函数的代理。

示例

{@title /}

wpfooter

wpfooter 作为 WordPress 的原生 wpfooter() 函数的代理。

示例

{@wpfooter /}

wphead

wphead 作为 WordPress 的原生 wphead() 函数的代理。

示例

{@wphead /}

转义过滤器

  • kses
    • 使用 WordPress 函数 wp_kses_post()
  • attr
    • 使用 WordPress 函数 esc_attr()
  • html
    • 使用 WordPress 函数 esc_html()
  • url
    • 使用 WordPress 函数 esc_url()

示例用法

<a href="{permalink|url}">Link text</a>

添加自定义过滤器

  • 您可以通过 dustpress/filters 过滤器添加自定义过滤器。

其他功能

do_not_render

如果您不希望 DustPress 自动渲染页面，而是想自行完成，可以在模型或子模型的任何地方调用 $this->do_not_render()。在这种情况下，DustPress 会填充数据对象，但渲染工作留给了开发者。

DustPress 的渲染函数被声明为公共的，因此可以在任何地方使用。它接受一个参数数组。唯一的必填参数是 partial，它包含所需部分的名字、文件名或路径。

仅定义了部分的情况下，DustPress 将其全局数据对象传递给模板。可以通过提供另一个参数 data 来改变这一点，这样它就会被传递到模板中。

还有一个参数 type，它定义了数据将被渲染的格式。默认为 html，但也可以是 json。您还可以编写自己的渲染格式函数。该功能将在稍后进行文档说明，对此表示歉意。

参数列表中最后一个但同样重要的是 echo，它接受布尔值。默认情况下设置为 true，因此渲染函数将输出直接输出到浏览器。如果为 false，则返回为字符串。以下是一个渲染函数的示例用法：

在某个函数中

$output = dustpress()->render( [
  "partial"   => 'my_custom_template',
  "data"    => [
      'some_number' => 1,
      'some_string' => 'ABC',
  ],
  "type"    => "html",
  "echo"    => false
]);

echo $output;

my_custom_template.dust

<ul>
    <li>My number: {some_number}</li>
    <li>My string: {some_string}</li>
</ul>

输出的内容

<ul>
    <li>My number: 1</li>
    <li>My string: ABC</li>
<ul>

json 输出

DustPress 可以输出 JSON 格式的数据而不是渲染版本，如果开发者启用了该功能。这通过将以下一个或两个过滤器添加到您的 functions.php 文件中实现：

add_filter( 'dustpress/settings/json_url', '__return_true' );

add_filter( 'dustpress/settings/json_headers', '__return_true' );

前者在 URL 中添加查询参数 ?JSON 时启用 JSON 输出，后者在请求中存在 HTTP 头 Accept: application/json 时启用。

自定义路由

使用 DustPress，您可以轻松定义自定义路由，以便在 WordPress 帖子上下文之外使用。如果您有一个需要显示的自定义页面，但不想为它创建管理页面，自定义路由就是您要走的路。

dustpress()->register_custom_route( 'custom/route', 'MyModel' );

上面的代码注册了 custom/route URL 以映射到 MyModel。DustPress 会自动将 URL 中的所有参数作为参数传递给模型，因此例如 URL custom/route/custom_parameter/1 仍然使用 MyModel 模型，参数可以通过 $this->get_args() 获取，供开发者使用。

路由应该在运行 init 钩子之前定义，因此只需在 functions.php 范围内直接注册它们即可。

注意！ 请记住在 functions.php 中注册后刷新 WordPress 重写。您可以在代码中执行此操作，使用 WP CLI 或只是访问管理员中的“永久链接”选项卡。

额外类

\DustPress\Query

\DustPress\Query 是一个包含一些常见 WordPress 任务辅助函数的类。这个类的主要功能是自定义帖子查询，能够将基本 WordPress 元数据绑定到查询的帖子对象上。通过单个函数调用，您可以获取 Dust 模板中所需的所有元数据。它还支持对帖子对象中 高级自定义字段 (ACF) 字段组数据的自定义数据获取。

查询单个帖子

get_post()

使用 \DustPress\Query，您可以通过两个不同的函数查询单个 WordPress 帖子。函数 get_post() 接受以下参数

  • id：帖子的 id。
  • args：数组中的参数。

参数键 meta_keys 用于查询 postmeta。默认值为 'null'，默认情况下不加载任何 postmeta。将值设置为 'all' 以获取所有 postmeta 行。您可以通过传递一个与 postmeta 中键对应的字符串数组来查询单个元数据键。

参数键 'single' 在 WordPress 文档 中描述了 get_metadata()，它定义了找到的元数据行的返回类型。Postmeta 通过键 meta 追加到查询的帖子对象中。找到的元数据以关联数组返回，其中找到的元数据值按元数据键映射。元数据是函数返回值下的键 meta。

所需的返回类型可以类似于 WordPress 的 get_post 函数定义。使用 output 参数键设置之一 'OBJECT'、'ARRAY_A' 或 'ARRAY_N'，分别对应于 WP_Post 对象、关联数组或数字数组。如果没有找到与传入 id 匹配的帖子，则返回 false。

$args = [
  'meta_keys' => [
    'my_meta_key_1',
    'my_meta_key_2'
  ],
  'single' => true
];
\DustPress\Query::get_post( get_the_ID(), $args );

返回的 WordPress 帖子对象 通过以下键扩展

  • permalink - 帖子的永久链接。
  • image_id - 如果为帖子设置了特色图像，则这是其 id。

get_acf_post()

此函数通过 ACF 函数 get_fields 自动加载 ACF 字段组数据。字段通过 ACF 函数加载，并在帖子对象下的键 fields 中返回。此函数接受与 get_post() 函数相同的参数，还包括参数键 whole_fields。将此参数设置为 true 时，此函数返回字段组数据，如字段组编辑屏幕中所见。

此函数具有递归操作。如果使用整数值设置带有键 max_recursion_level 的参数，则会递归地加载具有关联帖子对象数据的 ACF 字段，包括完整的元数据和字段组数据。级别指示加载为包括 ACF 字段的完整帖子对象的关联文章级别。此递归也适用于 ACF 重复器字段的第一个级别。

请谨慎使用递归。大于 1 的级别可能会增加页面加载时间。

$args = [
  'meta_keys' => null,
  'single'    => true
];
\DustPress\Query::get_acf_post( get_the_ID(), $args );

查询多个帖子

get_posts()

此函数将根据给定的参数查询多个帖子。帖子对象通过 WordPress WP_Query 类查询。此函数接受以下参数

  • WordPress codex 中 get_posts 函数描述的所有参数：https://codex.wordpress.org/Function_Reference/get_posts
  • meta_keys：此功能在 get_post() 函数中描述，并且应用于每个找到的帖子。
  • 查询对象：如果设置为false，函数返回一个数组中的帖子。如果设置为true，函数返回一个对象，其规格如下所述。默认为false。

如果没有找到匹配的帖子，则返回false。此函数的返回类型根据提供的参数而变化。如果将query_object参数设置为true或接受的WP_Query参数no_found_rows设置为false，则函数返回一个干净的带有从查询的WP_Query类实例复制属性（删除了不必要的属性）的对象。如果这些条件不满足，则函数返回找到的帖子数组。

在返回的数组中，WordPress帖子对象通过以下键进行了扩展

  • permalink - 帖子的永久链接。
  • image_id - 如果为帖子设置了特色图像，则这是其 id。
示例用法
public function Query() {
	// Args might be set if the function is in a submodel or
	// they can come from a DustPress.js AJAX request.
    $args = $this->get_args();

    $per_page   = (int) get_option( 'posts_per_page' );
    $page       = isset( $args['page'] ) ? $args['page'] : 1;
    $offset     = ( $page - 1 ) * $per_page;

    $query_args = [
        'post_type'                 => 'post',
        'posts_per_page'            => $per_page,
        'offset'                    => $offset,
        'update_post_meta_cache'    => false,
        'update_post_term_cache'    => false,
        'no_found_rows'             => false,
        'query_object'              => false,
    ];

    // This returns a WP_Query like object.
    // Queried posts are accessible in dust under the 'Query' key.
    return \DustPress\Query::get_posts( $args );
}

get_acf_posts()

此函数扩展了\DustPress\Query\get_posts方法，使其能够加载ACF字段组数据与帖子对象。接受描述的get_posts方法的参数也在此接受，增加了键whole_fields，其用法类似于\DustPress\Query\get_acf_post函数。

此函数不支持递归获取相关帖子。需要单独加载具有关系帖子对象数据的ACF字段。

除了\DustPress\Query\get_posts之外，还从找到的帖子对象中移除了image_id键，并扩展了WordPress帖子对象（https://codex.wordpress.org/Class_Reference/WP_Post）以下键

  • permalink - 帖子的永久链接。
  • image - 如果为帖子设置了特色图片，则这是由acf_get_attachment函数返回的数据。

插件

调试器

DustPress还具备一个调试器，可以在美观的JSON查看器中显示您当前模型加载数据。

从Geniem GitHub获取调试器或使用Composer安装它。

composer require devgeniem/dustpress-debugger

DustPress.js

我们还创建了一个方便的DustPress.js库，用于在前端使用DustPress模型方法。

从Geniem Github获取DustPress.js或使用Composer安装它。

composer require devgeniem/dustpress-js

评论辅助工具

如果您需要在您的网站上制作评论功能，您可以使用我们非常易于使用的Comments辅助工具。它作为独立的插件提供。

从Geniem Github获取Comments辅助工具或使用Composer安装它。

composer require devgeniem/dustpress-comments

覆盖默认模板

DustPress提供了一种覆盖WordPress默认模板的方法，否则这些模板不易编辑。

目前可以修改