esparの導入準備編 - 導入手順 -

espar form を導入する手順を順を追ってご説明します。

 

espar form の概要

まず最初に espar form の仕組みを解説します。

gettingstarted_1-0

espar form は JavaScript のプログラムです。動作させたいフォームの近くに espar form 専用の埋め込みコードを貼り付けて頂くことから始まります。（Google Analytics の組み込みコードをページに貼り付ける感覚と似ています）

esapr form が導入された html ページが表示されると、esapr form エンジン（JavaScriptプログラム）がページ内の html の解析を行い、フォームが動作するよう各種の設定を自動で行います。その解析の「手がかり」となるのが、html要素に付与して頂くCSSクラス（後述）です。

espar form のエンジンは、CSSクラスを「手がかり」にして

  • formはどこにあるのか
  • 入力項目はどれか
  • 入力項目に入力チェックは必要か
  • 入力チェックでひっかかった場合に出すエラー文言はどれか
  • 確認ボタンや送信完了ボタン、確認画面から入力画面に戻るボタンはどれか
  • 完了時に表示するテキストはどれか

などの解析を行います。この解析を助けるため、espar form の導入ではCSSクラスを正しく指定することが重要となります。

 

espa form の導入手順（基礎）

それでは、htmlファイル上のフォームを動作させてみましょう。PHPの設定も、PHPプログラムも、WordPressのプラグインも不要です。以下の手順でhtmlファイルしかないのにメールが届くようになります。

  1. html を用意する
  2. 埋め込みコードを貼り付ける
  3. クラスや要素を追加する
  4. espar form の管理画面でメールテンプレートを設定する

以上の4ステップでフォームが動き出します。1つ1つはとても簡単な作業ですので安心して下さい。まずはメールが届くところまで体験し、その後、応用編のページを見ながら細かな作り込みをして下さい。

 

1. html を用意する

最初にフォームが含まれるhtmlをご用意下さい。既存のWordPressサイト等に espar form を使用する場合は、フォームを含んでいるテーマやテンプレートをご利用ください。

 

2. 埋め込みコードを貼り付ける

埋め込みコードは espar form の管理画面から取得できます。

espar form のトライアル申込みの際に当社よりアカウント情報をお送りしています。管理画面にアクセスのうえ、ホスト名・パスワードを入力してログインし、「フォーム」メニューの「基本情報」タブを開いて下さい。

basic_4-0-0

埋め込みコードをコピーして、1.で用意したhtmlの <form> タグ直前に貼り付けて下さい。例えば以下のようになります。

<script src="https://code.jquery.com/jquery-1.12.4.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-validate/1.17.0/jquery.validate.min.js"></script>
<script src="https://bridge.espar.biz/v1.5.0/form.js"></script>
<script>
    var espar_form = { espf : { api_key: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", debug:true } };
</script>

<form>
...(省略)...
</form>

上記の埋め込みコード中の espf をフォームIDといいます。

フォームIDはespfで始まる文字列で、espar form はこのフォームIDを「手がかかり」にしてフォームを動作させます。このあとの手順で出てくるCSSクラス名指定の際にも使用することになります。（フォームIDは espf で固定です。同一サイトの2つ目以降のフォームで、espf で始まる任意の文字列を指定できます。esprReqruit など）

(注) 埋め込みコード中の jQuery と jQuery Validation について

espar form では jQuery と jQuery Validation を使用しています(埋め込みコードの1行目と2行目)。両ライブラリを既に使用しているページの場合、埋め込みコードの該当行は省略して下さい。ただバージョンに最低条件がありますので、あらかじめ 動作条件 ページを御覧下さい。

 

3. クラスや要素を追加する

次に、espar form にフォームを認識・解析して貰うための「手がかり」となるクラスを指定します。先程のフォームIDを使用します。

3-1. formタグのclass属性にフォームIDを指定

まず <form> タグそのものにフォームIDをクラス指定して下さい。

<form class="[フォームID]">
(省略)
</form>

具体例を以下に示します。例えば、管理画面でのフォームID欄が以下の場合、

basic_5-1-0

<form>タグの指定は、

<form class="espf">
(省略)
</form>

となります。なお、<form>タグにクラス指定が既にある場合は、以下のようにクラス指定を追加表記して下さい。(formStyleは例です)

<form class="formStyle espf">
(省略)
</form>

フォームIDはフォーム毎に異なりますので、必ず管理画面のフォームIDと一致しているか確認して下さい。フォームIDが正しく指定されないと espar form は正常に動作しません。

 

3-2. ボタンを一式用意しクラスを指定する

次は、フォームのボタンです。確認画面の有無で指定が異なりますので、分けて説明します。

□ 確認画面が必要な場合

[入力]→[確認]→[完了] の各画面で使用するボタンを全て html 内に用意します。ボタンが3つ並んで表示されてしまいそうに思いますが、心配はいりません。espar form が必要な時に必要なボタンの表示・非表示を切り替えます。

(省略)
  <input type="button" value="戻る" class="[フォームID]-b-back">
  <input type="button" value="確認" class="[フォームID]-b-confirm">
  <input type="button" value="送信" class="[フォームID]-b-submit">
</form>

それぞれのボタンに指定するクラスは以下の通りとなっています。

クラス名 解説 表示される画面
[フォームID]-b-back 確認画面から入力画面に戻ってくる為のボタンに指定します 確認画面
[フォームID]-b-confirm 確認画面に遷移する為のボタンに指定します 入力画面
[フォームID]-b-submit 確認画面から完了画面に遷移する為のボタンに指定します 確認画面

ボタンの<input>要素の位置は<form>タグ内ならどこでも構いません。また、既にクラスが指定されている場合は、追加表記して下さい。

(省略)
  <input type="button" value="戻る" class="formButton [フォームID]-b-back">
  <input type="button" value="確認" class="formButton [フォームID]-b-confirm">
  <input type="button" value="送信" class="formButton [フォームID]-b-submit">
</form>

具体的例を示します。管理画面上でフォームIDが espf となっている場合、

(省略)
  <input type="button" value="戻る" class="formButton espf-b-back">
  <input type="button" value="確認" class="formButton espf-b-confirm">
  <input type="button" value="送信" class="formButton espf-b-submit">
</form>

のようになります。このように、espar form では常にフォームIDをプレフィックス(接頭語)とするクラス名を使います。なお、この例では <input type="button"> の入力要素でボタン表示する例を示しましたが <button> 要素を使うこともできます。この場合でもクラス名を付与する原則は変わりません。以下は <button> 要素を使った例です。

(省略)
  <button value="戻る" class="formButton espf-b-back">戻る</button>
  <button type="button" value="確認" class="formButton espf-b-confirm">確認</button>
  <button type="button" value="送信" class="formButton espf-b-submit">送信</button>
</form>

□ 確認画面が不要な場合

確認画面が不要な場合は、非常にシンプルです。以下の通りクラスを指定して下さい。

(省略)
  <input type="button" value="送信" class="[フォームID]-b-submit">
</form>

 

3-4. 完了画面用のメッセージを指定する

次に、完了画面で表示する文言を指定します。この文言も、espar form が適切なタイミングで自動的に表示を制御してくれますので安心して下さい。以下のように要素を追加します。

<div class="[フォームID]-m-success">お問い合わせありがとうございました</div>
<div class="[フォームID]-m-failure">送信に失敗しました。誠に申し訳ございませんが info [at] example.com にメールにて御連絡下さい</div>

必ず <form> タグの外に 追加して下さい。(<form>タグの前後どちらに追加しても構いません)

具体的には、例えば管理画面上でフォームIDが espf となっていた場合は、

<div class="espf-m-success">お問い合わせありがとうございました</div>
<div class="espf-m-failure">送信に失敗しました。誠に申し訳ございませんが info [at] example.com にメールにて御連絡下さい</div>

<!-- 3.1 でクラス指定を追加したform -->
<form class="formStyle espf">
(省略)
</form>

のようになります。追加する両クラスの意味は以下の通りです。

クラス名 説明
[フォームID]-m-success メール送信が成功した時に自動的に表示されます。
[フォームID]-m-failure メール送信が失敗した時に自動的に表示されます。
通常失敗することはありませんが、万が一の時のために電話/FAX番号やメールアドレスなど
代替手段を案内する文章を含めておくと良いでしょう。

両クラスを指定するhtmlタグは、divタグ以外でも構いません。(table, span, pなど)

 

3-5. 最低限のエラークラスを設定する

espar form が一時的に動作しなくなってしまうなど万が一の時に備えて、基本的なエラーメッセージを貼り付けておきます。以下のような要素を追加して下さい。

<p class="[フォームID]-m-token-expire">フォームの有効期限が切れました。一度最初からお試し下さい。</p>
<p class="[フォームID]-m-mail-error [フォームID]-m-token-error">未定義のエラーが発生しました。申し訳ございませんが info [at] example.com に直接メールをお送り頂くか、0120-12-3456 までお電話下さい。</p>

この要素は必ず <form> タグの外に 追加して下さい。(<form>タグの前後どちらに追加しても構いません)

具体的には、例えば管理画面上でフォームIDが espf となっている場合、

<p class="espf-m-token-expire">フォームの有効期限が切れました。一度最初からお試し下さい。</p>
<p class="espf-m-mail-error espf-m-token-error">未定義のエラーが発生しました。申し訳ございませんが info [at] example.com に直接メールをお送り頂くか、0120-12-3456 までお電話下さい。</p>

<!-- 3.4 で追加した完了画面用の要素 -->
<div class="espf-m-success">お問い合わせありがとうございました</div>
<div class="espf-m-failure">送信に失敗しました。誠に申し訳ございませんが info [at] example.com にメールにて御連絡下さい</div>

<!-- 3.1 でクラス指定を追加したform -->
<form class="formStyle espf">
(省略)
</form>

のようになります。タグ内の文章にある連絡先情報は、必要に応じて変更/削除して下さい。これで、万が一の時のためにお客様に別の連絡手段をご案内することができます。(エラークラスの詳細は エラークラスをご覧下さい)

以上でhtmlの基本的な作業は完了です。これで、htmlファイルからメールが送れるようになりました。最後にメールの送り方やメールの内容を設定しましょう。

 

4. メールテンプレートを指定する

どのようにメールを送るのかは、espar form の管理画面で設定します。espar form では、送信先・タイトル・本文などの設定をひとまとめに メールテンプレート と言います。espar form では1つのフォームに2つのメールテンプレートが存在します。

メールテンプレート 解説 必須かどうか
通知メール サイト運営側に届くメールの設定です 必須
返信メール お客様に受付をお知らせするメールの設定です 必須ではない

それぞれ指定してみましょう。まずは必須の通知メールからです。

4-1. 通知メールの差出人・宛先・件名を指定する

通知メールタブを開き、それぞれ入力します。

baisc_6-1-1

件名にはメールのタイトルを、差出人と宛先にはメールアドレスを指定して下さい。メールアドレスには2つの記述方式があります。

  • (1) メールアドレスをそのまま書く
  • (2) [任意の文字列]<[メールアドレス]>

いずれの形式でも構いません。複数のメールアドレスを指定する場合は、以下のように , (カンマ)で区切って指定して下さい。記述形式を混在させることもできます。

info+espar@feedtailor.jp, テスト用<example@feedtailor.jp>

 

4-2. 通知メールのメール本文を指定する

次に通知メールの本文です。デフォルトで以下のようなサンプル文章が設定されています。これを参考に変更していきます。

baisc_6-2-1

メールテンプレートでは、フォームで入力された値に置き換わる 変数 を使用することができます。上記例では、{{ .company }} や {{ .name }} などが変数です。フォームで入力された値に自動的に置換されます。

例えば、上記の {{ .mail }} は、以下のような <input> 要素で入力された値に置き換わります。

<input type="text" name="mail" />

つまり、<input> 要素の name 属性に指定した文字列がそのまま変数となります。

メールテンプレートでの変数表記ルールは、{{ .[input要素のname属性文字列] }} です。name属性に指定した文字列の前に . (ドット) を付け、前後にスペースを加えて更に二重の波括弧でかこって下さい。(espf で始まる変数は特殊な組み込み変数です。詳しくはこちらをご覧下さい)

なお、espar form を導入したフォームでは <input> や <textarea> 等の入力要素のname属性に使える文字が制限されます。使用できる文字は、半角英数字・アンダースコア・全角文字となります。ハイフンは使用できません。例えば、以下のようなname属性が指定されると正しく動作しませんのでご注意ください。

<!-- [] をつけてしまった例 -->
<input type="checkbox" name="flag[]">

<!-- ハイフンを入れてしまった例 -->
<input type="text" name="post-code">

 

4-3. 返信メールの設定を行う

次に、返信メールの設定を行いましょう。返信メールは必須ではありません。使う/使わないを設定することができます。

baisc_6-3-1

返信メールが不要な場合は「返信メールを送信する」のチェックをOFFにして下さい。使用する場合は、チェックを入れて通知メールと同じ要領で設定していきます。設定後は保存をして下さい。

一般的に返信メールは、フォームに入力されたお客様のメールアドレス宛に送るものですので、返信メールの宛先欄にはデフォルトで {{ .mail }} という変数が指定されています。メールアドレスを入力して貰う <input> 要素の name 属性が mail ではない場合は、返信メールの宛先の変数表記を変更して下さい。

具体的には、フォームでメールアドレスを入力して貰う <input> 要素を

<input type="text" name="emailaddress">

としている場合、返信メールの宛先欄は {{ .emailaddress }} とする必要があります。

 

5. メールを実際に送ってみる

設定作業は以上で終了です。お疲れ様でした。以下の手順で実際にメール送信してみましょう。

  • (1) html を Web サーバにアップロードする
  • (2) 当該のhtmlに対応するURLをブラウザに入力してページを開く
  • (3) アドレスバーのホスト名（ドメイン名）部分が、管理画面の [詳細設定]→[許可する送信元ホスト] に含まれているか確認する（管理画面の以下の赤枠）

basic_6-0-3

  • (4) フォームに値を入力してボタンを押す

設定した通りにメールが届けば成功です。メールが届かない場合、上記(3)のホスト名（ドメイン名）が、htmlを設置したホスト名と異なっていることが原因であることが多いです。URLをご確認下さい。

また、フォームが反応しない場合はデバッグ機能を使ってクラス指定が正しく行われているかチェックして下さい。それでも、メールが送信されない、画面にエラー文言等が表示されるといった場合は、弊社担当にお問い合わせ下さい。その際、デバッグのログ画面のキャプチャや、フォームの画面キャプチャを併せてお送り頂くと解決が早くなりますので、ご協力をお願い致します。

espar form 導入サイトで静的化エンジン espar をご利用の場合

esparをご利用の場合、CMS用のドメイン・公開用のドメイン・トライアル環境用のドメインなど、多数のドメインが登場します。espar form でのメール送信確認をする際は、「ブラウザで表示しているドメイン」と「管理画面の『許可する送信元ホスト』に記載されたドメイン」が一致しているかどうかご確認下さい。

CMS用のドメインにアクセスしてしまっていてメールが送信できない…とご報告を頂くケースがまれにございます。esparをご利用の場合は、必ず静的化した結果であるespar公開側のページ上から送信テストをお願い致します。(ただし、CMS側でも動作確認できるよう当社で特別に設定させて頂いている場合この限りではありません)

 

以上で espar form の導入手順（基本編）は終了です。

この後の進み方

この後、入力条件チェック(バリデーション)や、メールの細かな設定、そのほか必要に応じてチャット連携や外部API連携を実装していきます。以下を参考に実装・設定を進めて下さい。必須の項目のみで多くのシンプルなフォームが十分機能します。

高度な振る舞いが必要な場合に限り、応用編を参考にして下さい。

ページ 必須？ 説明
実装編1 - バリデーション 必須 フォームの入力要素に必須やメアド形式等の条件指定とエラー表示をしたいとき
設定編1 - メールテンプレート 必須 メール送信で入力値による条件分岐など高度なメール設定を行いたいとき
設定編2 - DNS設定 必須 espar form からのメールが受信側で迷惑メールに入りにくくするための設定
応用編1 - 独自バリデーション 標準のバリデーションにはない条件指定とエラー表示をしたいとき
応用編2 - 表示制御クラス 入力画面や完了画面にだけ表示したいメッセージがある場合
応用編3 - チャット連携 slackやchatworkなどのチャットサービスに問い合わせ内容を転送したいとき
応用編4 - 外部API連携 RestAPIを備える外部のサービスやシステムと連携したいとき
(Google SpreadSheet やサイボウズkitnone、その他自社システム等)
応用編5 - 複数フォームと値コピー 複数フォームを順に入力していくウィザード形式のフォームを作りたいとき

また、正常に動作しない場合には、以下のページが参考になります。

ページ 説明
デバッグとテスト 導入準備編の作業の抜けや、バリデーションでの指定の抜けを検出するデバッグ機構を用意しています
よくある質問 よく頂く質問について回答と解説を列挙しています。実装にあたり不明点があれば参照して下さい

JavaScriptの実装ができるフロントエンジニアの方は、JavaScript を使って高度なカスタマイズが可能です。espar form 技術仕様 のページにある B.グローバルオブジェクト と C.コールバック のセクションが参考になります。