cfFormMailer マニュアル v0.0.7.1
2007-11-0223:44
cfFormMailer マニュアル v0.0.7
MODx 用日本語メールフォーム作成スニペット「cfFormMailer」の利用解説です。
設置&使用方法
下準備
- /assets/snippets/ フォルダ内に cfFormMailer というフォルダを作成し、そのフォルダ内に以下のファイルを配置します。
- class.cfFormMailer.inc.php
- class.cfFormMailerMODx.inc.php
- MODxの管理画面にログインし、[リソース]-[リソース管理]-[スニペット]タブ-[スニペットの作成]をクリックして、スニペットを新規作成します。
スニペット名に cfFormMailer と入力し、スニペットコード欄にファイル snippet.cfFormMailer.php の内容をコピー&ペーストします。 - [リソース]-[リソース管理]-[チャンク]タブ-[チャンクの作成]から、「環境設定」として利用するチャンクを任意の名称で作成し、チャンクコードにまずは chunk_sample フォルダ内の tmpl.chunk_config.txt の内容をコピー&ペーストします。
その後、各設定項目の値をご利用の環境に合わせて書き換え、保存してください。
# で始まる行はコメントですので、これを参考にしてください。 - [リソース]-[リソース管理]-[チャンク]タブ-[チャンクの作成]から、「入力画面」「確認画面」「完了画面」「管理者宛メール」「自動返信メール」の各テンプレートとして使用するチャンクを任意の名称で作成します。
それぞれのチャンクコードは、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
- 検証項目。コンマ区切りで複数指定可。以下の標準装備の方式以外にも、独自の方式も指定可能。(下記「検証メソッドの追加」参照。)
- メールアドレスチェック(※半角に強制変換)
- 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>
検証メソッドの追加
以下の仕様に則った関数を使用して、任意の検証メソッドを追加することができるます。
関数仕様
- 名前が 「_validate_検証名」 となる関数を作成する
- 引数として 2つの値を受け取るようにする。1つ目はユーザが入力した値、2つ目は検証メソッドのパラメータ(カッコ内の数値)
- これらの引数を基に検証する
- 正しい値の場合は TRUE を、それ以外の場合はエラーメッセージを返値として指定する
登録のやり方
スニペット内の「↓こここら↓」と「↑ここまで↑」の間に以下の構文と上記仕様の関数を追加する。
$mf->addValidateMethod('検証名');
※ここで指定する検証名には _validate_ を付けない
例
/* 正しい郵便番号かどうかを検証 */
function _validate_postcode($data, $param) {
return preg_match("/\d{3}\-\d{4}/", $data) ? TRUE : '郵便番号が正しくありません';
}
$mf->addValidateMethod('postcode');
フィルターの追加
任意の出力整形フィルタを加えることができます。(Smarty みたいな?!)
大まかな流れは、上記「検証メソッドの追加」と同様。
関数仕様
- 名前が「_filter_フィルタ名」 となる関数を作成する
- 引数として 2つの値を受け取るようにする。1つめは整形対象となるテキスト、2つめはフィルタメソッドのパラメータ(カッコ内の数値)
- これらの引数を基に整形する
- 返値として、整形後の値を返す
登録のやり方
スニペット内の「↓こここら↓」と「↑ここまで↑」の間に以下の構文と上記仕様の関数を追加する。
$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] 入力必須項目のエラーメッセージで、ラジオボタンやリストのときは「選択必須項目です」と表示(他は「入力必須項目です」)
- [FIX]
- v0.0.5(未公開)
- 2007-10-16
- [NEW] CAPTCHA 認証コードに対応
- [NEW] 検証メソッド"range"追加
- [FIX] 入力値が空(NULL)の場合は確認画面表示時に に変換
- 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] 一部の設定項目省略値が反映されない不具合を修正
- [NEW]
- 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)