web-forms

Frappe Web Forms

データ収集、送信、顧客のセルフサービス向けに、一般公開するウェブフォームを作成します。

使用する場面

• 外部ユーザー向けのフォームを作成する場合（Desk へのアクセス権がないユーザー）
• サポート／チケット送信用フォームを作成する場合
• 顧客からのフィードバックや登録情報を収集する場合
• セルフサービスのデータ入力ポータルを提供する場合
• シンプルなポータルページをフォームベースのワークフローに置き換える場合

必要な入力情報

• フォーム送信先の DocType
• ウェブフォームに表示するフィールド
• 認証要件（ログイン必須かゲスト利用可か）
• ユーザーによる入力内容の編集／再送信を許可するかどうか
• ファイルアップロードの要件

手順

0) 前提条件

対象の DocType が存在し、表示したいフィールドが用意されていることを確認します。

1) Web Form を作成する

1. awesomebar に「new web form」と入力します
2. タイトルを入力します（URL スラッグになります）
3. レコード作成用の DocType を選択します
4. 紹介文を追加します（任意。フォームの上部に表示されます）
5. 「Get Fields」をクリックしてすべてのフィールドをインポートするか、フィールドを手動で追加します
6. フィールドの順序と必須項目を設定します
7. フォームを公開します

2) 設定する

設定	目的
Login Required	フォームへのアクセス前に認証を必須にします
Allow Edit	ユーザーが送信済みの入力内容を編集できるようにします
Allow Multiple	ユーザーが複数回送信できるようにします
Show as Card	カードレイアウトで表示します
Max Attachment Size	ファイルのアップロードサイズを制限します
Success URL	送信成功後のリダイレクト先を設定します
Success Message	送信後に表示するカスタムメッセージを設定します

3) Standard Web Form（アプリにバンドル）にする

「Is Standard」（Developer Mode で表示）にチェックを入れると、フォームがファイルとしてエクスポートされます。

my_app/
└── my_module/
    └── web_form/
        └── contact_us/
            ├── contact_us.json    # Web form metadata
            ├── contact_us.py      # Server-side customization
            └── contact_us.js      # Client-side customization

4) サーバー側のカスタマイズを追加する

# contact_us.py
import frappe

def get_context(context):
    """Add custom context variables to the web form."""
    context.categories = frappe.get_all("Support Category",
        filters={"enabled": 1},
        fields=["name", "label"],
        order_by="label asc"
    )

def validate(doc):
    """Custom validation before the document is saved."""
    if not doc.email:
        frappe.throw("Email address is required")

    # Prevent duplicate submissions
    existing = frappe.db.exists("Support Ticket", {"email": doc.email, "status": "Open"})
    if existing:
        frappe.throw("You already have an open ticket. Please wait for a response.")

5) クライアント側のカスタマイズを追加する

// contact_us.js
frappe.ready(function() {
    // Handle field changes
    frappe.web_form.on("field_change", function(field, value) {
        if (field === "category" && value === "Urgent") {
            frappe.web_form.set_df_property("description", "reqd", 1);
        }
    });

    // Custom validation
    frappe.web_form.validate = function() {
        let data = frappe.web_form.get_values();
        if (data.phone && !data.phone.match(/^\+?[0-9\-\s]+$/)) {
            frappe.msgprint("Please enter a valid phone number");
            return false;
        }
        return true;
    };

    // Custom after-save behavior
    frappe.web_form.after_save = function() {
        frappe.msgprint("Thank you for your submission!");
    };
});

6) 権限を制御する

• ゲストアクセス：「Login Required」のチェックを外すと、完全な公開フォームになります
• ポータルロール：ポータルロールを割り当て、どのログインユーザーがフォームを閲覧できるかを制御します
• ユーザー権限：対象の DocType に明示的なドキュメントレベルの権限を設定します
• 行レベルのアクセス：User Permission ルールを使用して、ユーザーが編集できるレコードを制限します

7) Web Form のスタイルを設定する

Web Form では、デフォルトでウェブサイトのテーマが使用されます。カスタムスタイルを設定するには、次のようにします。

<style>
    .web-form-container { max-width: 600px; margin: 0 auto; }
    .web-form-container .form-group { margin-bottom: 1.5rem; }
    .web-form-container .btn-primary { background-color: #2490EF; }
</style>

検証

• Web フォームが正しい URL（/contact-us）でアクセスできる
• すべてのフィールドが正しく表示される
• 必須フィールドの検証が機能する
• 送信によって正しい DocType レコードが作成される
• （設定した場合）ログイン要件が適用される
• （設定した場合）編集と再送信が機能する
• ファイルサイズ制限の範囲内でファイルをアップロードできる
• 送信後の成功メッセージ／リダイレクトが機能する
• 送信時にカスタム Python 検証が実行される

失敗パターン／デバッグ

• フォームにアクセスできない：公開されているか確認し、URL スラッグを確認します
• 送信時に権限が拒否される：Website User または Guest の DocType 権限を確認します
• フィールドが表示されない：DocType 上だけでなく、Web Form にフィールドが追加されていることを確認します
• カスタム JS が読み込まれない：ブラウザーコンソールを確認し、ファイルパスが正しいことを確認します
• 検証が実行されない：Python ファイル内の validate 関数が正しく値を返すか、例外を発生させるか確認します
• 重複したエントリーが作成される：「Allow Multiple」の設定を確認し、カスタムの重複検出を追加します

エスカレーション

• DocType スキーマについては → doctype-development
• Frappe UI のポータルアプリについては → frontend-development
• API エンドポイントへのアクセスについては → api-development

参考資料

• references/web-forms.md — Web Form の作成とカスタマイズ

ガードレール

• サーバー側で入力を検証する：クライアント側の検証を信用せず、Python の validate() メソッドで確認します
• 公開フォームには CAPTCHA を使用する：スパムを防ぐため、ゲストがアクセスできるフォームでは reCAPTCHA を有効にします
• 出力をサニタイズする：ユーザーが送信したデータを表示するときはエスケープし、frappe.utils.escape_html() を使用します
• ファイルのアップロードを制限する：添付フィールドの最大ファイルサイズと許可するファイル形式を設定します
• レート制限を確認する：同じ IP アドレスからのフォーム送信をスロットリングすることを検討します

よくある間違い

間違い	失敗する理由	修正方法
DocType の権限がない	送信時に「Permission denied」が表示されます	Website User または Guest ロールに Create 権限を付与します
ファイルのアップロードを処理していない	ファイルがレコードに添付されません	Attach フィールドを正しく設定し、アップロード制限を確認します
XSS の脆弱性	セキュリティリスクになります	表示時にユーザー入力をエスケープし、テンプレートで `
フォームの公開を忘れる	404 エラーになります	Web Form の「Published」チェックボックスを確認します
クライアント側だけで検証する	データベースに無効なデータが保存されます	Web フォームの Python ファイルに validate() メソッドを追加します
ゲストユーザーとしてテストしない	管理者では動作しても、ユーザーでは動作しません	シークレットモードまたはログアウト状態でテストします