eForm - The Electronic Form Snippet

キーワード：eForm 問い合わせフォーム

http://modx.jp.net/snippets/basics/eform.html
http://www.modx.liolion.net/resource/eform.html
上記サイトの説明がとても分かりやすいです

Who's responsible for eForm

オリジナル作者： Raymond Irving (2004-12-15)
Version 1.3 - 1.4 extended by: Jelle Jager (TobyL) September 2006

Captcha image support - thanks to Djamoer
Multi checkbox, radio, select support - thanks to Djamoer
Styles (for these docs) 'borrowed' from Adam Crownoble's QuickEdit

What is eForm?

eForm converts a web form into an email which can be sent via email to specified users. Its main features are: html form mail with attachments, auto-respond, report generation using placeholders and extended form validation.

What's New

Version 1.4.4.1 - 1.4.4.7

You can see a more extensive version history here.

インストールする

※現在はMODX配布パッケージに標準で同梱されていますが、参考のために下記掲載します。

注意事項

標準的な使い方では、確認画面を設定することはできません。eFormが愛用されている欧米では、問い合わせフォームに確認画面を設ける慣習がもともとありません。多少の開発ができる場合は、eForm本体を改造することなく独自プラグインの追加などにより確認画面を設けることは可能ですが、開発まで行なわない場合は cfFormMailerの採用をおすすめします。

http://modx.jp.net/snippets/generic/eform.html

eFormの使い方の詳細については、上記サイトが詳しいです。

設置作業の基本

設置作業は基本的に３ステップです。

問い合わせフォームを記述

設置したいページではなく、チャンクや他リソースなど別の場所にフォームを記述する理由は、同じページで「フォーム」と「ありがとうございましたメッセージ」を動的に出し分ける必要があるためです。

フォームの記述自体は、基本的には専用のタグを用いることなく、使い慣れたhtmlタグ(form・input・selectなど)で記述できます。eFormは単純に、各フォーム要素に入力された値を各name属性ごとに読み取って処理する働きを持ちます。

入力必須項目を指定したい場合などにeform属性を利用します。
(<input type="name" eform="メールアドレス:email:1" /> など)

formの記述に関しては、eform属性を利用する以外は通常のhtmlを扱うのとほとんど変わりませんが、form要素にIDを指定する必要がありますのでご注意ください。これを忘れると動作しません。IDはスニペットコール(※後述)と紐づけます。

受け取るメールのひな型

eFormは、送信するメールの本文を全自動で組み立てる機能を持っていません。問い合わせ人の名前やメールアドレスなどといった入力情報を、どういう形でメール本文とするかを指定する必要があります。

ウェブサイトの問い合わせフォームからの送信です。
--------------------------------------------------------
お名前 : [+氏名+] さん
Email : [+email+]
件 名 : [+subject+]
内 容 :
[+問い合わせ内容+]
--------------------------------------------------------

上記のように指定します。[+氏名+] は、フォーム側で <input name="氏名" type="text" /> などと記述された個所と自動的に連動します。「email」「subject」は特別な機能を持つシステム固有の名前なので気をつけてください。ただしカスタマイズで変更することもできます。

スニペットコール

フォームと「ありがとうございましたメッセージ」を出し分ける必要があるため、キャッシュオフ書式で記述します。

[!eForm!] と記述するだけでは動作しません。３つのパラメータが必須です。

スニペットコールのパラメータ

eForm is very flexible and there's quite a collection of parameters you can use to get eForm to do what you want. Read some of the examples if you're unsure what to do.

必須パラメータ

[!eForm? &tpl=`フォーム本体(htmlで書く)` &report=`送信メールのひな型`!]

&tpl

eFormは、問い合わせフォームを設置したいページとは別の場所でフォームの本体コード(<form>・・・</form>要素のこと)を管理します。もちろんform要素の前後に他の記述が存在してもかまいません。

フォームの本体は、チャンクまたは他のリソースで管理します。そのチャンクまたはリソースを指定するのが、この &tplパラメータです。通常の文字列で指定した場合はチャンク名、数字のみで指定された場合はリソースが指定されたものと認識します。

No parameters are forwarded to the snippet call in this version. For the regular form fields you do not normally need to add placeholders, they automatically get inserted by eForm. The esception to this rule are in the case of event functions where you want to set specific values.

Special placeholders available are: [+validationmessage+], [+postdate+],[+verimageurl+] & [+debugText+]

You should have the [+validatiomessage+] placeholder in all your forms. The others you may need depending on other parameters.

&report

送信するメールのひな型はチャンクまたは他リソースに記述します。ひな型を記述したチャンクまたはリソースを指定するのが、&reportパラメータです。

チャンクを指定する場合はそのままチャンク名を、リソースを指定する場合はリソースIDを記述してください。eForm側では、半角数字のみかどうかで「チャンクかリソースか」を判別します。

※2012年4月5日追記
「&formidパラメータは必須」としておりましたが、これは不具合でした。1.0.6J-r1で修正します。

その他のパラメータ（必須ではありません）

&formid

ひとつのページ内に複数のフォームを設置する場合は、必ずIDを設定する必要があります。たとえば下記のように記述します。

<input type="hidden" name="formid" value="formName" />

または

<form id="formName"...>

上記のようにしてフォーム側で設定したIDをスニペットコール側で紐づけるのが、&formidパラメータです。

PHP Event Functions:

The eForm event functions are now incorporated into the parameters. They are:

Examples:

[!eForm? 
		&to=`me@mydomain.com`
		&gotoid=`1`
		&tpl=`orders`
		&report=`orderreport`
!]
[!eForm?
		&to=`sales@mysuppliers.com`
		&category=`Purchase Order`
		&tpl=`chunkPurchaseOrder`
		&report=`chunkPurchaseReport`
!]

Placeholders

For all normal form fields eForm automatically inserts appropriate placeholders. However there are a few that you may need to add manually:

Datatypes and formatting

eForm is incorporating a form parser which extracts formatting and validation options from each form field. To set options for a field add the

eform

(pseudo) attribute to each required form field.

<input type="text" name="color" eform="A Color:string:1" />

The basic format of the eform attribute is:

[description/title]:[datatype]:[required]:[validation message]:[validation rule]

Data types

You only need to set the following data types. Others will be set automatically (radio & checkbox as they are, string for textbox and listbox for select)

Standard validation: All fields that are required will be checked if they are left empty.

The listbox, checkbox and radio fields do normally not require the datatype to be set. eForm will recognize these automatically. It will validate the values against the list of values placed in the form.

Extended Server Validation

This version instroduces extended server validation and word filtering using very flexible validation rules that can be set in the

eform

attribute. You can set 2 extra validation parameters, a custom error message and a validation or filter rule.

example:

eform="Year of Birth:integer:1:Must be between 1950 and 2002:#RANGE 1950-2002"

The validation rules

Select boxes, radio options and checkbox fields

Select boxes, radio options and checkbox fields now have working automatic validation. Any input for these fields is validated against the values set in your form template. This avoids anyone tampering with the form by adding their own values to these fields

Hidden fields

By default hidden fields are validated as a protection against tampering by comparing the input against the value set in the form template (much like the select, checkbox and radio fields) In some circumstances this may not be desirable however. For instance when you use some javascript in your form to store a result in a hidden field. In those cases you can turn this behaviour off by setting the eform attribute (with or without it's own validation).

Hidden field example 1.
The default behaviour is handy for instance if you are storing a document id and want to be sure no one can tamper with the id. the field would look like this:

<input type="hidden" name="docId" value="31" />

 

Hidden field example 2.
Suppose you have a form where a javascript calculated value is stored in a hidden field. To avoid the hidden field being validated at all you add the following eform attribute:

<input type="hidden" name="calculatedField" value="" eform="::0::" />

 

Hidden field example 3.
Same scenario as 2 but suppose you want to make sure a value is returned and that it stays within a certain range. The eform attribute is set with: title,integer data type, required field, error message and validation with #RANGE (in this example a value between 1-10)

<input type="hidden" name="calculatedField" value="" eform="Calculated Value:integer:1:Calculation out of range:#RANGE 1-10" />

 

Form field examples with validation

1. Selectbox - set as required field (no validation required)

<select name="mySelect" eform_options="Select Country::1" /> (datatype left blank)
<option value="en-au">Australia</option>
<option value="en-us">USA</option>
</select>

2. Textbox - required and format set to date

<input type="text" name="dobDate" eform_options="Date of Birth:date:1:@EVAL return (strtotime($value)!==-1)?true:false;" />

3. Multiple checkbox - required, eform_options only set once.

<input type="checkbox" name="myColors[]" value="Red" eform_options="Colors::1" /> (datatype left blank)

<input type="checkbox" name="myColors[]" value="Green" /> (datatype left blank)

Todo

PR

  • KAGOYA
  • ASP at AKIHABARA Japan
  • CMS AWARDS 2007 Winner
ページトップへ