Snow Monkey Forms のフックをまとめてみました

2022年12月19日:snow_monkey_forms/administrator_mailer/skip の説明を追記しました
2024年2月24日:新しいフックの紹介をしていただいているページの紹介を追記しました

この記事は、Snow Monkey / unitone Advent Calendar 2022 の18日目の記事です。

「Snow Monkey」といえばテーマを思い浮かべる方が多いと思いますが、私が推したいのはコンタクトフォームプラグイン「Snow Monkey Forms」です。

確認画面・プログレストラッカーが標準装備というのが特長として挙げられることが多いですが、ブロックエディターベースの管理画面は設置の際にミスが起きづらく、設定項目が絞られているので導入のハードルが低く、ウェブ知識が無い方でも運用しやすいのがメリットだと思います。

しかし、設定項目が絞られているということは細かい設定ができないということでもあります。

そこで採用されているのが、Snow Monkey テーマと同じくフックによるカスタマイズ手法です。
Snow Monkeyテーマのように、様々なフックが用意されていてカスタマイズが可能になっています。

ただ・・・
フックの説明がまとまっていないことと、個々のフックの説明記事が Snow Monkey サブスクリプションユーザー限定記事であることから、有効に使われていないようです。

そこで、Snow Monkey Forms のフックを逆引きで探せるようにまとめてみました。
子テーマの functions.php または My Snow Monkeyプラグインに記述してください。

記載したコードは動作確認をしていますが、お使いの環境では動作しないことがあるかもしれません。
実案件に使用する場合は、十分にテストを行ってくださいね。

Snow Monkey Forms のフックいろいろ

送信が完了したときに表示されるメッセージをカスタマイズしたい
例)送信完了画面に表示するメッセージを動的に変えたり、入力項目を表示させたりしたい

snow_monkey_forms/complete/message

送信完了画面に表示するメッセージはフォームの設定画面の「完了画面」のところで設定できますが、これを動的に変えることができます。

return に表示したいものを設定します。
「完了画面」欄で設定したメッセージ(出力されるHTML)は $message で取得できます。
フィールドの入力値は、$responser->get( 'フィールドのNAME値' ); で取得できます。
フォームの設定値は、$setting->get_control( '設定項目のNAME値' ) で取得できます。

/*
 * 完了画面欄で設定したメッセージの前にお名前を表示する
 */
add_filter(
	'snow_monkey_forms/complete/message',
	function( $message, $responser, $setting ) {
		$data = '<p>' . $responser->get( 'fullname' ) . '様</p>'.$message;
		return $data;
	},
	10,
	2
);

システムエラー画面に表示されるメッセージをカスタマイズしたい
例)送信エラー時に表示されるエラーメッセージを任意のものに変えたい

snow_monkey_forms/system_error/message

return に表示したいものを設定します。

$message は Snow Monkey Forms のプログラムに記述されているデフォルトメッセージです。
フィールドの入力値は、$responser->get( 'フィールドのNAME値' ); で取得できます。

なお、デフォルトメッセージは英語で記述されていて翻訳で日本語になっていますので、単純にメッセージを変えたいだけであれば翻訳を変える方法もあります。

/*
 * システムエラー時、デフォルトメッセージの後にメール送信先を表示する
 */
add_filter(
	'snow_monkey_forms/system_erro/message',
	function( $message, $responser ) {
		$data = $message . '<p>メール送信先は "' . $responser->get( 'email' ) . ' "です。</p>';
		return $data;
	},
	10,
	2
);

バリデーションエラーメッセージを書き換えたい
例)入力項目に合わせてメッセージを変えたい

snow_monkey_forms/validator/error_message

Snow Monkey Forms のバリデーションは「必須」しかありませんが、その「必須」がエラーになったときのメッセージを変更できます。

なお、デフォルトメッセージは英語で記述されていて翻訳で日本語になっていますので、単純にメッセージを変えたいだけであれば翻訳を変える方法もあります。

$name は変更したいフィールドのNAME値です。
バリデーションは「必須」しかありませんので、$validation_name'required' 固定になります。

/*
 * 項目ごとにエラーメッセージを変える
 */
add_filter(
	'snow_monkey_forms/validator/error_message',
	function( $error_message, $validation_name, $name ) {
		if ( 'required' === $validation_name && 'fullname' === $name ) {
			return 'お名前は必須です';
		}
		if ( 'required' === $validation_name && 'email' === $name ) {
			return 'メールアドレスは必須です';
		}
		return $error_message;
	},
	10,
	3
);

各フォーム項目に初期値を設定したい
例)フォームに移動する元のページタイトルをフィールドに設定したい

snow_monkey_forms/control/attributes

フォームの項目の設定で value に初期値を設定しておくことができますが、これを動的に設定することができます。

フォームページへのリンクにクエリを付加しておき、それを取得して反映させる方法がよく使われます。
下記のコードでは、お問い合わせページへのリンクURLに元ページのIDを付加しておき( /contact/?page_id=1234 とか)、クエリパラメーターからページのタイトルを取得して refererフィールドの初期値に設定します。

クエリパラメーターには悪意のあるスクリプトを含められてしまう危険性がありますので、必ずサニタイズしてください。
下記のコードでは filter_input 関数を使用しています。

<!-- このページのIDが1234だとして、そのIDをクエリパラメーターとして指定する -->
<a href="/contact/?post_id=1234">お問い合わせはこちら</a>
/*
 * リンクURLに含まれるページIDからリンク元のページタイトルを取得して NAME値がrefererのフィールドに設定する
 */
add_filter(
	'snow_monkey_forms/control/attributes',
	function( $attributes ) {
		// name値が referer という名前のブロック
		if ( isset( $attributes['name'] ) && 'referer' === $attributes['name'] ) {
			// ?post_id という URL クエリがあるとき
			$post_id = filter_input( INPUT_GET, 'post_id' );
			if ( ! is_null( $post_id ) ) {
				// ?post_id で指定された投稿のタイトルを初期値として設定
				$attributes['value'] = get_the_title( $post_id );
			}
		}
		return $attributes;
	}
);

メールタグとして用意されていない情報を取得してメールに埋め込みたい
例)送信された日時やIPアドレスなどを取得したい

snow_monkey_forms/custom_mail_tag

有名なフォームプラグイン「Contact Form 7」では特別なメールタグとして送信者情報、ページ情報などを取得できるようになっていますが、Snow Monkey Forms には用意されていません。

管理者宛メールに、送信された日時・送信者IPアドレスなどの項目を入れたいという要望は多いと思います。
特にスパム対策には有効です。

Snow Monkey Forms では用意されていない情報を取得して、独自のメールタグを定義してメールに埋め込むことができます。
ただし情報取得は自分でコードを書く必要があります。

メールタグは {タグ名} としてメールに埋め込みます。
下記のコードでは、送信日付を {date} で埋め込めるようにします。

/*
 * {date}タグが使用されていたら現在の日付を取得して返す
 */
add_filter(
	'snow_monkey_forms/custom_mail_tag',
	function( $value, $name ) {
		if ( 'date' === $name ) {
			return date('Y-m-d');
		}
		return $value;
	},
	10,
	2
);

管理者あてのメールの設定を変更したい
例)選択肢によってメールの送信先を変えたい

snow_monkey_forms/administrator_mailer/args

例えば、お問い合わせの内容によってメールの送信先を変更したりできます。

$argsが設定値です。
$respomserでフォームの入力値が扱えます。
$settingでフォームの設定値が扱えます。

チェックボックスで選んだ送信先にメールを送信するには下記のようにします。
例えば、チェックボックスの name'multiple-to' として、value にメールアドレスを指定します。
フォームのチェックボックスでチェックした送信先(複数可)に管理者あてメールが送信されます。
チェックしないとフォーム設定の送信先に送信されます。

チェックボックス 'multiple-to' の value

'kawai@cherrypieweb.com':'川井'
'tanaka@cherrypieweb.com':'田中'
'suzuki@cherrypieweb.com':'鈴木'
/*
 * チェックボックスの値をメール送信先に設定する
 */
add_filter(
	'snow_monkey_forms/administrator_mailer/args',
	function( $args, $responser, $setting ) {
		if ( $responser->get( 'multiple-to' ) ) {
			$args['to'] = implode(',', $responser->get( 'multiple-to' ) );
		}
		return $args;
	},
	10,
	2
);

こちらの記事もわかりやすいです。

ユーザーあての自動返信メールを送信しない
例)アンケートなど、ユーザーに返信メールを送るまでもない場合

snow_monkey_forms/auto_reply_mailer/skip

trueを返すとユーザーあての自動返信メールを送信しません。
(内部的にはユーザーあての自動返信メールが送信されたものとして扱われます)

add_filter(
	'snow_monkey_forms/auto_reply_mailer/skip',
	'__return_true'
);

管理者宛メールを送信しない
例)外部のASPにデータをとばして管理したい

snow_monkey_forms/administrator_mailer/skip

trueを返すと管理者あての自動返信メールを送信しません。
(内部的には管理者あての自動返信メールが送信されたものとして扱われます)

実は私にはちょっと使い道がわからなかったのですが、Slackでキタジマさんに伺ったところ、例えば外部のASPにデータをとばして管理するといった用途を想定されているそうです。
(後述の snow_monkey_forms/administrator_mailer/after_send フックを使うということになるのでしょうか?)

実際に使われている方がいらっしゃったら教えていただけると嬉しいです。

add_filter(
	'snow_monkey_forms/administrator_mailer/skip',
	'__return_true'
);

ユーザーあての自動返信メールの送信処理にかかわらず、送信結果を変更したい

snow_monkey_forms/auto_reply_mailer/is_sended

falseを返すと内部的にはユーザーあての自動返信メールの送信が失敗されたものとして扱われます。
実際のメール送信処理には影響しません。

実はちょっと使い道がわかりません。デバッグ用なのでしょうか?

add_filter(
	'snow_monkey_forms/auto_reply_mailer/is_sended',
	'__return_false'
);

管理者あての自動返信メールの送信処理にかかわらず、送信結果を変更したい

snow_monkey_forms/administrator_mailer/is_sended

falseを返すと内部的には管理者あての自動返信メールの送信が失敗されたものとして扱われます。
実際のメール送信処理には影響しません。

実はちょっと使い道がわかりません。デバッグ用なのでしょうか?

add_filter(
	'snow_monkey_forms/administrator_mailer/is_sended',
	'__return_false'
);

メールヘッダーをカスタマイズしたい
例)管理者あてメールに CC, BCC を設定したい

(管理者あてメール)
snow_monkey_forms/administrator_mailer/headers

(ユーザーあてメール)
snow_monkey_forms/auto_reply_mailer/headers

(共通)
snow_monkey_forms/mailer/headers

メールヘッダーの書式に従ってカスタマイズ内容を記述します。
メールの件名も変更できます。

フィールドの入力値は、$responser->get( 'フィールドのNAME値' ); で取得できます。
フォームの設定値は、$setting->get_control( '設定項目のNAME値' ) で取得できます。

/*
 * 管理者あてメールとユーザーあてメールにCc, Bcc, Reply-to を指定する
 */
add_filter(
	'snow_monkey_forms/mailer/headers',
	function ($headers, $responser, $setting) {
		return [
			'Cc: cc@example.com',
			'Cc: cc2@example.com',
			'Bcc: bcc@example.com',
			'Bcc: bcc2@example.com',
			'Reply-to: rpy@example.com',
		];
	}
);

その他のフック

本記事公開後に追加されたフックについて使い方を記載していただいているページがありますのでご紹介いたします。

Snow Monkey Formsのフックを調べた #WordPress – Qiita

snow_monkey_forms/administrator_mailer/after_send、snow_monkey_forms/auto_reply_mailer/after_send を使うと、送信されたメールの内容を保存することができそうです。

フックを使いこなすために

実際のところ、自分でフックを探して使いこなすというのはかなり難しいと思っています。
私も、使えそうなフックを見つけても使えるまで試行錯誤に何時間もかかったり、結局うまく使えなかったりしています。
サンプルコードを見ても、それを自分がやりたいように応用をきかせるのは難しいですよね。

せっかくのすばらしいフォームプラグイン「Snow Monkey Forms」ですし、カスタマイズ記事がもっともっと公開されていくといいなと思います。

この記事を書いた人

川井 昌彦
川井 昌彦
FAシステムメーカー、国内最大手印刷会社製版部、印刷・ウェブ制作会社を経て、家庭の事情で実家に帰省して独立
現在はフリーランスと制作会社シニアディレクターのマルチワーク
ウェブ制作のほぼ全般を見渡せるディレクター業務が主だが、デザイン・コーディングも好き

1997年ブログ開設
WordPressコミュニティには2011年から参加
WordCamp Kansai 2016 セッションスピーカー
WordCamp Tokyo 2023 パネルディスカッションパネラー
WordBench京都、WordBench神戸、WordPress Meetup八王子など登壇多数

コメントを残す

メールアドレスが公開されることはありません。 が付いている欄は必須項目です

Vektor Passport(ライセンス期間1年)
VK Filter Search Pro
Vektor WordPress Solutions
PAGE TOP