WordPress Popular Postsで出力されるHTMLをカスタマイズする

簡単に記事ランキングを表示できるため、多くのWordPressサイトで利用されている人気プラグイン「WordPress Popular Posts」。しかし、サイトのデザインに合わせて表示するには、出力されるHTMLを適宜カスタマイズする必要があります。

今回は、その「WordPress Popular Posts」で出力される HTML をカスタマイズする方法についてまとめました。

使用バージョン：WordPress 6.7.2、WordPress Popular Posts 7.2.0

WordPress Popular Posts で記事ランキングを表示させる方法
- ショートコード [wpp] を使って表示
- wpp_get_mostpopular() を使って表示
[wpp] と wpp_get_mostpopular() で使えるオプション
post_html で使用できる変数
終わりに

WordPress Popular Posts で記事ランキングを表示させる方法

まず、詳しいカスタマイズ方法の前に、WordPress Popular Posts で記事ランキングを表示させる方法について簡単に説明します。主な方法は 2 つです。

ショートコード [wpp] を使って表示

ショートコード[wpp]を使用して表示させる方法です。ショートコード内でオプションを指定することで、出力する情報をカスタマイズできます。

例えば、データの集計期間を 1 ヵ月、表示順を閲覧数順、取得件数を 5 件で取得する場合は、以下のようになります。

[wpp range='monthly' order_by='views' limit=5]

wpp_get_mostpopular() を使って表示

もう一つの方法が、wpp_get_mostpopular()関数を使って表示させる方法です。オプション配列を渡すことで、出力する情報をカスタマイズできます。

ショートコードの例と同じく、データの集計期間を 1 ヵ月、表示順を閲覧数順、取得件数を 5 件で取得する場合は、以下のようになります。

wpp_get_mostpopular(array(
  'range' => 'monthly',
  'order_by' => 'views',
  'limit' => 5,
));

さて、ここからはいよいよ詳しいカスタマイズ方法です。

[wpp] と wpp_get_mostpopular() で使えるオプション

上の例で使用したオプション以外にも、WordPress Popular Posts には様々なオプションが用意されており、それらを駆使することで柔軟なカスタマイズが可能です。ちなみに、wpp_get_mostpopular()は、内部的にdo_shortcode()で[wpp]を呼び出しているため、これから紹介するオプションはどちらの場合でも使用することができます。

数あるオプションの中でも、出力されるHTMLの構造を細かく設定できる post_html は特に重要です。このオプションは設定内容が複雑なため、詳細は最後に記載します。

取得条件に関するオプション

オプション名	説明	指定可能な値	デフォルト値
limit	取得件数	数値	10
offset	取得開始位置	数値	0
range	集計期間	'daily' 'last24hours' 'weekly' 'last7days' 'monthly' 'last30days' 'all' 'custom'	'daily'
time_unit	`range`が`custom`の時に使用、時間の単位を指定。	'minute' 'hour' 'day' 'week' 'month'	'hour'
time_quantity	`range`が`custom`の時に使用、時間の数値を指定。	数値	24
freshness	集計期間内に投稿された記事のみを対象にするかどうか。	bool	false
order_by	表示順で使用する項目	'comments' 'views' 'avg'	'views'
post_type	対象の投稿タイプ	文字列（複数指定する場合はカンマ区切り）	'post'
exclude	除外する投稿 ID	文字列（複数指定する場合はカンマ区切り）	''
cat	対象のカテゴリー ID	文字列（複数指定する場合はカンマ区切り）	''
taxonomy	対象のタクソノミー	文字列	'category'
term_id	対象の term_id	文字列（複数指定する場合はカンマ区切り）	''
author	対象の投稿者 ID	文字列（複数指定する場合はカンマ区切り）	''

表示するデータに関するオプション

オプション名	説明	指定可能な値	デフォルト値
title_length	取得するタイトルの長さ。0 で制限なし。	数値	0
title_by_words	タイトルの長さを文字数ではなく単語数で取得するかどうか。	bool	0
excerpt_length	取得する抜粋の長さ。0 の場合は取得しない。	数値	0
excerpt_by_words	抜粋の長さを文字数ではなく単語数で取得するかどうか。	bool	0
excerpt_format	抜粋に含まれる HTML タグをそのまま取得するかどうか。	bool	0
rating	評価情報を表示するかどうか（WP-PostRatings プラグインを併用している場合に有効）	bool	false
stats_comments	コメントの件数を表示するかどうか	bool	false
stats_views	PV 数を表示するかどうか	bool	true
stats_author	投稿者情報を表示するかどうか	bool	false
stats_date	投稿日時を表示するかどうか	bool	false
stats_date_format	投稿日時のフォーマット	文字列（日付フォーマット）	'F j, Y'
stats_category	カテゴリーを表示するかどうか	bool	false
stats_taxonomy	タクソノミーを表示するかどうか	bool	false

HTML 出力に関するオプション

オプション名	説明	指定可能な値	デフォルト値
ajaxify	表示に Ajax を使用するかどうか	bool	1（管理画面の設定で Ajax を無効にしていた場合は 0）
theme	プラグインフォルダ内の `/assets/themes` の中にあるフォルダ名を指定すると、その中にあるスタイルが適用される。	文字列	''
header	リストの上に表示する見出しの文字列（空で非表示）	文字列	''
header_start	見出しの開始タグ	文字列	'<h2>'
header_end	見出しの終了タグ	文字列	'</h2>'
thumbnail_width	サムネイルの幅。	数値	0
thumbnail_height	サムネイルの高さ。	数値	0
thumbnail_build	プラグイン用のサムネイルを生成するかどうか。'predefined' を指定すると、アイキャッチの画像がそのまま使われる。	'manual' 'predefined'	'manual'
wpp_start	リストの開始タグ	文字列	'<ul class="wpp-list">'
wpp_end	リストの終了タグ	文字列	'</ul>'
post_html	出力される<li>タグの HTML 構造（使用できる変数については後述）	文字列	'<li>{thumb} {title} <span class="wpp-meta post-stats">{stats}</span></li>'

post_html で使用できる変数

post_htmlオプションは、出力される<li>タグの HTML のフォーマットをカスタマイズできます。このとき、特定の変数を使うことで、記事のタイトルやURL、サムネイルなどを動的に挿入できます。

変数	出力内容
{pid}	投稿 ID
{url}	記事のURL
{title}	記事タイトル（記事のリンク付き）
{title_attr}	記事タイトル（テキストのみ）
{text_title}	記事タイトル（テキストのみ、`title_length`の設定が反映されたもの）
{thumb}	サムネイル画像の`<img>`タグ（記事のリンク付き）
{thumb_img}	サムネイル画像の`<img>`タグ
{thumb_url}	サムネイル画像の URL
{excerpt}	記事の抜粋（`'excerpt_length'`が 0 以外の時のみ有効）
{views}	記事の PV 数
{comments}	記事のコメント数
{date}	記事の投稿日時（`'stats_date'`が`true`の時のみ有効）
{author}	投稿者名（アーカイブリンク付き、`'stats_author'`が`true`の時のみ有効）
{author_name}	投稿者名（`'stats_author'`が`true`の時のみ有効）
{author_url}	投稿者のアーカイブ URL（`'stats_author'`が`true`の時のみ有効）
{taxonomy}	カテゴリー（アーカイブリンク付き、`'stats_taxonomy'`か`'stats_category'`が`true`の時のみ有効）
{category}	`{taxonomy}`と同じ（`'stats_taxonomy'`か`'stats_category'`が`true`の時のみ有効）
{stats}	`stats_`系のオプションについて、`true`になっている項目の情報をまとめて表示。
{item_position}	順位。ただし、`offset`の指定があったとしても、その分繰り上がるわけではない。
{rating}	WP-PostRatings プラグインの評価情報（フォーマットは WP-PostRatings の設定による）
{score}	WP-PostRatings プラグインの評価情報（数値のみ）
{total_items}	取得した記事の件数
{current_class}	同じ投稿 ID のページが表示されている場合は current と出力される。

終わりに

今までなんとなくで使っていましたが、ガッツリ調べてみると知らない設定がたくさんありました。ちなみに、当サイトでは以下のような設定でサイドバーに表示させています。

wpp_get_mostpopular(array(
  'range' => 'monthly',
  'limit' => 5,
  'rating' => true,
  'thumbnail_build' => 'predefined',
  'thumbnail_width' => 320,
  'thumbnail_height' => 168,
  'wpp_start' => '<ul class="sidebar-posts">',
  'post_html' => '<li><a href="{url}" title="{title_attr}"><div class="thumbnail"><img src="{thumb_url}"></div><div class="title">{title_attr}</div></a></li>'
));

サムネイルを生成しないようにできるなんて知りませんでした…。

WordPress の人気プラグイン「WordPress Popular Posts」を使う際は、是非参考にしてみてください。