Frappe Better List View

bench get-app https://github.com/kid1194/frappe-better-list-view

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=kid1194%2Ffrappe-better-list-view)](https://frappegems.com/gems/apps/kid1194/frappe-better-list-view)

# Frappe Better List View A small **Frappe** list view plugin that allows customization.  --- ### Table of Contents - [Requirements](#requirements) - [Setup](#setup) - [Install](#install) - [Update](#update) - [Uninstall](#uninstall) - [Usage](#usage) - [Options](#options) - [Methods](#methods) - [Example](#example) - [Issues](#issues) - [License](#license) --- ### Requirements - Frappe >= v12.0.0 --- ### Setup ⚠️ *Important* ⚠️ *Do not forget to replace [sitename] with the name of your site in all commands.* #### Install 1. Go to bench directory ``` cd ~/frappe-bench ``` 2. Get plugin from Github ``` bench get-app https://github.com/kid1194/frappe-better-list-view ``` 3. Build plugin ``` bench build --app frappe_better_list_view ``` 4. Install plugin on a specific site ``` bench --site [sitename] install-app frappe_better_list_view ``` 5. (Optional) Restart bench to clear cache ``` bench restart ``` #### Update 1. Go to app directory ``` cd ~/frappe-bench/apps/frappe_better_list_view ``` 2. Get updates from Github ``` git pull ``` 3. Go to bench directory ``` cd ~/frappe-bench ``` 4. Build plugin ``` bench build --app frappe_better_list_view ``` 5. Update a specific site ``` bench --site [sitename] migrate ``` 6. (Optional) Restart bench to clear cache ``` bench restart ``` #### Uninstall 1. Go to bench directory ``` cd ~/frappe-bench ``` 2. Uninstall plugin from a specific site ``` bench --site [sitename] uninstall-app frappe_better_list_view ``` 3. Remove plugin from bench ``` bench remove-app frappe_better_list_view ``` 4. (Optional) Restart bench to clear cache ``` bench restart ``` --- ### Usage #### Options ##### 1. `status` 🔴 Status object to enable or disable ListView. **Keys:** | Key | Type | Description | | :--- | :--- | :--- | | `enable` | Boolean | Enabled or disabled status.

Default: `true` | | `message` | String | Disabled message.

Default: `ListView is disabled.` | | `color` | String | Message text color.

Colors: `green`, `blue`, `orange`, `gray`, `red`

Default: `red` | **Example:** ``` { enable: false, message: __('ListView is disabled.'), color: 'red' } ``` ##### 2. `query_fields` List of additional fields to fetch but not display. **Example:** ``` ['is_approved', 'is_paid'] ``` ##### 3. `query_filters` List of additional filters for the fetch query. **Example:** - Object: ``` {is_approved: 1, is_paid: 0} ``` - Array: ``` [ ['is_approved', '=', 1], ['is_paid', '=', 0] ] ``` ##### 4. `page_length` Number of rows to display per page. - Default: `20` - Minimum: `20` **Example:** ``` 50 ``` ##### 5. `parser` Function to modify the list data before display. **Arguments:** | Name | Type | Description | | :--- | :--- | :--- | | `data` | Array | Data list before display. | | `render` | Function | ⚠️ Must be called after data parsing is done to render ListView. | | `error` | Function | ⚠️ Must be called when an error is raised to ignore all data modification. | ⚠️ *Important* ⚠️ If an error isn't caught inside the parser function, all data modification will be ignored and original data will be rendered automatically instead. **Examples:** ``` function(data, render, error) { let names = []; data.forEach(function(row) { names.push(row.name); }); frappe.db.get_list('Doctype', { fields: ['name', 'value'], filters: { name: ['in', names], } }).then(function(list) { list.forEach(function(vals) { data.forEach(function(row) { if (vals.name === row.name) { row.value = vals.value; } }); }); // Render modified data render(); }).catch(function(e) { console.error(e.message, e.stack); // Render original data instead error(); }); } ``` ##### 6. `set_row_background` Function to set the row background color. **Arguments:** | Name | Type | Description | | :--- | :--- | :--- | | `row` | Plain Object | ListView row data object. | **Return:** | Type | Description | | :--- | :--- | | `String` | Row background color.

Color Type: `CSS Key`, `Hex`, `RGB`, `RGBA` or `HSLA`. | | `Null` | No row background color. | **CSS Colors & Keys:**

**Examples:** ``` function(row) { let cost = cint(row.cost); if (cost > 1000) return 'danger'; if (cost > 800) return '#ffeeba'; if (cost > 600) return 'rgb(190,229,235)'; if (cost > 400) return 'rgba(190,229,235,1)'; if (cost < 200) return 'hsla(133.7,41.2%,83.3%,1)'; } ``` #### Methods ##### 1. `toggle_status` Method to enable or disable ListView on demand. It can be called from within `onload` event. **Parameters:** | Name | Type | Description | | :--- | :--- | :--- | | `enable` | Boolean | Enabled or disabled status.

Default: `true` | | `message` | String | Disabled message.

Default: `ListView is disabled.` | | `color` | String | Message text color.

Colors: `green`, `blue`, `orange`, `gray`, `red`

Default: `red` | **Example:** ``` frappe.listview_settings['DocType'] = { onload: function(listview) { if (!frappe.user_roles.includes('Some Role')) { listview.toggle_status(false, __('ListView is disabled.'), 'red'); } } }; ``` #### Example ``` frappe.listview_settings['DocType'] = { /* *--------------------------------------------------- *---------- 🔴 Plugin Custom Options 🔴 ------------ *--------------------------------------------------- */ /* * 1. ListView status */ status: { enable: false, message: __('ListView is disabled.'), color: 'red' }, /* * 2. Fields to fetch but not display */ query_fields: ['is_approved', 'is_paid'], /* * 3. Additional filters (array or object) for fetch query */ query_filters: { is_approved: 1, is_paid: 1, }, /* * 4. Only 50 rows will be displayed per page */ page_length: 50, /* * 5. List data modify function */ parser: function(data, render, error) { let names = []; data.forEach(function(row) { names.push(row.name); }); if (!names.length) { return render(); } frappe.db.get_list('Doctype', { fields: ['name', 'price'], filters: { name: ['in', names], is_approved: 1, } }).then(function(list) { list.forEach(function(vals) { data.forEach(function(row) { if (vals.name === row.name) { row.price = vals.price; } }); }); // Render modified data render(); }).catch(function(e) { console.error(e.message, e.stack); // Render original data instead error(); }); }, /* * 6. Custom row background color */ set_row_background: function(row) { if (!cint(row.is_approved)) return 'info'; }, /* *--------------------------------------------------- *-------- 🔵 ListView Options & Events 🔵 ---------- *--------------------------------------------------- */ /* * 1. Onload event * * ListView status can be toggled and changed using * the method "toggle_status" added by the plugin. */ onload: function(listview) { if (!frappe.user_roles.includes('Some Role')) { listview.toggle_status(false, __('ListView is disabled.'), 'red'); } }, /* * 2. Custom indicator method * * Additional fields listed in the "query_fields" option above * are added to the "doc" object and can be accessed directly. */ get_indicator: function(doc) { if (doc.is_paid) { return [__('Paid'), 'blue', 'is_paid,=,Yes|is_approved,=,Yes']; } if (doc.is_approved) { return [__('Approved'), 'green', 'is_paid,=,No|is_approved,=,Yes']; } return [__('Pending'), 'gray', 'is_paid,=,No|is_approved,=,No']; }, /* * 2. Column data formatters * * Additional fields listed in the "query_fields" option above * are added to the "doc" object and can be accessed directly. */ formatters: { name: function(value, field, doc) { let html = value; if (doc.is_approved) { html += ' '; } return html; }, }, }; ``` --- ### Issues If you find a bug, please create a [bug report](https://github.com/kid1194/frappe-better-list-view/issues/new?assignees=kid1194&labels=bug&template=bug_report.md&title=%5BBUG%5D) and let us know about it. --- ### License This plugin has been released under the [MIT License](https://github.com/kid1194/frappe-better-list-view/blob/main/LICENSE).