ブログカード機能のカスタマイズ基礎 – Snow Monkey カスタマイズ

本記事は、Snow Monkey のブログカード機能についての詳細と、カスタマイズについて解説します。

最初に

注意

本記事は Snow Monkey v8 以上のみ対応しています。
(Snow Monkey v9.0.10 にて確認しています)

ブログカードとは?

WordPress には Embed という機能が標準で用意されており、ウェブページの URL を貼った時に、対象のウェブページが oEmbed というプロトコルに準拠している場合に、自動的に対象のウェブページのタイトルや詳細を取得します。その結果を変換した上で、リッチなリンク表示を行う仕様になっています。Snow Monkey では、そのリッチなカード表示に変換されたリンク部分のことを「ブログカード」と呼んでいます。

テネーブル

次のように、リッチにカード表示がされているリンク部分がブログカードに当たります。

当ウェブサイトの URL でブログカードを表示した例

ブログカードの表示要素について

テネーブル

正常に変換されて表示されているブログカードには、5つほどの表示要素があります。

ブログカードの5つの要素
  1. タイトル
  2. 説明文
  3. サムネイル画像
  4. ファビコン
  5. ドメイン名

ブログカードを記事で使う方法

次の Snow Monkey公式ウェブサイト のマニュアルページを参考にしてください。

テネーブル

ブロックエディターの場合であれば、[埋め込み] カテゴリーの [埋め込み] ブロックで、URL を記入して [埋め込み] を行うとブログカードに変換されます。または、現在のブロックエディターでは、新しい段落ブロックの場合に URL を貼り付けることでも変換が行われます。
どちらかお好きな方法で行いましょう。

ルミェール

対象のウェブページが oEmbed というプロトコルに準拠していない場合や、特定のエラーを返す場合は、ブロックエディター内でのみ表示がされない場合もあるよ。可能な限り、実際の記事画面で正しくブログカードに変換されているかプレビューなどで確認をするようにしようね。

Snow Monkey のブログカード表示について

リンク先 URL が外部の場合は、WordPress の標準の仕様のままでは正しくブログカードにならない場合が多いです。その為、Snow Monkey テーマでは WP oEmbed Blog Card と言うライブラリを使用され、外部のリンク先 URL でもoEmbed プロトコルに準拠している場合には、可能な限り正しいカード表示に変換される仕組みが備わっています。

WP oEmbed Blog Card ライブラリ – GitHub

Snow Monkey ブログカード表示のパターンについて理解

4パターンのブログカード表示方法

ブログカードの表示パターンは、Snow Monkey 上では次の4つです。

  • ブロックエディター内での表示
  • 取得前、取得時(リンク先 URL の oEmbed を取得する前、取得中)
  • 取得失敗時(通常リンク表示)
  • 取得成功時(ブログカード表示)

4パターン、それぞれ表示されるHTMLについて

ブロックエディター内での表示

ブロックエディター(Gutenberg) のバージョンによっては、埋め込みや埋め込まれた URL によって、いくつかのパターンがあるようです。本記事ではHTML例の紹介を割愛させていただきます。

取得前、取得時

ブログカードを生成する為の情報を取得・読み込み中の場合は、ブログカード中の URL は、次のような HTML に変換されます。

<div class="js-wp-oembed-blog-card">
	<a class="js-wp-oembed-blog-card__link" href="リンク先URL" target="_selfまたは_blank">リンク先URL</a>
</div>

target 要素は、リンク先のURL が同一のサイトであれば _self 、それ以外は _blank となります。

テネーブル

このような HTML 記述を [カスタム HTML] ブロック等で記述した場合でも、自然にブログカードに変換されます。後述の PHP でのブログカード処理が難しい場合、この記述を行って変換をさせるのも、1つのカスタマイズ方法です。

取得失敗時

ブログカードを生成する為の情報を取得することに失敗した場合、通常のリンクとして次のような HTML に変換されます。

<p class="wp-oembed-blog-card-url-template">
	<a href="リンク先URL" target="_blank">リンク先URL</a>
</p>

target 要素は _blank 固定です。

取得成功時

ブログカードを生成する為の情報を取得することに成功した場合、ブログカードが生成され、次のようなHTMLに変換されます。

<div class="wp-oembed-blog-card" data-cached-time="キャッシュ時間">
	<a href="リンク先URL" target="_selfまたは_blank">
		<div class="wp-oembed-blog-card__figure">
			<img src="サムネイル画像URL" alt="">
		</div>
		<div class="wp-oembed-blog-card__body">
			<div class="wp-oembed-blog-card__title">
				リンク先の記事タイトル
			</div>
			<div class="wp-oembed-blog-card__description">
				リンク先の説明文字列(160文字で…省略)
			</div>
			<div class="wp-oembed-blog-card__domain">
				<img class="wp-oembed-blog-card__favicon" src="リンク先のファビコンのURL" alt="">
				リンク先のドメイン
			</div>
		</div>
	</a>
</div>

target 要素は、リンク先 URL が同一のサイトであれば _self、それ以外は _blank となります。
サムネイル画像が存在しない場合は、 wp-oembed-blog-card__figure クラスの div タグは出力されません。
ファビコンが存在しない場合は wp-oembed-blog-card__favicon クラスの img タグは出力されません。

ブログカード表示をカスタマイズしてみよう

テンプレート置換ではない表示カスタマイズ

ブリエ

4つの表示パターンもあり、ブログカードは何処にでも貼ることが可能なので、カスタマイズに難しいイメージを感じちゃう…。

テネーブル

ブログカードの表示カスタマイズも、Snow Monkey v8 以降はテーマで用意されている独自フックを使用してカスタマイズが可能になっていますので少し簡単になりました。

取得前、取得時の表示をカスタマイズする為には

snow_monkey_oembed_blog_card_loading_template と言うフィルターフックが用意されています。
渡される引数は HTML と URL となり、返却値には HTML を渡します。

標準のブログカードを表示する HTML であれば 次のような形になります。

add_filter(
	'snow_monkey_oembed_blog_card_loading_template',
	function( $html, $url ) {
		if ( 0 === strpos( $url, home_url() ) ) {
			$target = '_self';
		} else {
			$target = '_blank';
		}
		return sprintf(
			'<div class="js-wp-oembed-blog-card"><a class="js-wp-oembed-blog-card__link" href="%1$s" target="%2$s">%1$s</a></div>',
			esc_url( $url ),
			esc_attr( $target )
		);
	},
	10,
	2
);

このコードをベースにカスタマイズをすると良いでしょう。

テネーブル

カスタマイズする場合は、class 名を追加する等のカスタマイズに留めておく必要もあります。oEmbed 情報が正しく取得された状態に、ブログカード表示に正常に切り替わらなくなってしまう場合があるからです。特に js-wp-oembed-blog-card などの class 部分は変更しないように注意してください。

ルミェール

Snow Monkey 公式の情報でも「※ただし、.js-wp-oembed-blog-card 、.js-wp-oembed-blog-card__link がないと正しく動作しない場合があるので注意してください。」と記載されているよ。

取得失敗時の表示をカスタマイズする為には

snow_monkey_oembed_blog_card_url_template と言うフィルターフックが用意されています。渡される引数は HTML と URL となり、返却値には HTML を渡します。

標準のブログ表示 HTML であれば、次のようなコードになります。

add_filter(
	'snow_monkey_oembed_blog_card_url_template',
	function( $html, $url ) {
		return sprintf(
			'<p class="wp-oembed-blog-card-url-template"><a href="%1$s" target="_blank">%1$s</a></p>',
			esc_url( $url )
		);
	},
	100,
	2
);

このコードをベースにカスタマイズをすると良いでしょう。

テネーブル

注意することとして、ブログカードの変換処理を正常に行う為に wp-oembed-blog-card-url-templateclass 部分を変更しないようにしましょう。

取得成功時の表示をカスタマイズする為には

snow_monkey_oembed_blog_card_template と言うフィルターフックが用意されています。
渡される引数は、HTML と 「取得された Embed 情報配列」となり、返却値には HTML を渡します。

標準のブログ表示 HTML であれば、下記のような形になります。

<?php
add_filter(
	'snow_monkey_oembed_blog_card_template',
	function( $html, $cache ) {
		$url = '';
		preg_match( '/<a href=\"(.*?)\".*?>/mis', $html, $matches );
		if ( is_array( $matches ) && 1 <= count( $matches ) ) {
			$url = $matches[1];
		}
		if ( 0 === strpos( $url, home_url() ) ) {
			$target = '_self';
		} else {
			$target = '_blank';
		}
		$cached_time = isset( $cache['cached_time'] ) ? date_i18n( 'd/m/y H:i:s', $cache['cached_time'] ) : null;
		ob_start();
?>
		<div class="wp-oembed-blog-card" data-cached-time="<?php echo esc_attr( $cached_time ); ?>">
			<a href="<?php echo esc_url( $url ); ?>" target="<?php echo esc_attr( $target ); ?>">
				<?php if ( $cache['thumbnail'] ) : ?>
					<div class="wp-oembed-blog-card__figure">
						<img src="<?php echo esc_url( $cache['thumbnail'] ); ?>" alt="">
					</div>
				<?php endif; ?>
				<div class="wp-oembed-blog-card__body">
					<div class="wp-oembed-blog-card__title">
						<?php echo esc_html( $cache['title'] ); ?>
					</div>
					<div class="wp-oembed-blog-card__description">
						<?php
						if ( function_exists( 'mb_strimwidth' ) ) {
							echo esc_html( mb_strimwidth( $cache['description'], 0, 160, '…', 'utf-8' ) );
						} else {
							echo esc_html( $cache['description'] );
						}
						?>
					</div>
					<div class="wp-oembed-blog-card__domain">
						<?php if ( $cache['favicon'] ) : ?>
							<img class="wp-oembed-blog-card__favicon" src="<?php echo esc_url( $cache['favicon'] ); ?>" alt="">
						<?php endif; ?>
						<?php echo esc_html( $cache['domain'] ); ?>
					</div>
				</div>
			</a>
		</div>
<?php
		return ob_get_clean();
	},
	100,
	2
);

このコードをベースにしてカスタマイズをすると良いでしょう。

テネーブル

$cache 配列の要素は、次の一覧を参考にしてください。

説明
titleタイトル
thumbnailサムネイル画像URL
description説明、抜粋
faviconファビコン画像URL
domainドメイン

wp-oembed-blog-card クラスが付与される

Snow Monkey のテーマでは、前述のフックを利用し class の文字置換が行われています。

class="js-wp-oembed-blog-card"class="js-wp-oembed-blog-card wp-oembed-blog-card" に置換されます。

class="wp-oembed-blog-card-url-template"class="wp-oembed-blog-card-url-template wp-oembed-blog-card" に置換されます。

その理由から前述したフック例は、優先度を 100 とし、class の置換処理より前に処理を行うように設定しています。

テネーブル

Snow Monkey テーマの場合は、スタイルを設定する場合は、 wp-oembed-blog-card と言う class も付与されると言うのを考慮しましょう。

記事以外にブログカードを直接使用する方法

テネーブル

例えば、「404 Not Page Found」ページの場合、ブログカードを使って移転後の記事を表示するとかの場合。PHP で直接ブログカードを呼び出す方法もあります。

PHPで使用する場合は、下記のように記述を行います。

use Inc2734\WP_OEmbed_Blog_Card;

$_url = 'ブログカード表示を行いたいリンク先URL';
$_blog_card_html = '<a href=' . $_url . '>' . $_url . '</a>';
$_blog_card = new WP_OEmbed_Blog_Card\Bootstrap();
if ( method_exists( $_blog_card, '_embed_html_for_no_oembed' ) ) {
	$_blog_card_html = $_blog_card->_embed_html_for_no_oembed( null, $_url );
}
echo $_blog_card_html;
テネーブル

WP OEmbed Blog Card を使用する為に、まず名前空間の Inc2734\WP_OEmbed_Blog_Card を使用するように設定します。

WP_OEmbed_Blog_Card\Bootstrap() で、ブログカードのクラスをインスタンス化します。

_embed_html_for_no_oembed 関数には、第1引数は内部で使用されていませんので null で問題ありません。第2引数は、リンク先のURL になります。

このコードが処理された場合、取得成功時または取得失敗時の HTML が返却されます。処理は非同期で実行される為、返却される変数はブログカード表示とは別に通常の a タグで初期化しておくと良いです。

メソッド名の存在チェックの必要性について

第1回の Snow Monkey ミートアップで、Snow Monkey 開発者のキタジマタカシ氏から

タカシ

ソースコードを修正や整理してると、メソッド名が変わるのはライブラリでは度々あるので、メソッド存在チェック(method_exists)は書いておいた方が良いです。ほとんど落ち着いてきたけど、ブログカードの場合は WordPress の仕様に合わせて今後も変更する可能性あります。

とのことです。

現在開発されているライブラリでは、メソッド名の変更に関してほぼ無くなってきていますが、WP oEmbed Blog Card では WordPress の Embed 機能の仕様変更に合わせて、ライブラリの仕様も変更される場合もあります。その為、ブログカードのライブラリを使用する場合は、メソッド存在チェックなどを行う方が良いでしょう。

ルミェール

実際に _embed_html_for_no_oembed は、以前 _wp_embed_handler と言うメソッド名だったけど、現在のバージョンには存在しなくなってるよ。

ライブラリが格納されているディレクトリについて

ブリエ

解説されている WP oEmbed Blog Card ライブラリは、Snow Monkey テーマの何処に格納されているんだろう?

Snow Monkey テーマでは、

snow-monkey (Snow Monkey テーマルートディレクトリ)

vendor

inc2734

wp-oembed-blog-card

のディレクトリに WP oEmbed Blog Card ライブラリが格納されています。

assets ディレクトリには、ブログカードに使用されるスクリプトやスタイルシートが格納されています。ブログカードの動作や表示スタイルを変更する場合には、このディレクトリ内のリソースを参考にすると良いでしょう。

ルミェール

テーマの標準動作に影響を及ぼす場合もある為、vendor ディレクトリ内の下位リソースは上書きしないようにしようね!

まとめ

ケミ

当ウェブサイトの「404 Page Not Found」の際に、移動先のURL候補をブログカード表示される場合があります。この機能は、この記事で解説していることで実現可能です。

興味がある方は、是非、挑戦してみてください。

この記事の筆者

Kmix39(ケミ)

電子の妖精。当ウェブサイトの記事制作などを行なっています。
金融・不動産・医療・教育などの数々の業種のシステム開発を経験を積み、スマートフォンアプリケーションと WordPress などのウェブアプリケーションを日々勉強中。