--- applyTo: '**/*.vue' --- ### General Backend API Calls ```vue ``` ### Document Resource ```vue ``` Example API: ```vue todo.doc // doc returned from request todo.reload() // reload the doc // update options todo.update({ doctype: '', name: '' }) todo.get // doc resource todos.get.loading // true when data is being fetched todos.get.error // error that occurred from making the request todos.get.promise // promise object of the request, can be awaited // resource to set value(s) on the document todos.setValue todos.setValue.submit({ // field value pairs to set status: 'Closed', description: 'Updated description' }) // same as setValue but debounced todos.setValueDebounced // will run once after 500ms todos.setValueDebounced.submit({ description: 'Updated description' }) // resource to delete the document todos.delete todos.delete.submit() // if whitelistedMethods is defined // you get a resource for each whitelisted method todos.sendEmail todos.sendEmail.submit todos.sendEmail.loading ``` ### List Resource List Resource is a wrapper on top of [Resource](./Resource.story.md) for working with lists. This feature only works with a Frappe Framework backend as of now. ## Usage A list resource knows how to fetch records of a DocType from a Frappe Framework backend so there is no need to specify the url. Instead you only define `doctype`, `fields`, `filters`, etc. You also get methods like `next()`, `setValue()`, etc. ```vue ``` ## Options API You can also define resources if you are using Options API. You need to register the `resourcesPlugin` first. **main.js** ```js import { resourcesPlugin } from 'frappe-ui' app.use(resourcesPlugin) ``` In your .vue file, you can declare all your resources under the resources key as functions. The resource object will be available on `this.$resources.[name]`. In the following example, `this.$resources.todos` is the resource object. **Component.vue** ```vue ``` ## List of Options and API Here is the list of all options and APIs that are available on a list resource. ### Options ```js let todos = uesList({ // name of the doctype doctype: 'ToDo', // list of fields fields: ['name', 'description', 'status', ...], // object of filters to apply filters: { status: 'Open' }, // the order in which records must be sorted orderBy: 'creation desc', // index from which records should be fetched // default value is 0 start: 0, // number of records to fetch in a single request // default value is 20 pageLength: 20, // parent doctype when you are fetching records of a child doctype parent: null, // set to 1 to enable debugging of list query debug: 0, // cache key to cache the resource // can be a string cacheKey: 'todos', // or an array that can be serialized cacheKey: ['todos', 'faris@frappe.io'], // default value for url is "frappe.client.get_list" // specify url if you want to use a custom API method url: 'todo_app.api.get_todos', // make the first request automatically auto: true, // events // error can occur from failed request onError(error) { }, // on successful response onSuccess(data) { }, // transform data before setting it transform(data) { for (let d of data) { d.open = false } return data }, // other events fetchOne: { onSuccess() {}, onError() {} }, insert: { onSuccess() {}, onError() {} }, delete: { onSuccess() {}, onError() {} }, setValue: { onSuccess() {}, onError() {} }, runDocMethod: { onSuccess() {}, onError() {} }, }) ``` ### API A list resource is made up of multiple individual resources. In our running example, the resource object that fetches the list is at `todos.list`. So all the [properties of a resource](./Resource.story.md) are available on this object. Similarly, there are resources for `fetchOne`, `setValue`, `insert`, `delete`, and `runDocMethod`. ```js let todos = useList({...}) todos.data // data returned from request todos.originalData // response data before being transformed todos.reload() // reload the existing list todos.next() // fetch the next page todos.hasNextPage // whether there is next page to fetch // update list options todos.update({ fields: ['*'], filters: { status: 'Closed' } }) todos.data // list resource todos.loading // true when data is being fetched todos.error // error that occurred from making the request todos.promise // promise object of the request, can be awaited // resource to fetch and update a single record in the list todos.fetchOne // pass the name of the record to fetch that record and update the list todos.fetchOne.submit(name) // resource to set value(s) for a single record in the list todos.setValue todos.setValue.submit({ // id of the record name: '', // field value pairs to set status: 'Closed', description: 'Updated description' }) // resource to insert a new record in the list todos.insert todos.insert.submit({ description: 'New todo' }) // resource to delete a single record todos.delete todos.delete.submit(name) // resource to run a doc method todos.runDocMethod todos.runDocMethod.submit({ // name of the doc method method: 'send_email', // name of the record name: '', // params to pass to the method email: 'test@example.com' }) ``` ### List View Component ### Story ```vue ``` ## Props ### Row Key `row-key` is a unique key which is used to identify each row in the list. It is required to be passed in the `row` object. ### Column 1. `label` & `key` is required in column object. 2. `width` is optional and it is used to set column width in list 1. If you need a column to be `3` times a default column then add `3`. if width is not mentioned default will be `1` 2. You can also add custom width in px and rem e.g `300px` or `12rem` 3. Combination of both can also be used. 3. `align` is also optional. You can change the alignment of the content in the column by setting it as. 1. `start` or `left` (default) 2. `center` or `middle` 3. `end` or `right` 4. You can add more attributes which can be used to render custom column header items. ### Row 1. The row object must contain a unique_key which was mentioned in ListView `row-key` 2. Then you can add the row fields as key value pairs and each field can be an object or a string (to handle custom rendering) ``` { // unique_key 'id' id: 1, // row fields name: 'John Doe', age: 25, email: 'john@doe.com', } ``` E.g field value as an object (to handle custom rendering), but make sure it has a `label` attribute which holds the actual value to be shown ``` row: { name: { label: 'John Doe', image: '/johndoe.jpg', }, age: 25, status: { label: 'Active', color: 'green' } } ``` ### Grouped Rows To render grouped rows, you must provide `rows` in the following format: ``` [ { group: 'Group Title 1', collapsed: false, rows: [ {id: 1, key1: value1, key2: value2, ...}, {id: 2, key1: value1, key2: value2, ...}, ] }, { group: 'Group Title 2', collapsed: false, rows: [ {id: 3, key1: value1, key2: value2, ...}, {id: 4, key1: value1, key2: value2, ...}, ] }, ] ``` ### Options 1. If you want to route using router-link just add a `getRowRoute` function which returns a route object `getRowRoute: (row) => ({ name: 'User', params: { userId: row.id } })` 2. if you need to do some action add a `onRowClick` event handler `onRowClick: (row) => console.log(row.label + ' was clicked')` 3. selectable (Boolean) - if true, checkbox will be shown in header and rows, to select/multiselect rows and perform some action on them - default is true 4. showTooltip (Boolean) - if true, tooltip will be shown on hover of row - default is true 5. resizeColumn (Boolean) - if true, column can be resized by dragging the resizer on the right side of the column header - default is false --- ### Selection Banner (Will be shown when selectable (default is true) is true) **Without custom action buttons:**

**With custom action buttons:**

``` ``` You can also make your own custom selection banner

```

Custom Banner

``` ### Badge Component #### Story ```vue ``` ### FormControl Component #### Story ```vue ``` ### Toasts Example: ```vue ``` ### Dropdown Component The icon is name of a lucide icon. #### Story ```vue ``` ### Dialog Component #### Story ```vue ```

Custom Title with Styling

Settings Dialog