cfFormMailerマニュアル

v0.0.7.2

■ 設置＆使用方法

【下準備】

  1. /assets/snippets/ フォルダ内に cfFormMailer というフォルダを作成し、そのフォルダ内に以下のファイルを配置します。
  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?&config=`config_chunk`!]

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

■ 機能解説

【入力値の検証】

フォーム内の各フィールドに対して、入力値の検証を行うことができます。

[書式]

<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
その他（未実装）

[例]

以上で挙げた検証の他に、「自動返信」を使用する場合は”自動返信先”（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+]
画像認証コードとして使用する画像の URI

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

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

【表示フィルタ】

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

[書式]

[+フィールド名|フィルタ名（パラメータ）+]

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

[例]

【検証メソッドの追加】

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

[関数仕様]

  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_ を付けない

【自動返信】

環境設定チャンク内の 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)の使用】 NEW in v0.0.5

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ワード」と同様になります。

■ 余談

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

などなど。

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

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

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

■ ご注意、免責事項

※本スクリプトは MODx と同様、GPL ライセンスの元で配布されています。
※本スクリプトに関してのメール等での個別のお問い合わせはご遠慮ください。
※本スクリプトの使用によって生じた損害等について、作者は一切の責務を負わない事とさせていただきます。ご了承ください。
※バージョン1.0以降、動作検証は modx 1.0 にて行っています。また文字コードは UTF-8 に限定しております。

■ 更新履歴

2009-09-12 v0.0.7.2
[FIX] 独自検証メソッド、フィルターメソッド追加に関する不具合を修正
[FIX] フォームの各属性の値が大文字で記述されていた場合に、エラー画面で入力値が反映しない不具合を修正
[FIX] 空のvalue属性があった場合にタグが崩れる不具合を修正
[FIX] 入力画面サンプルチャンクの<form>タグにaction属性を追加
2007-11-13 v0.0.7.1
[FIX] 前後にタブを含む<option>タグを正常に処理できない不具合を修正
[FIX] 初期選択値（selected="selected")が指定されている場合は削除
2007-11-04 v0.0.7
[NEW] HTML メール送信に対応
[NEW] 検証メソッド”tel”追加
[NEW] 自動返信先となるメールアドレスを任意指定可能に
[NEW] [+reply_to+]プレースホルダ追加
[CHANGE] 自動返信先として指定したフィールドは必ず、メールアドレス形式として正しいかを検証（→検証メソッド email は付けなくて良いです）
[FIX] EUC-JP 環境化でのメール文字化け解消
2007-10-23（未公開） v0.0.6
[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] 一部の設定項目省略値が反映されない不具合を修正
2007-10-16（未公開）v0.0.5
[NEW] CAPTCHA 認証コードに対応
[NEW] 検証メソッド”range”追加 [FIX] 入力値が空(NULL）の場合は確認画面表示時に &nbsp; に変換
2007-10-09 v0.0.4
[FIX] [+errors+]が効かない不具合を修正
[FIX] システムが付加するフィールドはアンダースコア(_)から始まる名称に変更
[NEW] <label>タグに対応
[NEW] 入力必須項目のエラーメッセージで、ラジオボタンやリストのときは「選択必須項目です」と表示（他は「入力必須項目です」）
2007-04-29 v0.0.3（公開初版）