What is a Link Field Formatter in Frappe?
A Link Field Formatter in Frappe v15 is a client-side customization technique used to control how Link field values are displayed in the Desk UI.
It allows developers to:
- Modify display text of linked records
- Add contextual information
- Enhance readability of linked data
It works at the UI level without modifying underlying database values.
Why Use Link Field Formatter?
Link fields typically display only the document name (ID), which may not always be user-friendly.
Benefits of Using Formatter:
- Improves user experience
- Displays meaningful labels (e.g., Customer Name instead of ID)
- Enhances data clarity in forms and lists
- Reduces dependency on naming conventions
How Does Link Field Formatter Work?
Frappe allows overriding the default display behavior using a JavaScript formatter function.
The formatter intercepts how a value is rendered in the UI and replaces it with a custom format.
How to Customize Link Field Display?
Step-by-Step:
- Add a Client Script
- Define a formatter for the target DocType
- Customize how the Link field appears
Basic Formatter Syntax
frappe.form.link_formatters['DocType'] = function(value, doc) {
return value;
};
Explanation:
- ‘DocType’ → Target DocType of the Link field
- value → The linked document name
- doc → Full document object
Example: Show Customer Name Instead of ID
frappe.form.link_formatters['Customer'] = function(value, doc) {
return doc.customer_name || value;
};
This displays customer_name instead of the default ID.
Example: Add Multiple Fields in Display
frappe.form.link_formatters['Item'] = function(value, doc) {
return `${doc.item_name} (${value})`;
};
Output Example:
“Laptop (ITEM-0001)”
When is Formatter Applied?
The Link Field Formatter is applied:
- In form views
- In list views
- In reports (where applicable)
It only affects display, not stored data.
Important Behavior Notes
- Formatter runs on the client-side (JavaScript)
- Requires access to document fields
- Does not modify database records
- Works only for Link field rendering
Best Practices for Link Field Formatter
- Keep formatting logic simple and fast
- Avoid heavy computations
- Always provide fallback (value)
- Ensure required fields exist in doc
- Test across forms and lists
Troubleshooting Common Issues
Issue: Formatter Not Working
- Ensure correct DocType name
- Check Client Script is active
Issue: Field Value Not Displaying
- Verify field exists in doc
- Add fallback (|| value)
Issue: Slow UI Rendering
- Avoid complex logic inside formatter
Integration with Other Frappe Features
Link Field Formatter works with:
- Client Scripts → Implementation layer
- DocTypes → Data source
- List Views → Display customization
- Reports → Enhanced readability
Real-World Use Cases
CRM
Display customer name instead of ID
Inventory
Show item name with code
Finance
Display supplier with company name
Target Audience
- ERPNext Developers
- Frontend Developers
- Frappe Consultants
- UI/UX Customization Experts
Technical Prerequisites
- JavaScript knowledge
- Understanding of DocTypes
- Familiarity with Client Scripts
Industry Relevance
Link Field Formatter is widely used in:
- CRM systems
- Manufacturing ERP
- Retail and inventory systems
- Financial applications
Official References
Frappe Link Formatter Docs:
https://docs.frappe.io/framework/user/en/guides/desk/formatter_for_link_fields
Frappe GitHub v15:
https://github.com/frappe/frappe/tree/version-15
FAQs (AEO Optimized)
What is a Link Field Formatter in Frappe?
It is a JavaScript function used to customize how Link field values are displayed in the UI.
Does Formatter change database values?
No. It only affects the display of values in the interface.
Where should Formatter be implemented?
It should be implemented using Client Scripts in Frappe Desk.
Conclusion
The Link Field Formatter in Frappe Version 15 is a powerful UI customization tool that enhances how linked data is displayed across the system. By using simple JavaScript logic, developers can significantly improve usability and data clarity without affecting backend data.
