README

Rest-Easy 是一个 WordPress 插件，旨在让您轻松将网站 Rest 化，并提供强大的自定义功能。

目录

1. 安装
2. 教程
   1. 基础
   2. 自定义过滤器
3. 核心概念
4. 参考
   1. 过滤器
      1. 构建器过滤器
         1. 站点数据
         2. 元数据
         3. 循环数据
      2. 序列化过滤器
         1. 序列化对象
         2. 序列化附件
         3. 序列化菜单
         4. 序列化导航项
         5. 序列化帖子
         6. 收集相关内容
   2. 实用函数
   3. 集成

安装

Rest-Easy 是作为 Vuepress 的配套工具构建的，因此如果您使用 VP，Rest-Easy 将会自动安装。

如果您不使用 Vuepress，或希望手动安装插件，请按照以下步骤操作

1. 下载插件的最新版本 [下载链接]。
2. 转到您网站的插件安装页面 ([your-site.com]/wp-admin/plugin-install.php)。
3. 点击 "上传插件"，然后上传步骤 1 中的 .zip 文件。
4. 转到您网站的插件页面 ([your-site.com]/wp-admin/plugins.php)，然后点击 Rest Easy 插件的 "激活"。

就这样！

教程

查看 可视化文档，了解 Rest-Easy 响应的逐步路线图。如果您使用 Vuepress，基础部分将自动处理 - 您可以继续阅读以了解 Rest-Easy 的工作方式，或转到 自定义过滤器 了解下一步。

基础

安装 Rest-Easy 后，导航到您网站上的任何页面，并在 URL 末尾添加 ?contentType=json。

您将看到包含请求页面数据的序列化 JSON 对象 - 这是对当前页面的轻量级且详尽的摘要，而您无需进行任何设置！

要程序化获取页面的此 JSON 序列化版本，您可以在您网站的 JS 中执行以下操作

fetch(myUrl + '?contentType=json')
    .then(res => {
        return res.json()
    })
    .then(json => console.log(json))

此示例 fetches 您网站上的请求页面，并返回与 ?contentType=json 查询参数相同的相同 JSON 对象。现在，您已经拥有了一个具有大量详细信息的有效 RESTful API。

自定义过滤器

Rest-Easy 对页面序列化的方式有一些假设 - 但如果您想更改这种序列化呢？

假设您想添加一个名为 _my_custom_field 的自定义字段，使其在数据中可用。将以下内容添加到您主题的 functions.php 文件中

function add_custom_field($input) {
    global $post;
    $input['myCustomField'] = $post->_my_custom_field;

    return $input;
}
add_filter('rez_serialize_post', 'add_custom_field');

让我们逐行分析。

• function add_custom_field($input) {

  Rest-Easy 首先会对帖子进行默认序列化，然后将结果传递给您的自定义过滤器作为关联数组（本例中的 $input）。您的过滤器可以添加、删除或编辑信息，然后将修改后的结果传递给下一个自定义过滤器，或者如果没有其他过滤器，则传递给最终的 JSON 输出。

• global $post;

  这是您目前正在工作的 WP 对象的引用。

• $input['myCustomField'] = $post->$_my_custom_field;

  这一行将 $post->_my_custom_field 的值保存到 $input 数组中。你可以给数据命名，这里使用驼峰命名法命名为 myCustomField。

• 返回 $input;

  这一行将修改后的数组传递给下一个自定义过滤器或最终的 JSON 输出。

• add_filter('rez_serialize_post', 'add_custom_field');

  Rest-Easy 需要知道你的自定义过滤器在哪里定义，所以我们使用 WordPress 的 add_filter 函数将 add_custom_field 方法（在示例的第一行中定义的名称）添加到 Rest-Easy 的 rez_serialize_post 过滤器中。

现在，每当你加载一个定义了 _my_custom_field 的帖子时，你会在 jsonData.loop[0]._my_custom_field 中看到你的自定义字段！

核心概念

（这是底层的实现信息——如果你不是在开发 Rest-Easy，无需担心这一点！）

为了避免页面序列化中的无限循环，Rest-Easy 使用两个主要概念：构建器 和 序列化器。

构建器 在一个页面上只运行一次。它将多个序列化器的输出组合起来，并以关联数组的形式返回这些数据，然后将其 JSON 编码形成 jsonData。

（注意，构建器也是唯一可以收集相关帖子的函数——如果其他任何东西都可以这样做，相关帖子会不断地在自身之上构建，而不会像在 Loop 构建器中那样保持一级深度。）

序列化器 将从 WordPress 中获取的数据转换成关联数组。例如，序列化器会将帖子转换成一个包含帖子标题、内容、永久链接等的数组。

Rest-Easy 的入口点是 rest-easy.php，在那里它

1. 运行 builders.php 中的 rez_build_all_data 函数中的序列化器
2. 通过检查请求的 CONTENT_TYPE 和查询字符串来确定如何将请求的输出发送给用户
   • 如果找到了，则输出 jsonData 对象
   • 否则，使用 wp_localize_script 将 jsonData 对象输出到页面上

参考

过滤器

添加自定义过滤器以构建自己的数据

function custom_function_name($input){
    // modify $input here...
    return $input;
}
add_filter('desired_rest_easy_filter', 'custom_function_name');

以下显示默认值。

构建器过滤器

构建器在每个页面上运行一次。它们旨在收集序列化数据，添加一些高级站点/元信息，并输出结果 JSON 对象。大多数时候，你只有在添加非常通用的站点信息时才会使用构建器——例如区域检测、自定义网站标语等。

• rez_build_all_data - 最高级别的数据构建器——这是结果 JSON 对象的顶层结构。返回

  array(
      // key      => filter
      'site'      => rez_build_site_data,
      'meta'      => rez_build_meta_data,
      'loop'      => rez_build_loop_data
  )

站点数据

• rez_build_site_data - 构建有关站点的通用信息

  array(
      'themeUrl'      => 'URL of current WordPress theme',
      'url'           => 'URL of site'
      'name'          => 'Site name',
      'description'   => 'Site description',
      'menus'         => array(
          // Array of all menus on the site
      ),
      'isMobile'      => 'Boolean - result of wp_is_mobile()'
  )

元数据

• rez_build_meta_data - 构建有关当前页面的元信息。

  array(
      'self'          => 'permalink to current page',
      'is404'         => /* bool - did this request return a 404 error? */,
      'nextPage'      => 'permalink to next page in pagination, if present',
      'previousPage'  => 'permalink to previous page in pagination, if present'
  )

循环数据

• rez_build_loop_data - 序列化当前在 The Loop 中的所有页面。

  array(
      // Array of serialized posts, pages, etc.
      // By default, each element in the array will be the result of
      // combining 'rez_serialize_object' and 'rez_gather_related'
  )

序列化过滤器

序列化器旨在将任何 WordPress 对象转换成 JSON 数据。当你想更改单个帖子、页面、媒体项目等返回的信息时，应自定义序列化器。帖子作者、媒体上传日期和自定义元字段是自定义序列化器的绝佳候选者。

序列化对象

• rez_serialize_object - 通用序列化器。知道如何序列化任何对象。

  * Runs rez_serialize_attachment filter if a media attachment
  * Runs rez_serialize_menu filter if a menu
  * Runs rez_serialize_nav_item filter if a menu item
  * Runs rez_serialize_post filter, then adds `_wshop_product_id` as `productId`, if a `wps-product` (see https://github.com/funkhaus/wp-shopify)
  * Runs rez_serialize_post filter if any other object type

序列化附件

• rez_serialize_attachment - 序列化一个媒体附件

  array(
      'ID'                => /* int - attachment ID */,
      'title'             => 'title of attachment',
      'alt'               => 'alt text - looks for Alt Text, then Caption, then attachment title',
      'caption'           => 'caption from WordPress',
      'description'       => 'description from WordPress',
  
      // This section only runs if the Funky Colors plugin is installed
      'primaryColor'      => 'primary image color from Funky Colors',
      'secondaryColor'    => 'secondary image color from Funky Colors'
      // End Funky-Colors-only section
  
      'postType'          => 'post type',
      'sizes' => array(
          // Runs for each image size defined in WP (https://developer.wordpress.org/reference/functions/add_image_size/)
          'size-slug' => array(
              'url'       => 'url to image at given size',
              'width'     => /* int - width in px */,
              'height'    => /* int - height in px */
          )
      )
  )

序列化菜单

• rez_serialize_menu - 序列化一个菜单及其项目

  array(
      'name'      => 'menu name',
      'slug'      => 'menu slug',
      'postType'  => 'post type',
      'items'     => array(
          // Array of all items in this menu run through `rez_serialize_object` filter
      )
  )

序列化导航项

• rez_serialize_nav_item - 序列化一个菜单项

  array(
      'title'         => 'menu item title',
      'classes'       => 'menu item classes',
      'permalink'     => 'permalink to target',
      'relativePath'  => 'relative path to target',
      'isExternal'    => /* bool - true if type label == 'Custom Link' */,
      'ID'            => 'int - menu item ID',
      'children'      => 'object - results of serialize_nav_menu on submenus',
      'postType'      => 'post type'
  )

序列化帖子

• rez_serialize_post - 任何帖子类型的通用序列化器

  array(
      'id'            => /* int - post ID */,
      'title'         => 'post title',
      'content'       => 'content with "the_content" filters applied',
      'excerpt'       => 'post excerpt',
      'rawExcerpt'    => 'post excerpt - only if set manually',
      'permalink'     => 'post permalink',
      'slug'          => 'post slug',
      'relativePath'  => 'relative path to post',
      'meta'          => array(
          // Contains all meta fields without leading underscore
          // $post->this_will_be_included_automatically
          // $post->_this_will_not
      ),
      'date'          => /* int - Unix timestamp of post date */,
      'attachedMedia' => 'serialized array of media uploaded to this page',
      'featuredAttachment'    => 'serialized featured image',
      'isFront'       => /* boolean - is this the front page? */,
      'isBlog'        => /* boolean - is this the page for posts? */,
      'isCategory'    => /* boolean - is this a category archive page? */,
      'terms'         => 'Array of all terms this post contains',
      'postType'      => 'post type'
  )

收集相关内容

• rez_gather_related($related, $target_post) - 获取给定对象的关联数据

  $related == array(
      'featuredAttachment'    => 'the serialized featured attachment, if this object has one',
      'ancestors' => array(
          // ancestors of this page, if applicable, serialized with rez_serialize_post and ordered from farthest -> nearest (ie [great-grandparent, grandparent, parent])
      ),
      'children'  => array(
          // children of this page, if applicable, serialized with rez_serialize_post
      ),
      'parent'    => /* object - the parent of this page, serialized with rez_serialize_post */,
      'next'      => /* object - the next page in menu order, if applicable, serialized with rez_serialize_post */,
      'prev'      => /* object - the previous page in menu order, if applicable, serialized with rez_serialize_post */
  );
  
  $target_post == /* The target $post object */

实用函数

• rez_get_next_page_id($target_post) - 获取 $target_post 后的页面/帖子的 ID。
• rez_get_previous_page_id($target_post) - 获取 $target_post 之前的页面/帖子的 ID。
• set_attachment_serialization($target_post, $value) - 设置目标帖子是否应自动序列化其附件。例如，在序列化包含大量附件的页面时可以节省时间。

集成

Rest-Easy 是专为与其它 Funkhaus 插件良好兼容而构建的

• Funky Colors，用于确定图像的主色调
• WP-Shopify，用于简化 Shopify 与 WordPress 商店的连接

Rest-Easy

http://funkhaus.us