« EUC-JP 使用時にドキュメントエイリアスの設定ができない | メイン | cfFormMailer v0.0.7リリース »

cfFormMailer マニュアル v0.0.7.1

cfFormMailer マニュアル v0.0.7

MODx 用日本語メールフォーム作成スニペット「cfFormMailer」の利用解説です。

設置&使用方法

下準備

  1. /assets/snippets/ フォルダ内に cfFormMailer というフォルダを作成し、そのフォルダ内に以下のファイルを配置します。
    • class.cfFormMailer.inc.php
    • class.cfFormMailerMODx.inc.php
  2. MODxの管理画面にログインし、[リソース]-[リソース管理]-[スニペット]タブ-[スニペットの作成]をクリックして、スニペットを新規作成します。
    スニペット名に cfFormMailer と入力し、スニペットコード欄にファイル snippet.cfFormMailer.php の内容をコピー&ペーストします。
  3. [リソース]-[リソース管理]-[チャンク]タブ-[チャンクの作成]から、「環境設定」として利用するチャンクを任意の名称で作成し、チャンクコードにまずは chunk_sample フォルダ内の tmpl.chunk_config.txt の内容をコピー&ペーストします。
    その後、各設定項目の値をご利用の環境に合わせて書き換え、保存してください。
    # で始まる行はコメントですので、これを参考にしてください。
  4. [リソース]-[リソース管理]-[チャンク]タブ-[チャンクの作成]から、「入力画面」「確認画面」「完了画面」「管理者宛メール」「自動返信メール」の各テンプレートとして使用するチャンクを任意の名称で作成します。
    それぞれのチャンクコードは、chunk_sample フォルダ内にあるテンプレートサンプルを参考に記述し、保存してください。

旧バージョンからのアップグレード

v0.0.3, v0.0.4 → v0.0.7
assets/snippets/cfFormMailer 内の2ファイルと、MODx 内スニペットを置き換える。
環境設定チャンクは従来のものがそのまま使用できます。ですが、設定項目が増えていますので、上記手順3 で最新のものに変更することをお勧めします。

書式

cfFormMailer を配置したいドキュメント内に以下のようなスニペットコードを書きます。

[!cfFormMailer?&config=`config_chunk`!]

config パラメータは必須で、【下準備】手順3で作成した「環境設定チャンク」の名称を指定します。

機能解説

自動返信

環境設定チャンク内の auto_reply を 1 、reply_to にメールアドレスとして使用するフィールド名を指定することで、"管理者"宛のメールのほかにフォーム送信者に対して自動返信を行うことができます。

※1 reply_to で指定したフィールドは正しいメールアドレス形式かどうかをチェックされます。
※2 reply_to は、1つのフィールド名、または複数のフィールド名を + 記号で繋げて指定します。

reply_to = email             //name="email" のフィールド値を宛先として使用
reply_to = email1+@+email2   //name="email1"のフィールド値+アットマーク+name="email2"のフィールド値を宛先として使用

画像認証コード(CAPTCHA)の使用

v0.0.5 から画像認証コードが利用できるようになっています。
環境設定チャンク内で CAPTCHA 使用を宣言し(vericode = 1)、以下の例のような、src 属性に [+verimageurl+] プレースホルダを指定した<img>タグと、検証項目に vericode を指定した<input>タグを、に入力画面チャンク内に作成します。

[例] <img src="[+verimageurl+]" alt="認証コード" /><input type="text" name="veri" valid="1:vericode" />

※MODx 本体と同じクラスを利用するため、画像として表示される文字列は [ツール]>[MODx設定]>[ユーザ]タブ の「CAPTCHAワード」と同様になります。

入力値の検証

フォーム内の各フィールドに対して、入力値の検証を行うことができます。
検証の結果、誤りがあった場合は後述の"追加タグ"を使用してエラーメッセージを表示させることができます。

また、v0.0.6以降では、環境設定チャンク内 invalid_class パラメータを指定することで、誤りのあるフィールドに任意のクラスセレクタが付加されます。

書式

<input type="text" name="field_name" value="" valid="required:method:other_param" />
required
入力必須項目(1-yes / NULL-no)
method
検証項目。コンマ区切りで複数指定可。以下の標準装備の方式以外にも、独自の方式も指定可能。(下記「検証メソッドの追加」参照。)
email
メールアドレスチェック(※半角に強制変換)
num
数値チェック(※半角に強制変換)
len(n-m)
文字数チェック(m文字以下 | n~m文字 | n文字以上)
range(n~m) NEW in v0.0.5
数値の値範囲チェック(m以下 | n~m | n以上)※n,mで指定した数値は範囲に含まれます
sameas(フィールド名) NEW in v0.0.6
「フィールド名」で指定したフィールドと同値かをチェック。
tel NEW in v0.0.7
正しい電話番号形式かどうかをチェック(※半角に強制変換)
vericode NEW in v0.0.5
画像認証
other_param
その他(未実装)

使用例

この項目は入力必須であり、数字(0-9)のみ入力を許可する
<input type="text" name="age" size="3" valid="1:num" />
8文字以内で入力させる
<input type="text" name="pass" size="10" valid=":len(-8)" />
10文字以上12文字以内の数値のみ許可する
<input type="text" name="tel" size="10" valid=":num,len(10-12)" />
20歳以上のみ許可する
<input type="text" name="age" size="4" valid="1:num,range(20~)" />
同じパスワードを2回入力させる
<input type="password" name="password" size="10" valid="1" />
<input type="password" name="password_confirm" size="10" valid="1:sameas(password)" />

以上で挙げた検証の他に、「自動返信」を使用する場合は"自動返信先"(reply_to)がメールアドレスとして正しいかどうかを必ずチェックします。(v0.0.7以降)
また、これにより自動的にフィールド reply_to が作成されますので、エラーメッセージ表示の際のフィールド名として利用できます。(下記参照)

追加タグ

主にエラーメッセージ表示用に、以下の独自タグをサポートしています。

<iferror></iferror>
エラーが存在する場合にタグ内を表示
<iferror.フィールド名></iferror>
指定したフィールドにエラーが存在する場合にタグ内を表示
<iferror.(f1,f2[,f3...])></iferror>
f1またはf2(またはf3...。すべてフィールド名)項目にエラーが存在する場合にタグ内を表示

プレースホルダ

テンプレートチャンク内に記述することで、特定の値を挿入できます。なお、一部のテンプレートチャンク内でのみ使用可能となるプレースホルダもあります。

[+フィールド名+]
フィールド名に対応するフォーム値
[+error.フィールド名+]
指定したフィールドに割り当てられているエラーメッセージ
(エラーメッセージが複数割り当てられている場合、<br />タグで区切って表示。下記「表示フィルタ」を使用して変更することも可能。)
[+errors+]
全てのエラーを表示(初期値は<br />区切り。下記「表示フィルタ」で変更可能。)
<input>タグや<select>タグに対して適切に<label$>タグを使用することで、エラーのあるフィールド名が<label>タグで囲まれた表記で表示されます。
[例] <label for="name">お名前</label><input type="text" name="name" valid="1" id="name" />
→ [お名前]入力必須項目です
[+verimageurl+] NEW in v0.0.5
画像認証コードとして使用する画像の URI

以下は「管理者宛メール」「自動返信メール」テンプレートチャンク内でのみ使用できます。

[+adminmail+]
管理者メールアドレス(環境設定の admin_mail と同値)
[+reply_to+] NEW in v0.0.7
自動返信の宛先メールアドレス
[+senddate+]
送信日時(デフォルト書式: Y-m-d H:i:s。下記「表示フィルタ」の dateformat を利用して変更可能。)
[+sender_ip+] NEW in v0.0.6
送信者のIPアドレス
[+sender_host+] NEW in v0.0.6
送信者のホスト名(逆引きできない場合は IPアドレス)
[+sender_ua+] NEW in v0.0.6
送信者のユーザーエージェント

表示フィルタ

上記プレースホルダの出力に対して任意のフィルターをかけることが可能。

書式

[+プレースホルダ名|フィルタ名(パラメータ)+]
プレースホルダ名
プレースホルダ名(上記「プレースホルダ」参照)
フィルタ名、パラメータ
適応させるフィルタ名とパラメータ(任意)。標準では以下のフィルタを備えています。
implode(string) string で区切って表示 ※該当フィールドが配列の場合のみ有効。
implodetag(string) 値を<string></string>タグで囲んで表示 ※該当フィールドが配列の場合のみ有効。
dateformat(format) format に従い日付書式を変換 ※PHP関数 strftime() と同様。
num 数字をフォーマット ※PHP関数 number_format() と同様。ただし第2引数以降は未対応。
sprintf(format) 整形して表示 ※PHP関数 sprintf() と同様。

  • [+errors+] (フィルタを指定しない場合)

    出力: [お名前:]入力必須項目です<br />[メールアドレス:]メールアドレスの形式が正しくありません<br />[性別:]入力必須項目です

  • [+errors|implode( / )+]

    出力: [お名前:]入力必須項目です / [メールアドレス:]メールアドレスの形式が正しくありません / [性別:]入力必須項目です

  • <ul>[+errors|implodetag(li)+]</ul>

    出力: <ul><li>[お名前:]入力必須項目です</li><li>[メールアドレス:]メールアドレスの形式が正しくありません</li><li>[性別:]入力必須項目です</li></ul>

検証メソッドの追加

以下の仕様に則った関数を使用して、任意の検証メソッドを追加することができるます。

関数仕様

  1. 名前が 「_validate_検証名」 となる関数を作成する
  2. 引数として 2つの値を受け取るようにする。1つ目はユーザが入力した値、2つ目は検証メソッドのパラメータ(カッコ内の数値)
  3. これらの引数を基に検証する
  4. 正しい値の場合は TRUE を、それ以外の場合はエラーメッセージを返値として指定する

登録のやり方

スニペット内の「↓こここら↓」と「↑ここまで↑」の間に以下の構文と上記仕様の関数を追加する。
$mf->addValidateMethod('検証名');
※ここで指定する検証名には _validate_ を付けない

 /* 正しい郵便番号かどうかを検証 */
 function _validate_postcode($data, $param) {
   return preg_match("/\d{3}\-\d{4}/", $data) ? TRUE : '郵便番号が正しくありません';
 }
 $mf->addValidateMethod('postcode');

フィルターの追加

任意の出力整形フィルタを加えることができます。(Smarty みたいな?!)
大まかな流れは、上記「検証メソッドの追加」と同様。

関数仕様

  1. 名前が「_filter_フィルタ名」 となる関数を作成する
  2. 引数として 2つの値を受け取るようにする。1つめは整形対象となるテキスト、2つめはフィルタメソッドのパラメータ(カッコ内の数値)
  3. これらの引数を基に整形する
  4. 返値として、整形後の値を返す

登録のやり方

スニペット内の「↓こここら↓」と「↑ここまで↑」の間に以下の構文と上記仕様の関数を追加する。
$mf->addFilterMethod('フィルタ名');
※ここで指定するフィルタ名には _filter_ を付けない

余談

eForm との相違

標準で添付されるスニペット eForm と比べて以下の点に対応していません。

  • CAPTCHA ---> v0.0.5で対応済み
  • ファイル添付
  • HTMLメール ---> v0.0.7で対応済み
  • イベントをトリガーにして何かする
  • ドキュメントをテンプレートとして使用すること (←これはいずれ対応するかも)

などなど。

今後の予定

  • エラーメッセージ等の言語ファイル化
  • ファイルを添付しての自動返信

バグレポート、お問い合わせ、サポート

ブログ「網的脚本実験室」まで
http://www.clefarray-web.net/blog/

または、MODxの公式日本語フォーラムでも受け付けています。

ご注意、免責事項

  • 本スクリプトは MODx と同様、GPL ライセンスの元で配布されています。
  • 本スクリプトに関してのメール等での個別のお問い合わせはご遠慮ください。
  • 本スクリプトの使用によって生じた損害等について、作者は一切の責務を負わない事とさせていただきます。ご了承ください。

更新履歴

v0.0.3(公開初版)
2007-04-29
v0.0.4
2007-10-09
  • [FIX] [+errors+]が効かない不具合を修正
  • [FIX] システムが付加するフィールドはアンダースコア(_)から始まる名称に変更
  • [NEW] <label>タグに対応
  • [NEW] 入力必須項目のエラーメッセージで、ラジオボタンやリストのときは「選択必須項目です」と表示(他は「入力必須項目です」)
v0.0.5(未公開)
2007-10-16
  • [NEW] CAPTCHA 認証コードに対応
  • [NEW] 検証メソッド"range"追加
  • [FIX] 入力値が空(NULL)の場合は確認画面表示時に &nbsp; に変換
v0.0.6(未公開)
2007-10-23
  • [NEW] [+sender_ip+][+sender_host+][+sender_ua+]プレースホルダ追加
  • [NEW] 管理者宛メールアドレス(admin_mail)に複数のメールアドレスを指定可能に
  • [NEW] 検証メソッド"sameas"追加
  • [NEW] エラーのあるフィールドに任意のクラスセレクタを付加
  • [NEW] admin_ishtml, reply_ishtml, reply_fromname, invalid_class 設定項目を追加
  • [CHANGE] mb_send_mail()関数ではなく MODx 付属の PHPMailer クラスを使用するように変更。送信メールの文字コードは iso-2022-jp。
  • [FIX] 一部の設定項目省略値が反映されない不具合を修正
v0.0.7
2007-11-04
  • [NEW] HTML メール送信に対応
  • [NEW] 検証メソッド"tel"追加
  • [NEW] 自動返信先となるメールアドレスを任意指定可能に
  • [NEW] [+reply_to+]プレースホルダ追加
  • [CHANGE] 自動返信先として指定したフィールドは必ず、メールアドレス形式として正しいかを検証(→検証メソッド email は付けなくて良いです)
  • [FIX] EUC-JP 環境化でのメール文字化け解消
v0.0.7.1
2007-11-13
  • [FIX] 前後にタブを含む<option>タグを正常に処理できない不具合を修正
  • [FIX] 初期選択値(selected="selected")が指定されている場合は削除

カテゴリ:取扱説明書 | トラックバック (0)

トラックバック

このエントリーのトラックバックURL:
http://www.clefarray-web.net/blog/tb/13

カテゴリーs

Powered by Movable Type 5.01

墨田区 錦糸町のホームページ制作工房 クレファレイ・ファクトリーによるブログです。

クレファレイ・ファクトリー