API de documents
L'API de documents donne accès aux documents Dodock en Python. Chaque document est une instance de la classe frappe.model.document.Document. Il représente une ligne de la table du type de document.
Les exemples de cette page utilisent le type de document Tâche (Task) et des noms fictifs.
frappe.get_doc
frappe.get_doc(doctype, name)
Renvoie l'objet Document identifié par son type de document et son nom. Pour un type de document unique (Single), le nom n'est pas nécessaire.
# Obtenir un document existant
doc = frappe.get_doc('Task', 'TASK00002')
doc.title = 'Test'
doc.save()
# Obtenir un document unique
doc = frappe.get_doc('System Settings') # ou frappe.get_single('System Settings')
doc.time_zone # 'Europe/Paris'
frappe.get_doc(dict)
Renvoie un nouvel objet Document en mémoire. Le document n'existe pas encore dans la base de données. Appelez insert() pour l'enregistrer.
# Crée un nouveau document
doc = frappe.get_doc({
'doctype': 'Task',
'title': 'New Task'
})
doc.insert()
frappe.get_doc(doctype={document_type}, key1 = value1, key2 = value2, ...)
Renvoie un nouvel objet Document en mémoire, à partir d'arguments nommés.
# Crée un nouvel objet avec des arguments nommés
todo = frappe.get_doc(doctype='ToDo', description='Rappeler le client')
todo.insert()
frappe.get_cached_doc
Même signature que frappe.get_doc. Cherche d'abord le document dans le cache, puis dans la base de données. Utilisez-la pour lire un document. Ne modifiez pas un document obtenu depuis le cache.
company = frappe.get_cached_doc('Company', 'Menuiserie Élégante')
frappe.new_doc
frappe.new_doc(doctype)
Crée un nouveau Document en mémoire, avec les valeurs par défaut du type de document.
# Crée un nouveau Document
doc = frappe.new_doc('Task')
doc.title = 'New Task 2'
doc.insert()
frappe.delete_doc
frappe.delete_doc(doctype, name, force=False, ignore_permissions=False, ignore_missing=True, delete_permanently=False)
Supprime le document et ses lignes de tables enfants. Supprime aussi les documents rattachés, comme les commentaires. Sauf avec delete_permanently=True, Dodock garde une copie dans Document supprimé (Deleted Document). Avec force=True, Dodock supprime le document même s'il est lié à d'autres documents.
frappe.delete_doc('Task', 'TASK00002')
frappe.rename_doc
frappe.rename_doc(doctype, old, new, force=False, merge=False)
Renomme un document, c'est-à-dire change sa clé primaire name. Dodock met à jour tous les champs Lien qui pointent vers ce document. Avec merge=True, si un document porte déjà le nouveau nom, Dodock fusionne les deux documents.
frappe.rename_doc('Task', 'TASK00002', 'TASK00003')
allow_rename). Sinon, Dodock refuse le renommage, sauf avec force=True ou ignore_permissions=True.frappe.get_meta
frappe.get_meta(doctype)
Renvoie les métadonnées d'un type de document. Les métadonnées incluent les champs personnalisés et les propriétés modifiées par Personnaliser un formulaire.
meta = frappe.get_meta('Task')
meta.has_field('status') # True
meta.get_custom_fields() # [field1, field2, ..]
Pour obtenir la définition d'origine, sans champs personnalisés ni propriétés modifiées, utilisez frappe.get_doc('DocType', nom_du_doctype).
Méthodes de document
Cette section liste les méthodes courantes d'un objet Document.
doc.insert
Insère un nouveau document dans la base de données. Dodock contrôle les autorisations de l'utilisateur. Il exécute ensuite les méthodes before_insert, validate, on_update et after_insert du contrôleur, si elles existent.
Des arguments désactivent certains contrôles :
doc.insert(
ignore_permissions=True, # ignore la validation des autorisations de l'utilisateur
ignore_links=True, # ignore la validation des liens présents dans le document
ignore_if_duplicate=True, # n'insère pas le document si un document avec un identifiant identique existe déjà
ignore_mandatory=True # insère même si certains champs obligatoires ne sont pas remplis
)
doc.save
Enregistre les modifications d'un document existant. Dodock contrôle les autorisations de l'utilisateur. Il exécute validate avant l'écriture et on_update après.
doc.save(
ignore_permissions=True, # ignore les autorisations de l'utilisateur
ignore_version=True # ne crée pas de document de Version pour cette mise à jour
)
doc.delete
Supprime le document de la base de données. Cette méthode appelle frappe.delete_doc.
doc.delete()
doc.get_doc_before_save
Renvoie le document tel qu'il était avant les modifications en cours. Utilisez-la dans validate ou on_update pour savoir quels champs ont changé. Pour un nouveau document, elle renvoie None.
old_doc = doc.get_doc_before_save()
if old_doc and old_doc.status != doc.status:
# le statut a changé
pass
doc.reload
Relit les valeurs du document dans la base de données. Utilisez-la quand un autre code a modifié le document directement en base, par exemple avec frappe.db.set_value.
doc.reload()
doc.check_permission
Lève une erreur frappe.PermissionError si l'utilisateur de la session n'a pas l'autorisation demandée sur ce document.
doc.check_permission(permtype='write') # erreur si l'utilisateur ne peut pas modifier le document
doc.get_title
Renvoie le titre du document : la valeur du champ défini dans title_field, sinon du champ title, sinon le nom.
title = doc.get_title()
doc.notify_update
Publie un événement en temps réel pour signaler que le document a changé. Les formulaires ouverts sur ce document se mettent à jour.
doc.notify_update()
doc.db_set
doc.db_set(fieldname, value=None, update_modified=True, notify=False, commit=False)
Écrit la valeur d'un champ directement dans la base de données. Par défaut, met aussi à jour la date de modification. fieldname peut aussi être un dictionnaire {champ: valeur}.
# Écrit la valeur et met à jour la date de modification
doc.db_set('status', 'Completed')
# Écrit la valeur et appelle doc.notify_update()
doc.db_set('status', 'Completed', notify=True)
# Écrit la valeur et appelle frappe.db.commit()
doc.db_set('status', 'Completed', commit=True)
# Écrit la valeur sans changer la date de modification
doc.db_set('status', 'Completed', update_modified=False)
# Écrit plusieurs champs
doc.db_set({'status': 'Completed', 'progress': 100})
doc.get_url
Renvoie le chemin du formulaire du document dans le bureau, par exemple /desk/task/TASK00002.
url = doc.get_url()
doc.add_comment
doc.add_comment(comment_type='Comment', text=None, comment_email=None, comment_by=None)
Ajoute un commentaire au document. Le commentaire s'affiche dans la chronologie du formulaire.
# Ajoute un simple commentaire
doc.add_comment('Comment', text='Test Comment')
# Ajoute un commentaire de type 'Edit/Modification'
doc.add_comment('Edit', 'Values changed')
# Ajoute un commentaire de type 'Shared/Partagé'
doc.add_comment("Shared", f"{user} a partagé ce document avec tout le monde")
doc.add_seen
Ajoute l'utilisateur indiqué, ou l'utilisateur de la session, à la liste des utilisateurs qui ont vu le document. La liste est stockée en JSON dans la colonne _seen.
# Ajoute John à la liste
doc.add_seen('john@doe.com')
# Ajoute l'utilisateur de la session
doc.add_seen()
track_seen (« Suivre les personnes l'ayant vu ») et n'est pas unique.doc.add_viewed
doc.add_viewed(user=None, force=False, unique_views=False)
Crée une entrée dans le Journal des vues (View Log) pour l'utilisateur. Avec unique_views=True, Dodock ne crée pas de deuxième entrée pour le même utilisateur.
# Ajoute une entrée dans le journal des vues pour l'utilisateur John
doc.add_viewed('john@doe.com')
# Ajoute une entrée dans le journal des vues pour l'utilisateur actif
doc.add_viewed()
track_views (« Suivre les vues »), ou avec force=True.doc.run_method
Exécute la méthode du contrôleur si elle existe. Exécute aussi les doc_events déclarés dans le hooks.py des applications pour cette méthode.
doc.run_method('validate')
doc.queue_action
Exécute une méthode du contrôleur dans une tâche d'arrière-plan. Si une méthode interne existe, comme _submit pour submit, Dodock appelle la méthode interne. Le document reste verrouillé pendant la tâche. Par défaut, la tâche part après le commit de la transaction en cours.
doc.queue_action('submit')