A small Frappe list view plugin that allows customization.
- Frappe >= v12.0.0
Do not forget to replace [sitename] with the name of your site in all commands.
- Go to bench directory
cd ~/frappe-bench
- Get plugin from Github
bench get-app https://github.com/kid1194/frappe-better-list-view
- Build plugin
bench build --app frappe_better_list_view
- Install plugin on a specific site
bench --site [sitename] install-app frappe_better_list_view
- (Optional) Restart bench to clear cache
bench restart
- Go to app directory
cd ~/frappe-bench/apps/frappe_better_list_view
- Get updates from Github
git pull
- Go to bench directory
cd ~/frappe-bench
- Build plugin
bench build --app frappe_better_list_view
- Update a specific site
bench --site [sitename] migrate
- (Optional) Restart bench to clear cache
bench restart
- Go to bench directory
cd ~/frappe-bench
- Uninstall plugin from a specific site
bench --site [sitename] uninstall-app frappe_better_list_view
- Remove plugin from bench
bench remove-app frappe_better_list_view
- (Optional) Restart bench to clear cache
bench restart
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'
}
List of additional fields to fetch but not display.
Example:
['is_approved', 'is_paid']
List of additional filters for the fetch query.
Example:
- Object:
{is_approved: 1, is_paid: 0}
- Array:
[
['is_approved', '=', 1],
['is_paid', '=', 0]
]
Number of rows to display per page.
- Default:
20
- Minimum:
20
Example:
50
Function to modify the list data before display.
Arguments:
Name | Type | Description |
---|---|---|
data |
Array | Data list before display. |
render |
Function | |
error |
Function |
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();
});
}
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)';
}
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');
}
}
};
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 += ' <span class="fa fa-check"></span>';
}
return html;
},
},
};
If you find a bug, please create a bug report and let us know about it.
This plugin has been released under the MIT License.