Vektor WordPress Solutions Advent Calendar 2021 12月25日の記事です。
前回の神尾さんの「WordPress引っ越し手順、lightningG2→G3への移行について」に引き続き、本日は今月のオンライン勉強会で質問のあった Lightning投稿一覧のカスタマイズについての話を書きます。

はじめに

WordPressには、カテゴリー一覧や月別アーカイブなど、投稿を一覧表示するアーカイブページがあります。

このアーカイブページには、投稿が並びますが、この投稿1件分に何を表示するのかは、多くの場合カスタマイズが必要になると思います。

今回はその投稿一覧の投稿1件分のカスタマイズ方法について解説します。

この記事をすすめる前に

本記事のカスタマイズは途中から出てくる 「VK_Component_Posts」の部分からは Lightning Pro 及び Katawara でも共通です。

そもそも Lightning G3 Pro Unit では、管理画面から投稿一覧に関するいろいろな設定が簡単にできるようになっています。本記事は G3 Pro Unit や Lightning Pro や Katawara の標準機能を使っても出来ないカスタマイズをするための解説になりますので、まずは G3 Pro Unit でできる事を把握して、それでもできない場合に参考にしてください。

本記事はPHPの基礎的は事を理解している前提で記載しています。よくわからない場合は以下の記事を参照ください。

投稿一覧の種類

投稿一覧のレイアウトについてLightningの場合は

  • アーカイブページ(カテゴリーページなど)で Lightning 標準状態での投稿一覧
    (無料版の場合はこれだけ)
  • アーカイブページ(カテゴリーページなど)で Lightning G3 Pro Unit などによって 外観 > カスタマイズ > Lightning アーカイブ設定 から表示要素を変更した状態の投稿一覧
  • VK Blocks Pro の「投稿リストブロック」で配置した投稿一覧

という3つの表示ケースがあります。

Lightning 標準投稿一覧のカスタマイズ

まずは標準の一覧のカスタマイズを見てみましょう。

子テーマの _g3/template-parts/ ディレクトリに(なければ作成)loop-item.php という名前で以下のように配置してみてください。

※ 子テーマについてわからない場合は [ カスタマイズの準備 1 : Lightningの子テーマの準備 ] を参照してください。

<article class="col-12">
    <?php echo esc_html( get_the_date() ); ?>
    <a href="<?php the_permalink(); ?>">
    <?php the_title(); ?>
    </a>
</article>

そうすると1件分の投稿が以下のように変更されます。

変更されない場合のケース

アーカイブページの表示タイプ「Lightning 標準」以外に変更している

G3 Pro Unit ではアーカイブ一覧のレイアウトを変更する機能が最初から備わっています。

外観 > カスタマイズ > Lightning アーカイブ設定 > (表示中のページの投稿タイプ) 画面で表示タイプを「Lightning 標準」以外にしている場合は表示要素が他のものに差し替わるので、このカスタマイズ方法は無効です。

アーカイブページではなく投稿リストブロックで配置したものを見ている

投稿一覧ページではなく、投稿リストブロックを配置した部分を見ていないか確認してください。
ここで変更されるのは例えばカテゴリーのアーカイブページです。

投稿タイプ毎の改変

ファイルの名前を loop-item-★投稿タイプ名★.php のように、最後に投稿タイプ名を追加すると、その投稿タイプにだけ適用されます。

たとえば以下のファイル名では、カスタム投稿タイプ event の場合のみ変更されます。

loop-item-event.php

しかしながら、この改変方法は先に述べた通りアーカイブページでのみ有効でそれ以外の場所には反映されないという特性があるため、それ以外のページでも改変する方法を説明します。

VK_Component_Posts による改変

VK_Component_Posts とは?

昔は表示レイアウトや要素を変更したい場合は、先に紹介したように、phpファイルを直接カスタマイズするしかありませんでした。

しかしながら、コードのカスタマイズをしなくても様々なレイアウトや表示要素の変更を管理画面から行えるようにするために、現在は VK_Component_Posts という独自のプログラムを経由して投稿要素を表示しています。

このプログラムは Lightning G3 に限らず、Katawara でも VK Blocks Pro の投稿リストブロックなどにも使用されています。

VK_Component_Posts が書かれているファイルは Lightning で言えば

_g3/inc/vk-components/package/class-vk-component-post.php

になりますが、先に述べたとおり様々な表示変更機能を含んでいるため複雑になっています。

VK_Component_Posts のファイルは子テーマに複製してカスタマイズしても効かない

このファイルはユーザーの要望や状況に応じて機能追加・仕様変更が入る頻度が多いので、通常のテンプレートファイルのようにファイルを子テーマに複製してカスタマイズされると、アップデートに追従しなくなってしまいます。

そのため、子テーマに class-vk-component-post.php が複製してあってもそのファイルは読み込みません

「それではカスタマイズ出来ないじゃないか!」とならないように、外部からカスタマイズ可能なしくみになっていますので、それを順番に解説していきます。

表示要素を各種パラメーター指定している

まず、lightningの _g3/template-parts/loop-item.php を見てみましょう。

以下のようになっています。

$options = array(
    // card, card-noborder, card-intext, card-horizontal , media, postListText.
    'layout'                     => 'media',
    'display_image'              => true,
    'display_image_overlay_term' => true,
    'display_excerpt'            => true,
    'display_date'               => true,
    'display_new'                => true,
    'display_taxonomies'         => false,
    'display_btn'                => true,
    'image_default_url'          => false,
    'overlay'                    => false,
    'btn_text'                   => __( 'Read more', 'lightning' ),
    'btn_align'                  => 'text-right',
    'new_text'                   => __( 'New!!', 'lightning' ),
    'new_date'                   => 7,
    'class_outer'                => 'vk_post-col-xs-12 vk_post-col-sm-12 vk_post-col-lg-12',
    'class_title'                => '',
    'body_prepend'               => '',
    'body_append'                => '',
);
VK_Component_Posts::the_view( $post, $options );

最初に子テーマにカスタマイズした例では、表示するHTMLをすべて指定して書き換えていましたが、標準の loop-item.php では、HTMLらしき記述はありません。

一番最後の行の VK_Component_Posts::the_view(); が投稿1件分を表示するメソッド(命令)です。
このメソッドに、表示する投稿の情報である $post と、どういう形式で表示するのかという情報を $options で渡すと、表示するHTMLが自動生成されるという仕組みになっています。

$post

$post は WordPress 標準で用意されている変数です。
投稿記事タイトル名や日付などの情報が入っています。

$options

ここで使う $options は VK_Component_Posts 独自のパラメーターを格納しています。
名前を見るとなんとなく想像が付くと思いますが、true になっているものが表示、false は非表示になります。

値を変更して表示を確認してみよう

子テーマに _g3/template-parts/loop-item.php を複製してください。
子テーマ内に loop-item.php が既にある場合は中身を上書きするだけでもかまいません。

子テーマの loop-item.php の $options のパラメーターを変更してみましょう。

例えば、

‘display_image’ => true,

の部分を

‘display_image’ => false,

にしてみましょう。

画像が表示されなくなったのが確認できると思います。

このように一部だけの改変であれば、投稿一件分の要素全てを書かなくても値の変更で対応できます。

しかしながら、

  • 子テーマからしか改変できない
  • アーカイブページの「Lightning 標準」レイアウトしか改変できない

という欠点があり、G3 Pro Unit で改変したレイアウトや、VK Blocks Pro の投稿リストブロックでは効きませんので、loop-item.php を子テーマに複製してパラメーターを改変するこの方法は非推奨です。

次に紹介するフィルターフックを使用した改変方法が推奨です。

フィルターフックで投稿1件分の表示要素を変更する

先に紹介した VK_Component_Posts::the_view( $post, $options ); の $options の値は、子テーマのテンプレートファイルでなくても、外部から指示を書き換える事ができます。

子テーマの functions.php などに以下のコードを貼り付けてみてください。

/**
 * 投稿一覧画面で表示する投稿情報を改変する
 * @param array  $options : 1件分の表示形式に関する設定配列.
 * @param object $post : 1件分の投稿情報.
 */
add_filter(
    'vk_post_options',
    function( $options, $post ) {

        // $options の 'btn_text' の値を上書き
        $options['btn_text'] = '詳しくはこちら';

        // 改変した $options を返す
        return $options;
    },
    10,
    2
);

これで一覧ページを見てみると以下のようにボタンの文字が「詳しくはこちら」になります。

このように設定値を functions.php など外部のファイルから書き換えられます。
先の解説で loop-item.php を子テーマに複製してカスタマイズしましたが、functions.php に書いたコードに $options['display_image'] = false; を書き足せば、loop-item.php を削除しても同じ結果が得られます。

/**
 * 投稿一覧画面で表示する投稿情報を改変する
 * @param array  $options : 1件分の表示形式に関する設定配列.
 * @param object $post : 1件分の投稿情報.
 */
add_filter(
    'vk_post_options',
    function( $options, $post ) {

        // $options の 'display_image' の値を上書き
        $options['display_image'] = false;

        // $options の 'btn_text' の値を上書き
        $options['btn_text'] = '詳しくはこちら';

        // 改変した $options を返す
        return $options;
    },
    10,
    2
);

改変する場合の条件分岐を指定する

フィルターフックによるカスタマイズは、VK_Component_Posts を経由して表示している部分全てに適用されますので、外観 > カスタマイズ > Lightning アーカイブ設定 で Lightning 標準以外に変更してあったり、VK Blocks Pro の投稿リストで表示している部分も全てが書き変わります。

条件分岐を指定しないと意図しない部分まで改変してしまうので注意が必要です。

投稿タイプでの条件分岐

例えば、イベント情報(event)というカスタム投稿タイプがあったとして、イベント情報の投稿一覧だけボタンの文字を「イベント詳細」に変更したい場合は以下のように if で条件分岐を追加します。

/**
 * 投稿一覧画面で表示する投稿情報を改変する
 *
 * @param array  $options : 1件分の表示形式に関する設定配列.
 * @param object $post : 1件分の投稿情報.
 */
add_filter(
	'vk_post_options',
	function( $options, $post ) {

		// 投稿タイプが event の場合のみ改変
		if ( 'event' === get_post_type() ) {
			// $options の 'btn_text' の値を上書き
			$options['btn_text'] = 'イベント詳細';
		}

		// 改変した $options を返す
		return $options;
	},
	10,
	2
);

投稿一覧に表示する要素を追加する

予め用意された設定パラメーターの変更だけでなく、要素の追加も可能です。

パラメーターで body_prepend と body_append という項目がありますので、そこに指定した要素が追加で表示されます。

/**
 * 投稿一覧画面で表示する投稿情報に要素を追加する
 *
 * @param array  $options : 1件分の表示形式に関する設定配列.
 * @param object $post : 1件分の投稿情報.
 */
add_filter(
	'vk_post_options',
	function( $options, $post ) {

			// テキスト部分の前に要素を追加
			$options['body_prepend'] = '<p class="alert alert-info">前に追加</p>';

			// テキスト部分の後に要素を追加
			$options['body_append'] = '<p class="alert alert-warning">後に追加</p>';

		// 改変した $options を返す
		return $options;
	},
	10,
	2
);

カスタムフィールドの値を表示する

独自に追加したカスタムフィールドの値を表示する場合、先のコードの応用で可能です。

まずは以下の例を見てください。

/**
 * 投稿一覧画面で表示する投稿情報にカスタムフィールドの値を追加する
 *
 * @param array  $options : 1件分の表示形式に関する設定配列.
 * @param object $post : 1件分の投稿情報.
 */
add_filter(
	'vk_post_options',
	function ( $options, $post ) {

		// 表示したい投稿タイプを条件分岐で指定.
		if ( 'post' === get_post_type() ) {

			/************************************
			 * カスタムフィールドの値など独自に表示したい要素を一旦 $insert_html に格納する.
			 */
			$body_append_html = '';
			// 家賃の入力がある場合
			if ( $post->yachin ) {
				$body_append_html .= '<p class="data-yachin"><span class="data-yachin-number">' . esc_html( $post->yachin ) . '</span>万円</p>';
			}
			$body_append_html .= '<table class="table-sm mt-3">';
			// カスタムフィールド kanrihi / reikin / chikunen の値をそれぞれ表示.
			$body_append_html .= '<tr><th>管理費</th><td class="text-right">' . esc_html( $post->kanrihi ) . '円</td></tr>';
			$body_append_html .= '<tr><th>礼金</th><td class="text-right">' . esc_html( $post->reikin ) . '円</td></tr>';
			$body_append_html .= '<tr><th>築年数</th><td class="text-right">' . esc_html( $post->chikunen ) . '年</td></tr>';
			$body_append_html .= '</table>';

			/************************************
			 * 投稿1件分の 最後に追加
			 * (最初に追加する場合は body_append の部分を body_prepend に変更 ).
			 */
			$options['body_append'] .= $body_append_html;
		}

		return $options;
	},
	10,
	2
);

カスタムフィールドの値など、追加したい要素を変数 $body_append_html に一旦格納して、最後に $options[‘body_append’] に .= で追加しています。
(直接 $options[‘body_append’] に追加していっても特に問題ありません )

この時 $options[‘body_append’] = $body_append_html; のように .= でなくピリオドのない = にしてしまうと、他のフックから追加してある場合にそれを上書きになってしまうので注意してください。

高度な条件分岐を指定する

例えば投稿タイプ post について表示を改変すると、アーカイブページの一覧だけでなく、記事詳細ページの下に表示される「前の記事」「次の記事」の部分にも影響してしまいます。

また、例えば画像つき一覧にはカスタムフィールドの情報を表示したいけれども、投稿リストブロックなどでテキストのみの一覧を指定している時はそのまま表示したいなど、実案件では様々な要件が出てきますので、参考になりそうな例をいくつか紹介します。

ページのタイプでの条件分岐

投稿タイプ post について除外すると、例えば記事詳細の下に表示される「前の記事」「次の記事」の部分にも影響してしまいます。

そこで、例えば以下のように is_single() などの条件を追加して指定します。

		// 投稿タイプ post の時に画像を無しに改変するが、投稿詳細ページでは改変させない.
		if ( 'post' === get_post_type() && ! is_single() ) {
			// $options の 'display_image' の値を上書き
			$options['display_image'] = false;
		}

投稿タイプ post の時に改変するけれど、投稿詳細ページである is_single() の時は除外するという指定をしています。

表示レイアウトでの条件分岐

以下の例では表示レイアウトを基準に条件分岐しています。

		// 投稿タイプ post の時に画像を無しに改変するが、カードインテキストのレイアウトが選択されている場合は改変しない.
		if ( 'post' === get_post_type() && 'card-intext' !== $options['layout'] ) {
			// $options の 'display_image' の値を上書き
			$options['display_image'] = false;
		}

投稿詳細ページの下の「前の記事」「次の記事」の部分は標準ではレイアウトがカードインテキスト( $options[‘layout’] = card-intext ) なので、その場合は除外する指定をしています。

特定のページに配置した投稿リストブロックのみ改変する

通常の運用なら今までの条件分岐で大丈夫なのですが、特定の固定ページや投稿ページに配置した投稿リストブロックだけ変更したいというケースが…ある場合は概ねサイト設計に問題があると思いますが、どうしても必要なケースは無いとは言い切れません。

そういった場合、そのブロックIDを渡すなどのスマートな指定方法は現状ありませんので、既存のパラメーターを使って指定するという美しくない裏技があります。

例えば投稿リストブロックで、ボタンの名前を「特定の投稿リスト」などのようにしておくと、$options[‘btn_text’] の中には ‘特定の投稿リスト’ が入った状態で落ちてくるので、それを基準にして条件分岐を指定します。

		// ボタンの表記が '特定の投稿リスト' の時のみ改変.
		if ( '特定の投稿リスト' === $options['btn_text'] ) {
			// 表示要素を追加.
			$options['body_append'] = '<p class="alert alert-warning">後に追加</p>';
			// ボタンの名前を普通の表記に上書きして戻す.
			$options['btn_text'] = '詳しくはこちら';
		}

実際に表示する時にボタンの表記が「特定の投稿リスト」ではまずいので、$options[‘btn_text’] の中身を普通の文言に上書きして返せば表示上は問題ありません。

うーん、美しくないですが、先に述べた通りこのカスタマイズをしないといけないケース = 情報配置設計自体に問題があるのではないかと思うので、ブロックIDを引数に入れるなどは特に予定していません。

表示される分類を一部非表示にする

『分類』にチェックを入れると、投稿タイプに紐付いているカスタムタクソノミーが全て取得して表示されてしまいます。

例えばカスタム投稿タイプ event に カスタムタクソノミー「イベントカテゴリー(event-cat)」と「地域(area)」がある場合、以下のように表示されます。

タクソノミーの指定


しかしながら、例えば 地域(area)を表示したくない場合などは、表示したくないタクソノミーを以下のように登録すれば除外する事ができます。

// 特定のタクソノミーを非表示にする
add_filter( 'vk_get_display_taxonomies_exclusion', function( $exclusion ){
    // 除外したいタクソノミーのスラッグ(複数ある場合は複数行書いてください)
    $exclusion[] = 'area';
   return $exclusion;
} );

とは言え、非表示にするだけならCSSで非表示にする方が楽だと思います。

.vk_post_taxonomy-area {
    display:none;
}

全要素の差し替え

最後に loop-item.php に直接手書きするのと同様に、完全に独自の要素を書く手順を紹介します。

 /**
 * 投稿一覧画面で表示する投稿情報を差し替える
 *
 * @param array  $html : 1件分の表示部分のHTML
 * @param object $post : 1件分の投稿情報.
 * @param array  $options : 1件分の表示形式に関する設定配列。特定の $options[layout] 指定の時だけ差し替えるなどの条件分岐用
 * @return string $hetm : 差し替えるHTML
 */
add_filter(
	'vk_post_view',
	function( $html, $post, $options ) {

		// 差し替えるHTMLを $html の中に格納していきます.
		$html  = '<article class="col-12">';
		$html .= esc_html( get_the_date() );
		$html .= '<a href="' . get_permalink() . '">';
		$html .= get_the_title();
		$html .= '</a>';
		$html .= '</article>';

		return $html;
	},
	10,
	3
);

この方法だと VK Blocks Pro の投稿リストブロックでも、アーカイブページでレイアウトが改変してあっても差し替わります。

Follow me!

この記事を書いた人

石川栄和代表取締役
名古屋のウェブ制作会社数社に10年程度務めた後、株式会社ベクトル設立。
企画・運営・コンサルティング〜WordPressを中心としたシステム開発まで幅広く携わる。
[ 著書 ]
・いちばんやさしいWordPressの教本(共著)
・現場でかならず使われているWordPressデザインのメソッド(共著)
[ 最近のWordPressコミュニティでの活動 ]
2019 WordCampNiigata セッションスピーカー
2019 WordCampHaneda セッションスピーカー
2018 WordCampOsaka セッションスピーカー
2017 WordCampKyoto セッションスピーカー

リリース記念キャンペーン!
G3 Pro Unit を買って


Evergreen


無料でダウンロードしよう

Lightningで使えるおしゃれなデザインスキン / コンテンツデータを試せるチャンス!