README

无缝集成您的WordPress站点到GearLab Tools套件。

安装

手动安装

下载最新版本的.zip存档并将其提取的目录放置在wp-content/plugins中。像往常一样，从WP管理激活插件。

通过Composer安装

将需求添加到您的composer.json

composer require sitecrafting/gearlab-tools-wordpress --prefer-dist

注意：如果您将WordPress代码库作为一个大型的monorepo跟踪，则--prefer-dist标志非常重要！这告诉Composer查找并下载.zip存档而不是完整的Git仓库。没有此标志，它将创建插件目录作为Git子模块，会发生奇怪的事情。

使用方法

入门

安装并激活插件后，转到WP管理的GearLab Tools部分。输入GearLab提供的API密钥、集合ID和基础URI。所有设置都是必需的。

搜索

使用GearLab Tools，您可以覆盖默认的WordPress搜索功能，该功能默认非常有限，并使用由GearLab Search提供的ElasticSearch爬虫的结果。为此，您必须首先按照上述入门中所述输入您的设置。

一旦您输入了上述设置，但在全局启用覆盖WordPress搜索之前，您可以从命令行测试以查看是否得到结果。为此，请运行wp gearlab search <search term>。您应该看到一个类似于以下JSON对象的输出

{"results": [{"url": "https://www.example.com/example-page", "title": "Example Page", "snippet": "Some content"}, ...]}

一旦正确输入了上述设置，您就可以启用GearLab Tools搜索来覆盖默认的WP搜索。启用选项覆盖默认WordPress搜索并再次保存设置。现在，每次您进行搜索时，您都应该看到由GearLab Tools渲染的基本搜索结果页面。

搜索短码

默认情况下，您可以在任何支持短码的RTE中使用[gearlab_search]短码。这是大多数情况下的推荐方法。

然而，基本搜索（使用WordPress的默认s查询参数）仍然会渲染您主题的默认search.php模板（假设存在）。您可以在设置中将全局搜索重定向到您的短码所在页面。转到设置 > GearLab Tools并选择将搜索重定向到特定页面。在出现的文本框中输入URI，例如/search。

保存您的更改，您就可以开始了！默认搜索现在将重定向到您的页面。请注意，所有查询字符串参数都将保留除了s，它将被重命名为glt_search以避免与WordPress的默认功能冲突。

覆盖Timber模板

此插件对Timber有特殊支持。

要覆盖Timber如何渲染您的搜索结果，您可以添加主题覆盖。这些是插件在您的主题中查找的文件，如果找到它们，则加载它们，如果没有找到，则回退到插件自己的模板。这些文件位于（相对于您的主题根目录）

• gearlab-tools/search.php：主PHP模板，用于运行。如果您想支持例如对metaTag进行筛选的UI，则覆盖此文件并查看下面的示例。
• (Timber模板路径)/gearlab-tools/search.twig：用于渲染搜索页面的主Twig模板。如果您不需要更改后端功能（例如，搜索筛选器的应用方式），而只想更改整体搜索结果页面的渲染方式，则覆盖此文件。
• (Timber模板路径)/gearlab-tools/search-result.twig：使用Twig渲染单个搜索结果。

...其中(Timber模板路径)是Timber已知用于查找Twig模板的任何位置。最常见的地方是您主题中的templates或views目录。

覆盖GearLab的search.php模板

在您的主题中，在gearlab-tools/search.php处放置以下内容（此示例不依赖于Timber）：

// NOTE: the client may throw an exception!
use Swagger\Client\ApiException;

// Call out to the API
try {
  // search with some sensible defaults
  $response = GearLab\search();
} catch (ApiException $e) {
  error_log($e->getMessage());
  $response = [];
}

wp_header();

// Render results
foreach (($response['results'] ?? []) as $result) : ?>
  <article class="search-result">
    <h1><a href="<?= $result['url'] ?>><?= $result['title'] ?></a></h1>
    <p><?= $result['snippet'] ?></p>
  </article>
<?php endforeach; ?>

<?= GearLab\paginate_links($response) ?>

<?php wp_footer(); ?>

为了获得更多自定义行为，您可以直接向GearLab\search()传递参数。

use Swagger\Client\ApiException;

// Override your site's pagination settings.
$count = 25;

// Note that we can't use $paged here, because WordPress core won't
// necessarily report the same number of pages as GearLab, leading to 404s
// in cases where GearLab has more result pages than WP would.
$pageOffset = ($_GET['page_num'] ?? 1) - 1;


// Call out to the API
try {
  $response = GearLab\search([
    // Pass the user's search term to the API.
    'query'     => get_query_var('s'),
    // Tell the API how many results we want per page.
    'resLength' => $count,
    // Tell the API which page of results we want.
    'resOffset' => $pageOffset * $count,
    // Tell the API to only return results of a certain type
    'metaKey'   => $_GET['my_content_type'],
  ]);
} catch (ApiException $e) {
  error_log($e->getMessage());
  $response = [];
}


// Render results
foreach (($response['results'] ?? []) as $result) : ?>
  <article class="search-result">
    <h1><a href="<?= $result['url'] ?>><?= $result['title'] ?></a></h1>
    <p><?= $result['snippet'] ?></p>
  </article>
<?php endforeach; ?>

<?= GearLab\paginate_links($response) ?>

搜索自动完成

除了提供优质的搜索结果外，GearLab Tools还自带将搜索自动完成添加到您的搜索模板中。您不需要做任何事情来使其工作，尽管您可能想覆盖默认的jquery-ui-autocomplete样式。

此模块对您的HTML的唯一假设是搜索输入可以在选择器form [name="s"]中找到，即name属性为"s"的表单元素。由于WordPress搜索的实现方式，除非您的搜索功能以高级方式覆盖了WordPress核心，否则此假设将成立。

好奇者可以知道，此功能通过在/wp-json/gearlab/v2/completions处注册自定义WP REST路由，并告诉jquery-ui-autocomplete从该路由获取自动完成建议来工作。

WP-CLI自定义命令

该插件实现了针对主要GearLab Tools REST端点（如搜索）的WP-CLI命令。

wp gearlab search tacos

这将自动使用您在插件设置中配置的凭据。

运行wp gearlab --help以列出子命令。

与其他WordPress选项一样，您可以使用wp option配置插件选项。

wp option get gearlab_api_key
wp option get gearlab_collection_id
wp option get gearlab_base_uri
wp option get gearlab_enabled
wp option set gearlab_api_key supersecure
wp option set gearlab_collection_id 12345
wp option https://prd.search-api-gateway.aws.gearlabnw.net
wp option set gearlab_enabled 1

开发

要构建新版本，选择Git标签名称并运行：

bin/build-release.sh <TAG>

这将创建一个.tar.gz和一个.zip存档，您可以将其上传到GitHub上的新版本。

如果您已安装hub，脚本将检测到它并提示您选择性地直接创建GitHub发布。