README

无缝将您的WordPress站点与Sitka Insights套件集成。

安装

手动安装

访问GitHub 发布页面 并下载最新版本的.zip存档。请确保您下载的是发布存档，而不是源代码存档。例如，如果最新版本名为v2.x.x，请点击名为sitka-insights-v2.x.x.zip的下载链接。（如果您想使用tar.gz存档也可以 - 它们包含相同的代码。）

下载并解压后，将提取的目录放置在wp-content/plugins中。像平常一样从WP管理员激活插件。

通过Composer安装

将要求添加到您的composer.json中

composer require sitecrafting/sitka-insights-wordpress --prefer-dist

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

使用方法

入门

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

搜索

使用Sitka Insights，您可以使用Sitka Search驱动的ElasticSearch爬虫的结果来覆盖默认的WordPress搜索功能，该功能默认非常有限。为此，您必须首先按照上述在入门中描述的方式输入您的设置。

输入Sitka Insights设置后，但在全局启用覆盖WordPress搜索之前，您可以从命令行测试以查看是否得到结果。为此，请运行wp sitka search <search term>。您应该看到如下JSON对象

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

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

搜索短代码

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

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

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

直接使用Sitka WordPress API

如果您想要更多的控制，可以直接使用提供的WordPress API。在您的主题中的search.php文件中放置以下内容：

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

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

wp_header();

// Render results
<?php if (empty($response['results'])) : ?>
  <p>Sorry, no results for <?= $response['originalQueryPhrase'] ?? ' that search term.' ?></p>
<?php else : ?>
  <?php 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; ?>
<?php endif; ?>

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

<?php wp_footer(); ?>

对于更定制的行为，您可以直接传递参数给Sitka\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 Sitka, leading to 404s
// in cases where Sitka has more result pages than WP would.
$page_offset = ($_GET['page_num'] ?? 1) - 1;


// Call out to the API
try {
  $response = Sitka\search([
    // Pass the user's search term to the API.
    'query'     => get_query_var('my_search_param'),
    // Tell the API how many results we want per page.
    'resLength' => $count,
    // Tell the API which page of results we want.
    'resOffset' => $page_offset * $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; ?>

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

主题覆盖

在渲染前端代码，例如搜索结果的标记时，Sitka会检查您主题的根目录（style.css所在的目录）中的特殊sitka-insights文件夹。如果此文件夹中存在某个文件，例如search-result.php，则Sitka将渲染该版本。否则，它将渲染其默认的实现。

Sitka默认无需主题覆盖即可使用，但如果您需要自定义渲染的标记，请按照以下方法操作。

目前有三种前端文件可以从您的主题中覆盖：

• search-result.php渲染单个搜索结果
• search-results.php渲染所有搜索结果，包裹在一个容器元素中。
• pagination.php渲染分页

当您这样做时，Sitka将require您的主题文件，设置一个名为$data的变量，该变量是一个包含您在覆盖模板中所有可用数据的数组。这将在不同的模板之间有所不同。

分页

Sitka实现自己的分页结果逻辑，与核心paginate_links()函数不同，它不与WordPress的内部查询逻辑耦合。实际上，它比内置的WordPress函数更容易使用。

以下是函数的默认返回值（不是回显输出），当有10页结果（且用户在第1页）时：

<div class="pagination">
  <span aria-current="page" class="page-numbers current">1</span>    
  <a class="page-numbers" href="?s=doctor&amp;page_num=2">2</a>
  <a class="page-numbers" href="?s=doctor&amp;page_num=3">3</a>
  <span class="page-numbers dots">…</span>
  <a class="page-numbers" href="?s=doctor&amp;page_num=10">10</a>
  <a class="page-numbers next" href="?s=doctor&amp;page_num=2" rel="next">Next</a>
</div>

自定义分页标记

您可以使用标准主题覆盖来覆盖此标记（请参阅前面的关于此的部分）。

以下是默认实现：

<?php

$url_params    = $data['url_params']; // this is just $_GET by default
$paginator = $data['paginator']; // A Sitka\Plugin\Paginator instance
$markers   = $paginator->page_markers($url_params);

/* START MARKUP */
if ($paginator->page_count() > 1) : ?>
  <div class="pagination">
    <?php foreach ($markers as $marker) : ?>
      <?php if (!empty($marker['previous'])) : ?>
        <a class="page-numbers prev" href="<?= $paginator->previous_page_url($url_params) ?>" rel="prev">Previous</a>
      <?php endif; ?>

      <?php if (!empty($marker['current'])) : ?>
        <span aria-current="page" class="page-numbers current"><?= $marker['page_num'] ?></span>
      <?php elseif (!empty($marker['filler'])) : ?>
        <span class="page-numbers dots">…</span>
      <?php elseif (!empty($marker['page_num'])) : ?>
        <a class="page-numbers" href="<?= $marker['url'] ?>"><?= $marker['page_num'] ?></a>
      <?php endif ?>

      <?php if (!empty($marker['next'])) : ?>
        <a class="page-numbers next" href="<?= $paginator->next_page_url($url_params) ?>" rel="next">Next</a>
      <?php endif; ?>
    <?php endforeach; ?>
  </div>
<?php endif; ?>

$paginator是一个对象，它实现了prev/next/number链接或“标记”应该显示的大部分复杂逻辑。请注意，您需要的有关每个标记的大部分信息都存在于标记数组本身中。

关键的是，请始终将$url_params数组传递给Paginator方法page_markers()、previous_page_url()和next_page_url()。否则，您的链接将不正确。

这是一个标记数组的示例，当我们在结果的第4页时返回，总共有25页。

// NOTE: Normally you are simply passed the $url_params array; you typically
// won't build it yourself. This is just for demonstration purposes.
$url_params = [
  's'        => 'doctor',
  'page_num' => 4,
];

$paginator->page_markers($url_params);

// result:
[
  [
    'text'     => 'Previous',
    'url'      => '?s=doctor&page_num=3',
    'previous' => true,
  ],
  [
    'page_num' => 1,
    'current'  => false,
    'url'      => '?s=doctor&page_num=1',
  ],
  [
    'page_num' => 2,
    'current'  => false,
    'url'      => '?s=doctor&page_num=2',
  ],
  [
    'page_num' => 3,
    'current'  => false,
    'url'      => '?s=doctor&page_num=3',
  ],
  [
    'page_num' => 4,
    'current'  => true,
    'url'      => '?s=doctor&page_num=4',
  ],
  [
    'page_num' => 5,
    'current'  => false,
    'url'      => '?s=doctor&page_num=5',
  ],
  [
    'page_num' => 6,
    'current'  => false,
    'url'      => '?s=doctor&page_num=6',
  ],
  [
    'text'     => '...',
    'filler'   => true,
  ],
  [
    'page_num' => 25,
    'current'  => false,
    'url'      => '?s=doctor&page_num=25',
  ],
  [
    'text'     => 'Next',
    'url'      => '?s=doctor&page_num=5',
    'next'     => true,
  ],
]

自定义分页参数

如果模板标记没问题，但您需要影响分页的逻辑，则可能需要sitka/pagination/construct过滤器，因为它控制传递给Sitka\Plugin\Paginator::__construct方法的数组。此钩子可用于自定义以下内容：

• 在显示“填充”标记（…）之前，显示在当前页码旁边的“附近”或“相邻”页码的数量（默认为2）
• 总页数和当前页码，以防您需要以某种原因覆盖这些值

以下是覆盖渲染相邻页数的示例

add_filter('sitka/pagination/construct', function(array $ctor_args) {
  return array_merge($ctor_args, [
    'display_adjacent' => 3, // override the default of 2
  ]);
});

搜索自动完成

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

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

对于好奇者，此功能通过在 /wp-json/sitka/v2/completions 注册自定义WP REST路由，并告诉 jquery-ui-autocomplete 从该路由获取自动完成建议。

WP-CLI自定义命令

插件实现了针对主要Sitka Insights REST端点的WP-CLI命令，例如搜索

wp sitka search tacos
wp sitka s tacos # `s` is an alias for `search`
wp sitka completions
wp sitka c taco # `c` is an alias for `completions`

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

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

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

wp option get sitka_api_key
wp option get sitka_collection_id
wp option get sitka_base_uri
wp option get sitka_enabled
wp option set sitka_api_key supersecure
wp option set sitka_collection_id 12345
wp option set sitka_environment production
wp option set sitka_enabled 1

开发

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

bin/build-release.sh <TAG>

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

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