独自のフォームタグを追加する

Posts in the developer's cookbook category describe topics that require technical knowledge. Be warned and use the techniques at your own risk. Unless you are an experienced developer, you are strongly advised to ask a professional for support.

This page is also available in English.

本稿は Contact Form 7 をカスタマイズしたい開発者に向けた「開発者の料理本」シリーズの第一弾です。

最初のトピックとして Contact Form 7 のフォームタグの拡張を取り上げます。すでにご存じと思いますがフォームタグとは角括弧に囲まれる特定のフォーマットに従うコードで、通常はテキスト入力項目や送信ボタンなどのフォームコントロールを表現するものです。現在 Contact Form 7 は30種のフォームタグを標準でサポートしています。

これらは典型的なフォームタグの例です:

[text* your-name]
[textarea your-message]
[submit "Send"]

WordPress のショートコードに似ていますが、ショートコードとは異なりフォームタグは Contact Form 7 のフォーム領域でのみ機能します。

標準サポートのフォームタグに加えて独自のフォームタグを作成することも可能です。独自フォームタグの追加に必要な手順が二つあります: (1) フォームタグのタイプとそれに関連づけられるコールバック関数を登録する、(2) コールバック関数を定義する。それぞれの手順について見ていきましょう。

wpcf7_add_form_tag

フォームタグのタイプを登録するには wpcf7_add_form_tag() 関数を呼び出します。wpcf7_add_form_tag() は3個の引数(2個の必須値と1個のオプション)を受け取ります。

第一引数は文字列値で、タグのタイプを示します。フォームタグの最初の単語がそのタイプです。上の例では “text*”、“textarea”、“submit” がタイプです。フォームタグのタイプには小文字のアルファベット ([a-z])、数字 ([0-9])、アンダースコア (“_“)、アスタリスク (“*“) が利用できます。末尾にアスタリスクが付いたタグタイプ (例: “text*”、”email*”) は慣習的に必須入力項目に使われます。

2種類以上のフォームタグタイプが同一のコールバック関数を共有する場合はそれらを一緒に登録できると手間が省けます。そういう場合は文字列値で構成される配列を第一引数として指定します。

第二引数は Contact Form 7 がフォームタグをパースする際に呼び出されるコールバック関数です。コールバック関数については後で詳しく説明します。

任意指定の第三引数はフォームタグタイプでサポートされる「特徴」の配列です。例を挙げると、名前の部分を持つフォームタグのタイプは name-attr という特徴をサポートする、といった具合です。

フォームタグ中の二番目の単語がそのフォームタグの「名前」です。上の例で言えば、“your-name” と “your-message” が名前です。[submit "Send"] のように名前を持たないフォームタグもあります。

name-attr をサポートするフォームタグタイプには wpcf7_add_form_tag() の第三引数として array( 'name-attr' => true ) を渡します。

wpcf7_add_form_tag() の呼び出しは wpcf7_init アクションフックのタイミングで行う必要があります。参考までに、Contact Form 7 がデフォルトのフォームタグを登録する様子を見てみましょう。

add_action( 'wpcf7_init', 'wpcf7_add_form_tag_text' );

function wpcf7_add_form_tag_text() {
  wpcf7_add_form_tag(
    array( 'text', 'text*', 'email', 'email*', 'url', 'url*', 'tel', 'tel*' ),
    'wpcf7_text_form_tag_handler',
    array( 'name-attr' => true )
  );
}

コールバック関数

次の手順はコールバック関数の定義です。この関数は WPCF7_FormTag オブジェクトを唯一の引数として受け取ります。WPCF7_FormTag オブジェクトは実際のフォームタグから得られる情報、つまりそのタイプ、名前、オプション、値、等々を表現するものです。

このコールバック関数は必ず一つのテキスト値を返します。このテキスト値は通常、フォームコントロールを表す HTML 断片です。Contact Form 7 がフォームタグを含んだフォームテンプレートを元に実際のフォームを生成する時に、対応するフォームタグを置き換えるのにこの返り値のテキストが用いられます。

デモンストレーションとして、現在の時刻を表示する単純なフォームタグを作ってみましょう (“[clock]” ととりあえず呼ぶことにします)。

次のコードを適当な場所に追加してみてください。こういった小規模のカスタムコーディングはテーマの functions.php で行うことを好む開発者が多いと思いますがべつにどこでも構いません。プラグインのフォルダ (contact-form-7) 内のファイルを直接編集するのは避けてください。プラグインを破壊してしまうかもしれませんし、次にプラグインが更新された時にあなたのカスタムコードは失われることになるからです。

add_action( 'wpcf7_init', 'custom_add_form_tag_clock' );

function custom_add_form_tag_clock() {
  wpcf7_add_form_tag( 'clock', 'custom_clock_form_tag_handler' ); // "clock" is the type of the form-tag
}

function custom_clock_form_tag_handler( $tag ) {
  return date_i18n( get_option( 'time_format' ) );
}

それが済んだら今度は次の一行をフォームテンプレートに追加します:

Current Time: [clock]

正しく機能すれば、フォーム内に次のような一行が表示されるはずです:

Current Time: 12:16 pm

以上です。今回の “[clock]” のデモは明らかに単純すぎて実用には使えませんが、Contact Form 7 のフォームタグの概念を示すのには十分でしょう。実用に耐えられるよう改良するために習得するべきことは:

フォームタグの構成要素から抽出した情報を使ってより複雑なフォームコントロールを構築する方法。
ユーザー入力を検証し、入力が不正の場合には検証エラーを表示する方法。

次回以降のレシピではそれらの領域について取り上げられる予定です。

Contact Form 7