frappe-web-forms

Frappe Web Forms

データ収集、送信、顧客のセルフサービスに対応する、外部公開用の Web フォームを作成します。

使用する場面

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

必要な入力

• フォーム送信先の DocType
• Web フォームに表示するフィールド
• 認証要件（ログイン必須か、ゲストを許可するか）
• ユーザーによる送信内容の編集・再送信を許可するか
• ファイルアップロードの要件

手順

0) 前提条件

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

1) Web フォームを作成する

1. Awesome Bar に「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) 標準 Web フォームにする（アプリに同梱）

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

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 フォームのスタイルを設定する

Web フォームには、デフォルトで Web サイトのテーマが適用されます。スタイルをカスタマイズするには、次のようにします。

<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 フォームにも追加されていることを確認します
• カスタム JS が読み込まれない：ブラウザーのコンソールを確認し、ファイルパスが正しいことを確認します
• 検証が実行されない：Python ファイル内の validate 関数が正しく値を返す、または例外を送出することを確認します
• レコードが重複する：「Allow Multiple」の設定を確認し、カスタムの重複検出を追加します

エスカレーション

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

参考資料

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

注意事項

• サーバー側で入力を検証する：クライアント側の検証を信用せず、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() メソッドを追加します
ゲストユーザーとしてテストしない	管理者では動作しても、ユーザーでは動作しません	シークレットモードまたはログアウト状態でテストします