Document API

Sebuah Document adalah instance dari DocType. Document ini diturunkan dari kelas frappe.model.Document dan mewakili satu catatan dalam tabel database.

frappe.get_doc

frappe.get_doc(doctype, name)

Mengembalikan objek Document dari catatan yang diidentifikasi oleh doctype dan name. Jika tidak ada dokumen yang ditemukan, DoesNotExistError akan diberikan. Jika doctype adalah Single DocType name tidak diperlukan.

# dapatkan dokumen yang ada
doc = frappe.get_doc('Task', 'TASK00002')
doc.title = 'Test'
doc.save()

# dapatkan single doctype
doc = frappe.get_doc('System Settings')
doc.timezone # Asia/Kolkata

frappe.get_doc(dict)

Mengembalikan objek Document baru dalam memori yang belum ada di database.

# buat dokumen baru
doc = frappe.get_doc({
    'doctype': 'Task',
    'title': 'New Task'
})
doc.insert()

frappe.get_doc(doctype={document_type}, key1 = value1, key2 = value2, ...)

Mengembalikan objek Document baru dalam memori yang belum ada di database.

# buat objek baru dengan argumen keyword
user = frappe.get_doc(doctype='User', email_id='test@example.com')
user.insert()

frappe.get_last_doc

frappe.get_last_doc(doctype, filters, order_by)

Mengembalikan objek Document terakhir yang dibuat di bawah doctype yang disebutkan.

# dapatkan Task terakhir yang dibuat
task = frappe.get_last_doc('Task')

Anda juga dapat menentukan filter untuk memperbaiki hasil Anda. Misalnya, Anda dapat mengambil Task terakhir yang dibatalkan dengan menambahkan filter.

# dapatkan Task Dibatalkan terakhir yang tersedia
task = frappe.get_last_doc('Task', filters={"status": "Cancelled"})

Secara default, argumen order_by diatur ke creation desc, tetapi nilai ini dapat diganti dengan menggunakan bidang non-standar lainnya yang dapat memiliki tujuan yang sama. Misalnya, Anda memiliki bidang timestamp di bawah DocType Task yang melacak waktu disetujui atau ditandai sebagai valid alih-alih waktu pembuatannya.

# dapatkan Task terakhir yang dibuat berdasarkan bidang non-standar
task = frappe.get_last_doc('Task', filters={"Status": "Cancelled"}, order_by="timestamp desc")

Alternatifnya, Anda dapat memilih untuk benar-benar mengabaikan semua ini dan sebagai bagian dari lelucon, mengubahnya menjadi "creation asc" untuk mengambil dokumen pertama sebagai gantinya.

frappe.get_cached_doc

Mirip dengan frappe.get_doc tetapi akan mencari dokumen di cache terlebih dahulu sebelum mengakses database.

frappe.new_doc

frappe.new_doc(doctype)

Cara alternatif untuk membuat Dokumen baru.

# buat dokumen baru
doc = frappe.new_doc('Task')
doc.title = 'New Task 2'
doc.insert()

frappe.delete_doc

frappe.delete_doc(doctype, name)

Menghapus catatan dan anak-anaknya dari database. Juga menghapus dokumen lain seperti Komunikasi, Komentar, dll. yang terhubung dengannya.

frappe.delete_doc('Task', 'TASK00002')

frappe.rename_doc

frappe.rename_doc(doctype, old_name, new_name, merge=False)

Mengganti name (kunci utama) dokumen dari old_name ke new_name. Jika merge diatur ke True dan ada catatan dengan new_name, catatan akan digabungkan dengannya.

frappe.rename_doc('Task', 'TASK00002', 'TASK00003')

Mengganti nama hanya akan berfungsi jika Allow Rename diatur di Formulir DocType.

frappe.get_meta

frappe.get_meta(doctype)

Mengembalikan informasi meta dari doctype. Ini juga akan menerapkan custom fields dan pengaturan properti.

meta = frappe.get_meta('Task')
meta.has_field('status') # True
meta.get_custom_fields() # [field1, field2, ..]

Untuk mendapatkan dokumen asli dari DocType (tanpa custom fields dan pengaturan properti), gunakan frappe.get_doc('DocType', doctype_name)

Document Methods

Bagian ini mencantumkan metode umum yang tersedia pada objek doc.

doc.insert

Metode ini menyisipkan dokumen baru ke dalam tabel database. Ini akan memeriksa izin pengguna dan menjalankan metode before_insert, validate, on_update, after_insert jika mereka ditulis di controller.

Ini memiliki beberapa pengecualian yang dapat digunakan untuk melewati beberapa pengecekan yang dijelaskan di bawah ini.

doc.insert(
    ignore_permissions=True, # abaikan izin tulis selama insert
    ignore_links=True, # abaikan validasi Link dalam dokumen
    ignore_if_duplicate=True, # jangan insert jika DuplicateEntryError muncul
    ignore_mandatory=True # insert meskipun mandatory fields belum diatur
)

doc.save

Metode ini menyimpan perubahan pada dokumen yang ada. Ini akan memeriksa izin pengguna dan menjalankan validate sebelum memperbarui dan on_update setelah memperbarui nilai.

doc.save(
    ignore_permissions=True, # abaikan izin tulis selama insert
    ignore_version=True # jangan buat catatan versi
)

doc.delete

Hapus catatan dokumen dari tabel database. Metode ini adalah alias untuk frappe.delete_doc.

doc.delete()

doc.get_doc_before_save

Akan mengembalikan versi dokumen sebelum perubahan dibuat. Anda dapat menggunakannya untuk membandingkan apa yang berubah dari versi terakhir.

old_doc = doc.get_doc_before_save()
if old_doc.price != doc.price:
    # harga berubah
    pass

doc.has_value_changed

Akan mengembalikan True jika nilai dari bidang yang diberikan berubah sebelum dan sesudah disimpan.

price_changed = doc.has_value_changed("price")

if price_changed:
    pass

doc.reload

Akan mendapatkan nilai terbaru dari database dan memperbarui status dokumen.

Saat Anda bekerja dengan dokumen, mungkin terjadi beberapa bagian lain dari kode memperbarui nilai dari beberapa bidang langsung di database. Dalam kasus tersebut, Anda dapat menggunakan metode ini untuk memuat ulang dokumen.

doc.reload()

doc.check_permission

Memberikan error jika pengguna saat ini tidak memiliki izin untuk permtype yang diberikan.

doc.check_permission(permtype='write') # memberikan error jika tidak ada izin tulis

doc.get_title

Dapatkan judul dokumen berdasarkan title_field atau bidang bernama title atau name.

title = doc.get_title()

doc.notify_update

Menerbitkan event realtime untuk menunjukkan bahwa dokumen telah dimodifikasi. Event handler sisi klien bereaksi terhadap event ini dengan memperbarui form.

doc.notify_update()

doc.db_set

Atur nilai bidang dokumen langsung di database dan perbarui timestamp modified.

Metode ini tidak memicu validasi controller dan harus digunakan dengan sangat hati-hati.

# memperbarui nilai di database, memperbarui timestamp modified
doc.db_set('price', 2300)

# memperbarui nilai di database, akan memicu doc.notify_update()
doc.db_set('price', 2300, notify=True)

# memperbarui nilai di database, akan juga menjalankan frappe.db.commit()
doc.db_set('price', 2300, commit=True)

# memperbarui nilai di database, tidak memperbarui timestamp modified
doc.db_set('price', 2300, update_modified=False)

doc.append

Menambahkan item baru ke child table.

doc.append("childtable", {
    "child_table_field": "value",
    "child_table_int_field": 0,
    ...
})

doc.get_url

Mengembalikan URL Desk untuk dokumen ini. Misalnya: /app/task/TASK00002

url = doc.get_url()

doc.add_comment

Menambahkan komentar ke dokumen ini. Akan muncul di timeline dalam tampilan Form.

# tambahkan komentar sederhana
doc.add_comment('Comment', text='Test Comment')

# tambahkan komentar bertipe Edit
doc.add_comment('Edit', 'Nilai berubah')

# tambahkan komentar bertipe Shared
doc.add_comment("Shared", "{0} membagikan dokumen ini dengan semua orang".format(user))

doc.add_seen

Tambahkan pengguna yang diberikan/saat ini ke daftar pengguna yang telah melihat dokumen ini. Akan memperbarui kolom _seen dalam tabel. Ini disimpan sebagai JSON Array.

# tambahkan john ke daftar yang telah melihat
doc.add_seen('john@doe.com')

# tambahkan pengguna session ke daftar yang telah melihat
doc.add_seen()

Ini hanya berfungsi jika Track Seen diaktifkan di DocType.

doc.add_viewed

Tambahkan log view saat pengguna melihat dokumen, misalnya membuka Form.

# tambahkan log view oleh john
doc.add_viewed('john@doe.com')

# tambahkan log view oleh pengguna session
doc.add_viewed()

Ini hanya berfungsi jika Track Views diaktifkan di DocType.

doc.add_tag

Tambahkan tag ke dokumen. Tag biasanya digunakan untuk memfilter dan mengelompokkan dokumen.

# tambahkan tag
doc.add_tag('developer')
doc.add_tag('frontend')

doc.get_tags

Mengembalikan daftar tag yang terkait dengan dokumen tertentu.

# dapatkan semua tag
doc.get_tags()

doc.run_method

Menjalankan metode jika didefinisikan dalam controller, juga akan memicu hooks jika didefinisikan.

doc.run_method('validate')

doc.queue_action

Menjalankan metode controller di latar belakang. Jika metode tersebut memiliki fungsi internal, seperti _submit untuk submit, metode itu akan dipanggil sebagai gantinya.

doc.queue_action('send_emails', emails=email_list, message='Howdy')

doc.get_children()

Hanya tersedia di DocType tree (diturunkan dari NestedSet).

Mengembalikan generator yang menghasilkan instance NestedSet untuk setiap catatan anak.

for child_doc in doc.get_children():
    print(child_doc.name)

Ini juga dapat diterapkan secara rekursif:

for child_doc in doc.get_children():
    print(child_doc.name)
    for grandchild_doc in child_doc.get_children():
        print(grandchild_doc.name)

doc.get_parent()

Hanya tersedia di DocType tree (diturunkan dari NestedSet).

Mengembalikan instance NestedSet untuk catatan induk.

parent_doc = doc.get_parent()
grandparent_doc = parent_doc.get_parent()

doc.db_insert()

Menserialize dan memasukkan dokumen ke dalam database. Peringatan: Ini melewati semua validasi dan metode controller yang mungkin diperlukan untuk dijalankan sebelum dan sesudah insert. Jika ragu, gunakan doc.insert() sebagai gantinya.

doc = frappe.get_doc(doctype="Controller", data="")
doc.db_insert()

doc.db_update()

Menserialize dan memperbarui dokumen ke dalam database. Peringatan: Ini melewati semua validasi dan metode controller yang mungkin diperlukan untuk dijalankan sebelum dan sesudah memperbarui. Jika ragu, gunakan doc.save() sebagai gantinya.

doc = frappe.get_last_doc("User")
doc.last_active = now()
doc.db_update()