frappe-builder

Frappe Builder

Builder サイトは、ドキュメントの集合です。Builder Page（blocks = 公開中、draft_blocks = 下書きのブロックツリー）、Builder Component（ページにインスタンスとして埋め込むブロックツリー）、Builder Token（色とフォントの変数）、Builder Client Script（ページの JS/CSS ファイル）、Builder Settings（ホームページ、サイト全体のコード）があります。ここでのすべての手順は、ドキュメントの読み取りまたは書き込み、あるいは許可リストに登録されたメソッドであるため、サイトのアシスタント、MCP、frappectl のいずれからでも同じように実行できます。ユーザーには Website Manager ロールが必要です。DocType（フォーム用）の作成には System Manager が必要です。

シェルを使う場合は、最初に reference/cli.md を読んでください。このスキルのディレクトリにある scripts/builder.py はサインインし、ツリーを lint してプッシュし、コンポーネントのインスタンスを作成し、ページをサイト間でコピーします。

1. 編集ループ

• ページのツリーは draft_blocks です。下書きが空の場合は blocks を使います。コンポーネントのツリーは block です。いずれも JSON が文字列として保存されます。読み取った modified 値とともに、ツリー全体を draft_blocks（または block）に書き戻してください。途中で誰かが保存していた場合、上書きされずに書き込みが失敗するため、再度読み取ってマージしてください。
• ページを初めて編集する前に、そのページの create_manual_snapshot メソッドを label とともに呼び出してください。ロールバックするには、その Builder Snapshot の名前を指定して restore_snapshot を呼び出します。ツリーが下書きに戻されます。
• 書き込む前に、該当ページのエディタータブを閉じるよう人に依頼し、書き込み後に再読み込みしてもらってください。開いたままのタブは、次回の編集時に古いツリーで下書きを上書きします。
• ページがあるサイトでは、最初にそのうちの1ページを読み取り、トークン、フォント、幅、コンポーネントを再利用してください。
• ページ上のブロックからセクションを作成します。同じツリーがこのページ内または複数のページで繰り返され、既存のコンポーネントでは対応できない場合に限り、コンポーネントにしてください。プロップを追加するのは、エディターがインスタンス上で編集できない項目、またはスクリプトが読み取る項目に限ります（reference/components.md）。
• 新しいページを作成するには、page_title と route を指定して Builder Page を作成します。
• 下書きをプレビューするには、builder.api.get_page_preview_html を使います。ライブデータスクリプトとスクリプトを適用してレンダリングされます。ここでエラーが発生した場合、訪問者にも同じエラーが表示されます。
• ページを公開するには、その publish メソッドを呼び出します。メソッドはルートを返します。REST 経由の場合は、JSON ボディに {"run_method": "publish"} を指定して /api/resource/Builder Page/<name> に POST します。

下書きがあるのはページのブロックツリーだけです。訪問者に表示されるのは公開後です。それ以外はすべて、保存するとすぐに公開されます。ページのデータスクリプトとフィールド、クライアントスクリプト、トークン、Builder Settings、コンポーネントの保存内容が該当します（ピン留めされていないインスタンスは即時に変更されます。続いて builder.api.sync_component を実行すると、そのコンポーネントを埋め込んでいるすべてのページの公開中のブロックが書き換えられます）。

プレビュー（公開中の変更の場合は公開ルート）に変更が表示され、人が何が公開中で何がまだ下書きなのかを把握していれば完了です。

2. 注意点

• すべてのブロックテキスト、属性、コンポーネントのスクリプトとスタイル、head_html、canonical_url は Jinja を通じてレンダリングされます。 {{ }} と {% %} は公開時に評価され、エディターにはそのまま表示されます。{# は {% raw %} 内にないとページのエラーになります。.__ はその中でもエラーになるため、そのようなコードはクライアントスクリプトファイルに移してください。
• データスクリプトでの例外、ネストされたバインディングの欠落、またはリピーターがリストを要求する箇所に辞書を渡すと、ページで 500 エラーが発生します。 reference/data-and-scripts.md を参照してください。
• ルートはすべてに優先します。 Builder のルートは他のすべての Web サイトルートより優先されます。/:slug のようなルート直下のキャッチオールは、/login や /builder のエディターも捕捉します。
• バインドされた値は生の HTML としてレンダリングされます。 訪問者が送信したテキストは、データスクリプトでサニタイズするかエスケープしてください。

リファレンス

• reference/blocks.md：ブロック JSON、スタイル、ブレークポイント、トークン、バインディング、リピーター、表示設定。
• reference/data-and-scripts.md：両方の実行環境でのデータスクリプト、動的ルート、クライアントスクリプトと読み込み順序、データを保存するフォーム。
• reference/components.md：コンポーネントの作成、インスタンスとオーバーライド、エディターのサンドボックス、ピン留めと同期。examples/tabs/ に動作するコンポーネントがあります。
• reference/live-and-cached.md：公開中の変更が表示されない場合について。
• reference/cli.md：シェルを使った作業（サインイン、scripts/builder.py、ローカルの bench、トンネル）。