Hooks

Fonctionnement

Un hook est un point du cœur où une application remplace ou étend le comportement, dans hooks.py. frappe.get_hooks transforme chaque valeur en liste, même une chaîne ou un dictionnaire : test_string = "value" revient ["value"], et test_dict voit ses valeurs enveloppées. Si plusieurs applications définissent le hook, les valeurs sont rassemblées. Selon l’auteur, on les inclut toutes (app_include_js) ou une seule gagne.

La dernière application installée a la priorité, « last writer wins ». Un remplacement, par exemple une classe, ne garde que la dernière. Une extension s’applique dans l’ordre d’installation. L’ordre se change dans Installed Applications, Update Hooks Resolution Order.

Les métadonnées sont générées à la création : app_name, app_title, app_publisher, app_description, app_version, app_icon, app_color. La liste officielle ajoute app_logo_url.

Assets, sons, cycle

Bureau : app_include_js et app_include_css dans desk.html, un chemin ou une liste. Portail : web_include_js et web_include_css dans web.html. Web Form standard : dictionnaires webform_include_js et webform_include_css par DocType. Un Web Form créé par l’utilisateur porte son script dans la fiche. Page standard : page_js, par exemple background_jobs. Le bureau et les pages du portail reçoivent ces fichiers.

sounds ajoute un nom, une source et un volume. frappe.utils.play_sound("ping") le joue.

before_install, after_install, after_sync (après les fixtures). before_uninstall, after_uninstall. before_migrate, after_migrate autour de bench migrate. after_build après le build de sa propre application. after_app_build n’existe que sur la branche develop : il tourne à chaque build, y compris pour les assets destinés à d’autres applications. built_apps vaut --app / --apps, ou toutes les applications si bench build n’a pas d’argument. before_tests sème des données avant les tests.

Fichiers : before_write_file, write_file (remplace l’écriture, par exemple un CDN), delete_file et delete_file_data_content. E-mail : l’expéditeur peut devenir un couple nom et adresse, l’exemple John Doe. send reçoit la file, l’expéditeur, le destinataire et le message. Le texte écrit « refrence ».

Site web

Après connexion, extend_bootinfo enrichit bootinfo, lu en JavaScript dans frappe.boot : défauts, notifications, droits. update_website_context et website_context modifient le contexte d’une page. extend_website_page_controller_context étend des pages livrées, comme /404 et /about. get_web_pages_with_dynamic_routes déclare des routes à valeur variable. website_clear_cache invalide un cache applicatif. website_redirects répond 304, URL simple ou expression. website_route_rules mappe une URL vers un contrôleur. website_path_resolver remplace la résolution standard, par exemple /profile vers /me. website_catch_all change la 404. L’accueil par défaut est index. home_page, get_website_user_home_page et role_home_page le changent. website_user_home_page est déprécié au profit d’un hook homepage, nom cité par le tableau. portal_menu_items et standard_portal_menu_items règlent la barre. brand_html remplace le logo : l’exemple est une image tennismart.png et le texte TennisMart. La page conseille Website Settings, sauf si l’on veut versionner le logo. base_template remplace templates/base.html. base_template_map est aussi listé.

never_skip_patches liste des patches qui doivent arrêter bench migrate --skip-failing. Les sauter peut faire fuiter des données. L’exemple est app.patches.v16_0.critical_data_fix.

Documents

permission_query_conditions ajoute un fragment WHERE. L’exemple ToDo limite au propriétaire ou à assigned_by. has_permission complète doc.has_permission. has_website_permission est listé sans texte.

Depuis la v16, extend_doctype_class ajoute méthodes et propriétés sans remplacer la classe, et plusieurs applications peuvent étendre le même DocType. L’ordre des hooks s’applique. Avec override_doctype_class, les extensions s’appliquent à la classe déjà remplacée. L’exemple final est ExtendedAddress(Prop2Mixin, Prop1Mixin, ERPNextAddress).

override_doctype_class remplace toute la classe. Plusieurs applications sur le même DocType se gênent. La page renvoie vers l’extension à partir de la v16. doctype_js étend les scripts de formulaire. override_doctype_dashboards est listé sans texte.

doc_events accroche le cycle. "*" vise tous les DocTypes. L’exemple appelle after_insert partout et before_insert sur ToDo. La méthode reçoit le document et le nom de méthode. La liste complète des événements de contrôleur n’est pas recopiée ici. override_whitelisted_methods remplace une méthode en liste blanche en gardant la signature. L’exemple détourne frappe.client.get_count. ignore_links_on_delete ignore des liens à la suppression, Communication et ToDo dans l’exemple. additional_timeline_content ajoute à la chronologie. on_print_pdf à l’impression. treeviews choisit l’arbre plutôt que la liste.

Planificateur et reste

scheduler_events : hourly, daily, weekly, monthly, et les variantes _long pour le worker long. all toutes les 60 secondes, ou scheduler_tick_interval du commun. cron est une chaîne lue par croniter, ou la clé annual dans l’exemple. Après un changement, bench migrate. Plusieurs chemins publiés ont deux points : app.scheduled_tasks..take_backups_daily.

jinja ajoute méthodes et filtres. Le tableau le nomme aussi jenv. Voir Jinja. auto_cancel_exempted_doctypes empêche l’annulation automatique. notification_config règle le menu de notifications. required_apps exige d’autres applications. user_data_fields définit les données personnelles. user_privacy_documents est déprécié au profit de ce hook. signup_form_template ajoute des champs au formulaire d’inscription. send_sms remplace l’envoi général. send_token_via_sms remplace l’OTP de la double authentification et de la connexion mobile.

braintree_success_page change la redirection après paiement. calendars liste des DocTypes du menu Calendrier. clear_cache vide le cache de l’application quand le cache global part. default_mail_footer pose le pied des e-mails. on_login juste après la connexion, on_session_creation après la session, on_logout à la sortie. Les hooks d’authentification valident en-têtes et Authorization, puis frappe.set_user(). fixtures synchronise des enregistrements JSON à l’installation et à la mise à jour.

Dépréciés dans le tableau : bot_parsers, dump_report_map, website_generators (utiliser Has Web View), write_file_keys. D’autres noms y figurent sans explication : communication_doctypes, domains, filters_config, get_site_info, get_translated_dict, leaderboards, look_for_sidebar_json, make_email_body_message, standard_queries (lien externe), setup_wizard_complete, setup_wizard_exception, setup_wizard_requires, setup_wizard_stages, setup_wizard_success, template_apps, translated_languages_for_website, translator_url, welcome_email.

Point d’attention

Un hook qui remplace ne se cumule pas : la dernière application installée gagne. never_skip_patches empêche --skip-failing d’ignorer ces patches. after_app_build n’est pas sur une version publiée, seulement develop.