API de documents
L'API de documents donne accès aux instances de types de documents Dodock. Chaque instance est dérivée de la classe frappe.model.Document et représente une entrée unique dans la table correspondante de la base de données.
L'API de documents donne accès aux instances de types de documents Dodock.
Chaque instance est dérivée de la classe frappe.model.Document et représente une entrée unique dans la table correspondante de la base de données.
frappe.get_doc
frappe.get_doc(doctype, name)
Renvoie un object de type Document pour une entrée identifiée par un type de document et un nom.
Si le type de document est Unique, le nom n'est pas requis.
# 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') # Vous pouvez aussi utilise frappe.get_single('System Settings')
doc.timezone # Asia/Kolkata
frappe.get_doc(dict)
Renvoi en mémoire un nouvel object de type Document qui n'existe pas encore dans la base de données.
# Création d'un nouveau Document
doc = frappe.get_doc({
'doctype': 'Task',
'title': 'New Task'
})
doc.insert()
frappe.get_doc(doctype={document_type}, key1 = value1, key2 = value2, ...)
Renvoi en mémoire un nouvel objet de type Document qui n'existe pas encore dans la base de données.
# Crée un nouvel object avec des arguments sous forme de clé/valeur
user = frappe.get_doc(doctype='User', email_id='test@example.com')
user.insert()
frappe.get_cached_doc
Similaire à frappe.get_doc, mais cherche d'abord le document dans le cache avant de requêter la base de données.
frappe.new_doc
frappe.new_doc(doctype)
Méthode alternative pour créer un nouveau 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)
Supprime les entrées et les entrées enfant associées de la base de données.
Supprime également d'autre documents liés comme les Communication, Commentaires, etc...
frappe.delete_doc('Task', 'TASK00002')
frappe.rename_doc
frappe.rename_doc(doctype, old_name, new_name, merge=False)
Renomme un document (modification de la clé primaire).
Si l'option merge=True et qu'un document existe déjà avec le nouveau nom, le document renommé sera fusionné avec le document existant.
frappe.rename_doc('Task', 'TASK00002', 'TASK00003')
Le renommage ne sera autorisé que si l'option correspondante est activée dans le formulaire du type de document correspondant.
frappe.get_meta
frappe.get_meta(doctype)
Renvoi les métadonnées associées à un type de document.
Renvoi également pour les champs personnalisés et les propriétés personnalisées.
meta = frappe.get_meta('Task')
meta.has_field('status') # True
meta.get_custom_fields() # [field1, field2, ..]
Pour obtenir le document original, sans champs personnalisés ou propriétés personnalises, utilisez frappe.get_doc('DocType', doctype_name)
Méthodes de document
Cette section liste les méthodes communes disponibles dans un objet de type Document.
doc.insert
Cette méthode insert un nouveau document dans la table de la base de données.
Elle déclenche la vérification des autorisations utilisateur et exécute les méthodes before_insert, validate, on_update, after_insert si elles présentes dans le contrôleur.
Des flags permettent de ne pas déclencher certaines vérification.
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
Cette méthode enregistrte les changements apportés à un document existant.
Elle déclenche la vérification des autorisations utilisateur et exécute les méthodes validate avant la mise à jour et on_update après la mise à jour des valeurs.
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 l'entrée du document de la table de la base de données.
Cette méthode est un alias pour frappe.delete_doc
doc.delete()
doc.get_doc_before_save
Renvoi la version du document avant les modifications qui viennent d'être effectuées.
Vous pouvez l'utiliser pour comparer ce qui a été modifié depuis la denière version.
old_doc = doc.get_doc_before_save()
if old_doc.price != doc.price:
# le prix a changé
pass
doc.reload
Requête les dernières valeurs dans la base de données et mets à jour l'état du document. Quand vous travaillez avec un document, il peut arriver qu'une autre fonction dans le code mette à jour des valeurs dans ce document directement dans la base de données. Dans ce cas vous pouvez utiliser cette méthode pour recharger le document.
doc.reload()
doc.check_permission
Renvoi une erreur si l'utilisateur de la session n'a pas les autorisations pour le type d'autorisation demandé.
doc.check_permission(permtype='write') # Renvoi une erreur si l'utilisateur n'a pas les droits d'écrire sur ce document
doc.get_title
Obtenez le titre du document sur la base de la métadonnée title_field ou d'un champ appelé title ou name.
title = doc.get_title()
doc.notify_update
Publie un événement en temps réel pour indiquer que le document a été modifié.
Des gestionnaires d'événement côté client réagissent à cet événement et mettent à jour le formulaire.
doc.notify_update()
doc.db_set
Inscrit la value d'un champ du document directement dans la base de données et mets à jour la date et heure de modification.
Cette méthode ne déclenche pas de validations de contrôleur et doit être utilisée avec attention.
# Mets à jour la valeur dans la base de données, mets à jour l'horodatage du document
doc.db_set('price', 2300)
# Mets à jour la valeur dans la base de données et déclenche doc.notify_update()
doc.db_set('price', 2300, notify=True)
# Mets à jour la valeur dans la base de données et déclenche frappe.db.commit()
doc.db_set('price', 2300, commit=True)
#Mets à jour la valeur dans la base de données sans mettre à jour l'horodatage
doc.db_set('price', 2300, update_modified=False)
doc.get_url
Renvoie l'URL vers ce document. Ex./app/task/TASK00002
url = doc.get_url()
doc.add_comment
Ajoute un commentaire au document. Le commentaire sera visible dans la chronologie de la vue de 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", "{0} a partagé ce document avec tout le monde".format(user))
doc.add_seen
Ajoute l'utilisateur actif/donné à la liste des utilisateurs ayant vu ce document.
Cette méthode mets à jour la colonne _seen de la table et stocke les données au format JSON.
# Ajoute John à la liste des utilisateurs ayant vu le document
doc.add_seen('john@doe.com')
# Ajoute l'utilisateur actif à la liste des utilisateurs ayant vu le document
doc.add_seen()
Cette méthode ne fonctionne que Suivre les vues de document est activé dans le type de document.
doc.add_viewed
Ajoute une entrée au journal des vues quand un utilisateur voit le document (ouvre le formulaire).
# 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()
Cette méthode ne fonctionne que si "Suivre les vues de document" est activé pour ce type de document.
doc.run_method
Exécute une méthode si elle définie dans le contrôleur et déclenche également les hooks correspondants.
doc.run_method('validate')
doc.queue_action
Exécute une méthode de contrôleur en tâche de fons.
Si la méthode a une fonction interne, comme _submit pour submit, cette fonction interne sera appelée à la place.
doc.queue_action('send_emails', emails=email_list, message='Howdy')