Developer's Guide to Customizing the Empress Tree View Feature

Developers
1

Introduction

The Tree View feature in Empress is a powerful tool that provides a hierarchical view of all DocTypes with the ‘Is Tree’ attribute enabled. This guide will guide developers through the process of customizing this feature, detailing how to modify and implement it in a manner that enhances software development and customization.

Understanding the Tree View Feature

The Tree View in Empress is generated for all DocTypes that have ‘Is Tree’ enabled, providing a user-friendly and intuitive interface to manage hierarchical data. Developers can customize the Tree View to suit different needs, offering a flexible and powerful tool for data management.

Customizing the Tree View

To customize the Tree View, you need to have a {doctype}_tree.js file in the doctype directory. This file allows developers to modify the various options available for customization. For instance, to configure the Account DocType, you would create a account_tree.js file.

The contents of this file should follow the template below:

frappe.treeview_settings['Account'] = {
    // Various customization options go here
}

Detailed Breakdown of Customization Options

The {doctype}_tree.js file is where you define all the customization options for the Tree View feature. Let’s explore these options in detail:

  • breadcrumb: The breadcrumb trail for your application. For instance, ‘Accounting’ in the case of Account DocType.

  • title: The title of your doctype. For instance, ‘Chart of Accounts’ in the case of Account DocType.

  • filters: An array of filter objects that can be used to filter the data displayed in the Tree View. Each filter object should have the following properties:

    • fieldname: The name of the field.
    • fieldtype: The type of the field.
    • options: The options available for the field.
    • label: The label of the field.
    • on_change: The function to call when the field value changes.

  • get_tree_nodes: The path to the whitelisted method that returns the child nodes.

  • add_tree_node: The path to the whitelisted method that handles the addition of a new node.

  • fields: An array of field objects to be displayed when creating a new node. Each field object should have the following properties:

    • fieldtype: The type of the field.
    • fieldname: The name of the field.
    • label: The label of the field.
    • options: The options available for the field (if applicable).
    • reqd: Whether the field is required or not (if applicable).

  • ignore_fields: An array of field names to be ignored even if they are mandatory.

  • menu_items: An array of menu item objects to be added under the 3-dot menu group. Each menu item object should have the following properties:

    • label: The label of the menu item.
    • action: The function to call when the menu item is clicked.
    • condition: The condition that determines whether the menu item should be displayed or not.

  • onload: A function that is triggered when the tree view is instantiated.

  • post_render: A function that is triggered when the tree is instantiated.

  • onrender: A function that is triggered when a node is instantiated.

  • on_get_node: A function that is triggered when get_tree_nodes returns nodes.

  • extend_toolbar: A boolean that determines whether to enable custom buttons beside each node.

  • toolbar: An array of toolbar button objects to be displayed beside each node. Each toolbar button object should have the following properties:

    • label: The label of the toolbar button.
    • condition: The condition that determines whether the toolbar button should be displayed or not.
    • click: The function to call when the toolbar button is clicked.
    • btnClass: The CSS class to be applied to the toolbar button.

Conclusion

The Tree View feature is a powerful tool for developers, allowing for extensive customization and control over the presentation and management of hierarchical data in Empress. With the understanding of the various customization options provided in this guide, developers can effectively tailor the Tree View feature to suit their specific needs and enhance the overall user experience.