frappe-ops-website-deploy

ERPNext/Frappe へのウェブサイトのデプロイ

Web Pages、Page Builder、REST API を使用して、静的な HTML/CSS ウェブサイトを ERPNext v15/v16 にデプロイするパターンです。

---

重要：ERPNext v16 では main_section はレンダリングされません

Frappe v16 では、Web Page の main_section フィールドは保存されますが、content_type: "HTML" や dynamic_template: 1 を指定しても、ブラウザーではレンダリングされません。主なレンダリング方法は Page Builder（page_blocks）です。

HTML コンテンツをレンダリングするには、カスタム Web Template を使用して page_blocks を指定する必要があります。

---

判断ツリー

What do you need?
├── Deploy HTML pages to ERPNext
│   ├── Step 1: Create "Raw HTML Section" Web Template (one-time)
│   ├── Step 2: Create Web Pages with page_blocks
│   └── Step 3: Configure Website Settings
│
├── Add a forum / discussion system
│   └── Use Frappe's built-in Discussion Topic/Reply + Discussions Web Template
│
├── Manage CSS
│   ├── Per-page CSS → Web Page `css` field
│   ├── Global CSS → Website Settings `head_html`
│   └── WARNING: Never stack !important overrides (see CSS Management)
│
└── Configure navigation
    └── Website Settings: top_bar_items, footer_items, brand_html, home_page

---

ステップ 1：Raw HTML Section Web Template を作成する

これは一度だけ行う設定です。このテンプレートは生の HTML を受け取り、そのままレンダリングします。

POST /api/resource/Web%20Template

{
  "name": "Raw HTML Section",
  "type": "Section",
  "template": "{{ values.html_content }}",
  "fields": [
    {
      "fieldname": "html_content",
      "fieldtype": "Text",
      "label": "HTML Content"
    }
  ]
}

重要な制約：

• fieldtype は "Text" にする必要があります。Frappe は Web Template フィールドに "Code" を指定すると拒否します
• 使用可能なフィールドタイプ：Attach Image、Check、Data、Int、Link、Select、Small Text、Text、Markdown Editor、Section Break、Column Break、Table Break
• テンプレートでは values. プレフィックスを付けた {{ values.html_content }} を使用して、フィールドデータにアクセスします

---

ステップ 2：Page Builder で Web Pages を作成する

各ページでは content_type: "Page Builder" を指定し、HTML を page_blocks に設定する必要があります。

POST /api/resource/Web%20Page

{
  "title": "Page Title",
  "route": "my-page",
  "published": 1,
  "show_title": 0,
  "full_width": 1,
  "content_type": "Page Builder",
  "css": "<per-page CSS here>",
  "page_blocks": [
    {
      "web_template": "Raw HTML Section",
      "web_template_values": "{\"html_content\": \"<div>Your HTML here</div>\"}"
    }
  ]
}

**重要：web_template_values はオブジェクトではなく JSON 文字列です。**送信前に json.dumps() でシリアライズしてください。

既存のページを更新する

PUT /api/resource/Web%20Page/{url_encoded_name}

ルートからページを検索するには：

GET /api/resource/Web%20Page?filters=[["route","=","my-page"]]&fields=["name"]

---

ステップ 3：Website Settings を設定する

PUT /api/resource/Website%20Settings/Website%20Settings

{
  "home_page": "home",
  "brand_html": "<span style=\"...\">NL</span> My Brand",
  "head_html": "<link href=\"fonts.css\" rel=\"stylesheet\">\n<style>/* global CSS */</style>",
  "top_bar_items": [
    {"label": "About", "url": "/about", "right": 0}
  ],
  "footer_items": [
    {"label": "About", "url": "/about"}
  ]
}

head_html：Frappe のラッパーを修正する

Frappe はページコンテンツを複数の div で囲み、不要な余白を追加します。次の修正を head_html に追加してください。

<style>
.page-header-wrapper { display: none !important; }
.page-breadcrumbs { display: none !important; }
.page-content-wrapper { padding: 0 !important; margin: 0 !important; }
.page_content { padding: 0 !important; margin: 0 !important; }
.webpage-content { padding: 0 !important; margin: 0 !important; }
.web-page-content { padding: 0 !important; margin: 0 !important; max-width: none !important; }
.section.section-padding-top { padding-top: 0 !important; }
.section.section-padding-bottom { padding-bottom: 0 !important; }
.web-template-section { padding: 0 !important; margin: 0 !important; }
main { padding: 0 !important; margin: 0 !important; }
</style>

使用する !important による上書きは、これだけにしてください。これらはコンテンツではなく、Frappe 独自のラッパー要素を対象としています。

---

CSS の管理

基本原則：モックアップの CSS はそのまま維持する

各ページの css フィールドでは、元のモックアップの CSS を使用してください。Frappe のラッパーを修正する場合にのみ head_html を使用します。コンテンツの CSS に !important による上書きを重ねないでください。カスケードの競合が発生し、レイアウトが予測できなくなります。

CSS の設定場所

CSS の種類	場所	フィールド
モックアップ／ページの CSS	Web Page ごと	css
Google Fonts、Frappe の修正	Website Settings	head_html
CSS 変数（:root）	Website Settings	head_html

避けるべきこと

.card、section、h2 などのコンテンツ要素に対して、広範囲に !important で上書きしないでください。余白がおかしい場合、その原因はほぼ常に Frappe のラッパー div です。すべてのコンテンツスタイルを上書きするのではなく、該当するラッパーを個別に修正してください。

---

HTML モックアップからのデプロイ

静的な HTML モックアップを ERPNext Web Pages に変換する場合は、次の手順に従ってください。

1. body コンテンツを抽出する

メインコンテンツ領域の外側をすべて削除します。通常は </header> と <footer> の間です。Frappe は Website Settings で独自のナビゲーションとフッターを設定するため、モックアップ独自のナビゲーションとフッターを削除してください。

2. リンクを書き換える

.html ファイルへの参照を Frappe のルートに置き換えます。

href="about.html"  →  href="/about"
href="index.html"  →  href="/"

3. 画像を処理する

ローカルの img/ 参照は ERPNext では機能しません。次の方法があります。

• Frappe File Manager から画像をアップロードし、返された URL を使用する
• File API を使用する：POST /api/method/upload_file
• 外部の画像 URL を参照する

4. デプロイスクリプトのパターン

完全なデプロイスクリプトは scripts/deploy.py を参照してください。重要なパターンは次のとおりです。

import requests, json

def deploy_page(title, route, html_content, css):
    data = {
        "title": title,
        "route": route,
        "published": 1,
        "show_title": 0,
        "full_width": 1,
        "content_type": "Page Builder",
        "css": css,
        "page_blocks": [{
            "web_template": "Raw HTML Section",
            "web_template_values": json.dumps({"html_content": html_content})
        }]
    }
    # Create or update (check 409 conflict for existing pages)
    resp = requests.post(f"{BASE_URL}/api/resource/Web%20Page",
                         headers=HEADERS, json=data)
    if resp.status_code == 409:
        # Find and update existing
        ...

---

Frappe Discussions とのフォーラム連携

Frappe には、任意の Web Page に埋め込めるディスカッション用の DocType が組み込まれています。

使用可能な DocType

• Discussion Topic — 参照ドキュメントにリンクされたスレッド／トピック
• Discussion Reply — トピック内の返信

フォーラムページを作成する

組み込みの「Discussions」Web Template をページブロックとして使用します。

{
  "page_blocks": [
    {
      "web_template": "Raw HTML Section",
      "web_template_values": "{\"html_content\": \"<section><div class=\\\"container\\\"><h1>Forum</h1></div></section>\"}"
    },
    {
      "web_template": "Discussions",
      "web_template_values": "{\"title\": \"Discussies\", \"cta_title\": \"Nieuw onderwerp\", \"docname\": \"forum\", \"single_thread\": 0}"
    }
  ]
}

Discussions Web Templateのフィールド

フィールド	種類	用途
title	データ	セクションの見出し
cta_title	データ	新しいトピックを作成するボタンのテキスト
docname	リンク	ディスカッションを紐付けるWebページ
single_thread	チェック	0 = 複数のトピック、1 = 単一のスレッド

APIを使ったトピックの管理

POST /api/resource/Discussion%20Topic
{"subject": "My topic", "reference_doctype": "Web Page", "reference_docname": "forum"}

POST /api/resource/Discussion%20Reply
{"topic": "TOPIC0001", "reply": "My reply text"}

---

認証

すべてのAPI呼び出しには、トークンヘッダーによる認証が必要です。

Authorization: token {api_key}:{api_secret}

ERPNextでAPIキーを生成します：ユーザー設定 → APIアクセス → キーを生成。

APIキーをスキルファイル、SKILL.mdに保存したり、gitにコミットしたりしないでください。 環境変数として渡すか、安全な設定ファイルから読み込んでください。

---

トラブルシューティング

ページが空白になる／main_sectionがレンダリングされない

v16のPage Builderの問題が発生しています。content_type: "Page Builder"とpage_blocksに切り替えてください。ステップ2を参照してください。

コンテンツの上に白いバーが表示される

Frappeの.page-header-wrapperと.page-breadcrumbsが空白を追加しています。head_htmlを使って非表示にしてください。ステップ3を参照してください。

フィールドタイプのエラーでWeb Templateの作成に失敗する

フィールドタイプには"Code"ではなく"Text"を使用してください。FrappeのWeb Templateで使用できるフィールドタイプは一部に限られています。

CSSの表示がおかしい／余白がずれている

Frappeの.section.section-padding-topや.page-content-wrapperがパディングを追加していないか確認してください。これらを個別に修正し、!importantでコンテンツのCSSを上書きしないでください。

グリッドレイアウトが1列に折りたたまれる

モックアップのCSSにグリッド列を上書きするメディアクエリがある場合、ERPNextでも適用されます。レンダリングされたCSSに、競合するメディアクエリのルールがないか確認してください。

画像が表示されない

モックアップのローカルなimg/パスは解決されません。ファイルをERPNextにアップロードするか、絶対URLを使用してください。