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.

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')

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.

# 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()

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()

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')