Implementing and Utilizing the Link Formatter Feature in Empress

Developers
1

Introduction

In software development, efficiency and user-friendliness are key. The Link Formatter feature in Empress encapsulates both of these qualities. It enables developers to present pertinent data in a concise and intuitive format. This feature is especially useful when handling entities that are identified by both an ID and a descriptive name, such as an employee entity with an Employee Code and Employee Name.

Understanding the Link Formatter Feature

The Link Formatter feature is a utility that allows you to display both the ID and name of an entity in a single link field. This feature is based on creating a custom formatter function that concatenates the entity’s ID and name, separated by a colon.

This feature provides a seamless way to visualize and interact with complex data structures. It enhances the user experience, improves data readability, and optimizes data representation.

Implementing the Link Formatter Feature

To implement the Link Formatter feature, you need to define a formatter function for the specific entity you want to format.

Here is an example for the ‘Employee’ entity:

frappe.form.link_formatters['Employee'] = function(value, doc) {
    if(doc.employee_name && doc.employee_name !== value) {
        return value + ': ' + doc.employee_name;
    } else {
        return value;
    }
}

In this code snippet, frappe.form.link_formatters['Employee'] defines the formatter function for the ‘Employee’ entity. The function takes two arguments: value, which is the entity’s ID, and doc, which is the document containing the entity’s data.

Inside the function, an if statement checks if the employee_name field exists and if its value differs from the entity’s ID. If both conditions are met, the function returns the ID and name concatenated with a colon. If not, it returns the ID only.

Important Considerations

  1. Both the primary key (name) and the descriptive name (e.g. employee_name) must be present in the document. The descriptive name field could be hidden.

  2. This code needs to be loaded before the document is loaded and can be re-used for all forms. You can also add it in build.json.

Debugging and Modification

The Link Formatter feature is highly flexible, and you can easily modify the formatter function to suit your specific needs. Debugging involves checking the entity’s ID and name and ensuring that they are correctly retrieved and displayed. You can also add more sophisticated logic in the formatter function to handle complex scenarios.

Security and Permissions

The Link Formatter feature respects the user roles and permissions defined in your Empress system. It only retrieves and displays data that the user is authorized to access, ensuring the system’s security and data integrity.

Conclusion

The Link Formatter feature is a powerful tool in the Empress suite that provides a user-friendly way to display entity data. By using this feature, developers can enhance the user experience, streamline data representation, and create efficient and intuitive software solutions.