frappe-syntax-hooks

Frappe 設定フック（hooks.py）

hooks.py の設定フックを使うと、カスタムアプリで Frappe/ERPNext の動作を拡張できます。このスキルでは、ドキュメントイベント以外のすべてのフックを扱います。doc_events （validate、on_submit、on_update など）については、frappe-syntax-hooks-events を参照してください。

クイックリファレンス：フックのカテゴリ

カテゴリ	主なフック	リファレンス
アプリのメタデータ	app_name、app_title、required_apps	以下
フロントエンドアセット	app_include_js/css、web_include_js/css	以下
インストール／マイグレーション	before_install、after_install、after_migrate	以下
スケジューラー	hourly、daily、cron、*_long	scheduler-events.md
セッション／認証	on_login、on_logout、auth_hooks	bootinfo.md
リクエストミドルウェア	before_request、after_request	request-lifecycle.md
権限	permission_query_conditions、has_permission	permissions.md
DocType のオーバーライド	override_doctype_class、doctype_js	overrides.md
Webサイト／ポータル	website_route_rules、portal_menu_items	request-lifecycle.md
ファイル処理	before_write_file、write_file	以下
メール	override_email_send、default_mail_footer	以下
PDF	pdf_header_html、pdf_footer_html	以下
Jinja	jinja.methods、jinja.filters	以下
起動時／クライアントデータ	extend_bootinfo、notification_config	bootinfo.md
データ／フィクスチャ	fixtures、global_search_doctypes	以下
メソッドのオーバーライド	override_whitelisted_methods、standard_queries	overrides.md

---

判断フロー：どのフックが必要ですか？

What do you want to achieve?
|
+-- ADD JS/CSS to desk or portal?
|   +-- Desk --> app_include_js / app_include_css
|   +-- Portal --> web_include_js / web_include_css
|   +-- Specific form --> doctype_js
|   +-- List view --> doctype_list_js
|
+-- RUN periodic background tasks?
|   +-- < 5 min execution --> hourly / daily / weekly / monthly
|   +-- 5-25 min execution --> hourly_long / daily_long / etc.
|   +-- Exact time needed --> cron
|   See: frappe-syntax-hooks > scheduler-events.md
|
+-- SEND data to client at page load?
|   +-- extend_bootinfo
|
+-- MODIFY controller of existing DocType?
|   +-- v16+ --> extend_doctype_class (RECOMMENDED)
|   +-- v14/v15 --> override_doctype_class (last app wins)
|
+-- MODIFY API endpoint?
|   +-- override_whitelisted_methods
|
+-- CUSTOMIZE permissions?
|   +-- List filtering --> permission_query_conditions
|   +-- Document-level --> has_permission
|
+-- REACT to document save/submit/delete?
|   +-- See frappe-syntax-hooks-events skill
|
+-- EXPORT/IMPORT configuration?
|   +-- fixtures
|
+-- SETUP on install or migrate?
|   +-- after_install / after_migrate
|
+-- ADD custom Jinja functions?
|   +-- jinja.methods / jinja.filters
|
+-- CUSTOMIZE website routing?
|   +-- website_route_rules
|   See: request-lifecycle.md for full routing pipeline
|
+-- INTERCEPT every request/response?
|   +-- before_request / after_request
|   See: request-lifecycle.md for lifecycle flow
|
+-- CUSTOM page rendering?
|   +-- page_renderer hook
|   See: request-lifecycle.md for renderer architecture

---

1. アプリのメタデータフック

すべての hooks.py に必ず含めてください：

app_name = "myapp"
app_title = "My App"
app_publisher = "My Company"
app_description = "Custom ERPNext extensions"
app_email = "[email protected]"
app_license = "MIT"
required_apps = ["erpnext"]  # Declare dependencies

---

2. フロントエンドアセットの挿入

# Desk (backend UI) assets — loaded on EVERY desk page
app_include_js = "/assets/myapp/js/myapp.min.js"       # string or list
app_include_css = "/assets/myapp/css/myapp.min.css"

# Website/portal assets — loaded on EVERY web page
web_include_js = "/assets/myapp/js/web.min.js"
web_include_css = "/assets/myapp/css/web.min.css"

# Web form specific assets
webform_include_js = {"My Web Form": "public/js/my_webform.js"}
webform_include_css = {"My Web Form": "public/css/my_webform.css"}

# Form script extensions (extend OTHER apps' forms)
doctype_js = {"Sales Invoice": "public/js/sales_invoice.js"}

# List view script extensions
doctype_list_js = {"Sales Invoice": "public/js/sales_invoice_list.js"}

# Custom sounds
sounds = [{"name": "alert", "src": "/assets/myapp/sounds/alert.mp3", "volume": 0.5}]

app_include_js に大きなライブラリを入れないでください。すべてのページで読み込まれます。

---

3. インストールとマイグレーションのライフサイクル

before_install = "myapp.setup.before_install"
after_install = "myapp.setup.after_install"
after_sync = "myapp.setup.after_sync"            # After fixture sync
before_migrate = "myapp.setup.before_migrate"
after_migrate = "myapp.setup.after_migrate"
before_uninstall = "myapp.setup.before_uninstall"
after_uninstall = "myapp.setup.after_uninstall"
before_tests = "myapp.setup.seed_test_data"

いずれもドット区切りのパス文字列を 1 つ受け付けます。関数には引数が渡されません。

---

4. スケジューラーイベント

詳しくは scheduler-events.md を参照してください。

scheduler_events = {
    "all": ["myapp.tasks.every_minute"],            # ~60s interval
    "hourly": ["myapp.tasks.hourly_check"],         # default queue, 5 min timeout
    "daily": ["myapp.tasks.daily_report"],
    "weekly": ["myapp.tasks.weekly_cleanup"],
    "monthly": ["myapp.tasks.monthly_summary"],
    "daily_long": ["myapp.tasks.heavy_sync"],       # long queue, 25 min timeout
    "cron": {
        "0 9 * * 1-5": ["myapp.tasks.weekday_morning"]  # cron expression
    }
}

scheduler_events を変更した後は、必ず bench --site sitename migrate を実行してください。 タスク関数に引数を定義しないでください。引数は渡されません。

---

5. セッション／認証フック

on_login = "myapp.auth.on_login"                     # Receives login_manager
on_logout = "myapp.auth.on_logout"                   # No arguments
on_session_creation = "myapp.auth.on_session_creation"  # No arguments
auth_hooks = ["myapp.auth.validate_request"]          # List of validators

実行順序：on_login --> セッション作成 --> on_session_creation --> extend_bootinfo。

---

6. リクエスト／レスポンスミドルウェア

リクエストのライフサイクル全体の流れ、ページレンダラーのアーキテクチャ、ルーター API については、request-lifecycle.md を参照してください。

before_request = ["myapp.middleware.before_request"]   # List of dotted paths
after_request = ["myapp.middleware.after_request"]
before_job = ["myapp.middleware.before_job"]            # Before background job
after_job = ["myapp.middleware.after_job"]              # After background job

---

7. 権限フック

詳しくは permissions.md を参照してください。

permission_query_conditions = {
    "Sales Invoice": "myapp.permissions.si_query_conditions"
}
has_permission = {
    "Sales Invoice": "myapp.permissions.si_has_permission"
}

ハンドラーでは必ず if not user: user = frappe.session.user を確認してください。 SQL では必ず frappe.db.escape(user) を使用し、文字列補間は決して使用しないでください。 permission_query_conditions が機能するのは get_list のみで、get_all では機能しません。

---

8. DocType クラスのオーバーライド

詳しくは overrides.md を参照してください。

# v14+ — Full replacement (LAST installed app wins)
override_doctype_class = {
    "Sales Invoice": "myapp.overrides.CustomSalesInvoice"
}

# v16+ — Mixin-based extension (ALL apps coexist) [RECOMMENDED]
extend_doctype_class = {
    "Address": ["myapp.extensions.AddressMixin"]
}

オーバーライドでは必ず super().method() を呼び出してください。super() を呼び忘れると、コアロジックが壊れます。

---

9. Webサイト／ポータルフック

# URL routing
website_route_rules = [
    {"from_route": "/custom-page/<name>", "to_route": "Custom Page"}
]
website_redirects = [
    {"source": "/old-url", "target": "/new-url"}
]
website_catch_all = "myapp.www.custom_404"

# Homepage
homepage = "my-custom-home"
role_home_page = {"Sales User": "sales-dashboard"}
get_website_user_home_page = "myapp.utils.get_home_page"

# Portal sidebar
portal_menu_items = [{"title": "My Orders", "route": "/orders", "role": "Customer"}]
standard_portal_menu_items = [{"title": "My Items", "route": "/my-items"}]

# Template overrides
base_template = "myapp/templates/base.html"
website_context = {"brand_html": "<b>My Brand</b>"}
update_website_context = "myapp.context.update_context"

---

10. ファイル処理フック

before_write_file = "myapp.files.before_write"      # Pre-save hook
write_file = "myapp.files.custom_write"              # Replace file storage (e.g., S3/CDN)
delete_file_data_content = "myapp.files.custom_delete"  # Replace file deletion

ファイルストレージをクラウドプロバイダー（S3、GCS、Azure Blob）に切り替えるには、write_file を使用してください。

---

11. メールフック

override_email_send = "myapp.email.custom_send"       # Replace email backend
get_sender_details = "myapp.email.get_sender"          # Override From address
default_mail_footer = "myapp.email.get_footer"         # HTML footer for all emails

---

12. PDF フック

pdf_header_html = "myapp.pdf.get_header"               # Custom PDF header
pdf_body_html = "myapp.pdf.get_body"                    # Custom PDF body wrapper
pdf_footer_html = "myapp.pdf.get_footer"                # Custom PDF footer
# pdf_generator = "myapp.pdf.generate"                  # [v16+] Replace PDF engine

---

13. Jinja フック

# Add custom methods available in Jinja templates
jinja = {
    "methods": ["myapp.jinja_utils.get_balance"],
    "filters": ["myapp.jinja_utils.format_iban"]
}

# myapp/jinja_utils.py
def get_balance(customer):
    """Usage in template: {{ get_balance(doc.customer) }}"""
    return frappe.db.get_value("Customer", customer, "outstanding_amount") or 0

def format_iban(value):
    """Usage in template: {{ bank_account|format_iban }}"""
    if not value: return ""
    return " ".join([value[i:i+4] for i in range(0, len(value), 4)])

---

14. 起動時／クライアントデータ

詳しくは bootinfo.md を参照してください。

extend_bootinfo = "myapp.boot.extend_boot"
notification_config = "myapp.notifications.get_config"

bootinfo にシークレットや API キーを入れないでください。ブラウザーに送信されます。 bootinfo で負荷の高いクエリを実行しないでください。すべてのページ読み込み時に実行されます。

---

15. データとフィクスチャ

fixtures = [
    {"dt": "Custom Field", "filters": [["module", "=", "My App"]]},
    {"dt": "Property Setter", "filters": [["module", "=", "My App"]]},
    {"dt": "Role", "filters": [["name", "like", "MyApp%"]]}
]

global_search_doctypes = {"My DocType": {"index": 10}}
ignore_links_on_delete = ["Communication", "Activity Log"]
calendars = ["My Event DocType"]
clear_cache = "myapp.cache.clear_custom_cache"

フィクスチャでは必ずフィルターを使用してください。フィルターなしでエクスポートしてはいけません（すべてがエクスポートされます）。 トランザクションデータ（Sales Invoice、Stock Entry）をフィクスチャに含めてはいけません。

---

16. メソッドのオーバーライド

詳細については、overrides.md を参照してください。

override_whitelisted_methods = {
    "frappe.client.get_count": "myapp.overrides.custom_get_count"
}
standard_queries = {
    "Customer": "myapp.queries.customer_query"
}

オーバーライドする際は、必ず元のメソッドシグネチャと完全に一致させてください。

---

バージョンによる違い

Hook	v14	v15	v16+
extend_doctype_class	--	--	NEW
extend_bootinfo	Yes	Yes	Yes
auth_hooks	Yes	Yes	Yes
after_sync	Yes	Yes	Yes
before_uninstall	--	Yes	Yes
after_uninstall	--	Yes	Yes
website_path_resolver	--	Yes	Yes
その他すべての Hook	Yes	Yes	Yes

---

重要なルール

1. hooks.py を変更した後は、必ず bench --site sitename migrate を実行してください
2. hooks.py のモジュールレベルで frappe をインポートしてはいけません。初期化前に実行されるためです
3. 必ずドット区切りのパス（"myapp.module.function"）を使用してください。ラムダは使用してはいけません
4. Hook ハンドラー内でコミットしてはいけません。トランザクションは Frappe が管理します
5. デプロイ前に、必ず開発環境で Hook をテストしてください

---

アンチパターンのまとめ

誤り	正しい方法
フィクスチャにフィルターがない	必ずモジュールまたはアプリでフィルターする
bootinfo にシークレットを含める	bootinfo には公開設定のみを含める
bootinfo で重いクエリを実行する	データをキャッシュするか、最小限にする
権限 Hook で get_all を使う	権限フィルタリングには get_list を使う
super() を呼び出さずにオーバーライドする	必ず最初に super().method() を呼び出す
引数付きのスケジューラータスク	タスクは引数を受け取りません
bench migrate を省略する	Hook の変更後は必ずマイグレーションする

アンチパターンの全一覧：anti-patterns.md

---

参考ファイル

ファイル	内容
hooks.md	カテゴリー別の Hook 完全一覧
scheduler-events.md	スケジューラーの実行頻度、cron 構文、タイムアウト
permissions.md	権限 Hook の詳細
overrides.md	DocType クラスのオーバーライドパターン
bootinfo.md	extend_bootinfo、セッション Hook、notification_config
examples.md	各カテゴリーの動作する hooks.py の例
request-lifecycle.md	リクエストのライフサイクル、ルーティングパイプライン、ページレンダラー、ルーター API
anti-patterns.md	よくある Hook の誤りと修正方法

ドキュメントのライフサイクルイベント（doc_events）については、frappe-syntax-hooks-events を参照してください。