Document Resource ​

createDocumentResource fetches one document from a Frappe backend and gives you methods to update, save and delete it, and to run its controller methods. It is the older data-fetching API and stays supported through 1.x.

For new code, use useDoc.

Composition API ​

Set doctype and name. The document is fetched when the resource is created and is available on todo.doc.

vue
<template>
  <div v-if="todo.doc">
    {{ todo.doc.description }}
    <Badge :label="todo.doc.status" />
    <Button @click="todo.setValue.submit({ status: 'Closed' })">
      Mark as closed
    </Button>
    <Button @click="todo.sendEmail.submit({ email: todo.doc.owner })">
      Send email
    </Button>
  </div>
</template>

<script setup>
import { createDocumentResource } from 'frappe-ui'

const todo = createDocumentResource({
  doctype: 'ToDo',
  name: 'TODO-0001',
  whitelistedMethods: {
    sendEmail: 'send_email',
  },
})
</script>

The resource sends dotted method names like frappe.client.get, so the app must use frappeRequest as its fetcher.

There is one resource for each doctype and name. A second createDocumentResource call for the same document returns the same object.

Options API ​

With app.use(FrappeUI, { resources: true }) in main.js (see Resource), declare the resource with type: 'document'. It is available on this.$resources.todo.

vue
<script>
export default {
  resources: {
    todo() {
      return {
        type: 'document',
        doctype: 'ToDo',
        name: this.todoName,
      }
    },
  },
}
</script>

API Reference ​

Options ​

OptionDefaultDescription
doctypeThe DocType of the document. Required.
nameThe name of the document. Required.
autotrueFetch the document when the resource is created.
whitelistedMethodsController methods to expose as resources, like { sendEmail: 'send_email' }. See Whitelisted methods.
debounce500Wait time in milliseconds for setValueDebounced.
realtimefalseFetch the document again when the server reports that it changed. Needs a socket on this.$socket, so it works only in the Options API.
onSuccess(doc)Runs after the document loads.
onError(error)Runs when loading the document fails.
transform(doc)Changes the document before it is set on doc.
setValueObject with onSuccess, onError and validate for setValue, setValueDebounced and save. Throw in validate to stop the request.
deleteObject with onSuccess and onError for delete.

Properties ​

PropertyDescription
docThe document, after transform. null until it loads.
originalDocA copy of the document as last loaded or saved.
isDirtytrue when doc differs from originalDoc.
getThe resource that fetches the document. Read get.loading, get.error and get.promise here.

Methods ​

MethodDescription
reload()Fetch the document again. Returns a promise.
setDoc(doc)Replace doc. Pass a function to compute it from the current document.

Write resources ​

Each of these is a resource with its own loading and error. Call submit() to run it.

Resourcesubmit() argumentDescription
setValue{ status: 'Closed' }Set field values. doc changes at once and goes back if the request fails.
setValueDebounced{ description: '…' }Same as setValue, sent once after debounce milliseconds without a new call.
savenoneSend the fields of doc that changed since it loaded. Sends no request when nothing changed.
deletenoneDelete the document and set doc to null.

Rows of the same document in a list resource update with setValue, save and delete.

Whitelisted methods ​

Each key in whitelistedMethods becomes a resource on the document resource. submit(args) runs the controller method with args, and data is the method's return value.

js
const todo = createDocumentResource({
  doctype: 'ToDo',
  name: 'TODO-0001',
  whitelistedMethods: {
    sendEmail: 'send_email',
    close: {
      method: 'close',
      onSuccess(result) {},
    },
  },
})

todo.sendEmail.submit({ email: '[email protected]' })
todo.close.loading

The value is the method name, or an object with method and any resource options. If the response includes this document after the method ran, doc updates with it.

List ResourceIcons