How to Set Dynamic Field Visibility in Frappe DocTypes
Field Visibility EvaluationLearn to control field visibility in Frappe DocTypes using `eval:` conditions. This guide covers common scenarios like checking field values, comparing numbers, and using `in_list`.
In the Frappe Framework, creating dynamic and user-friendly forms is crucial for a good user experience. One of the most powerful declarative features is the ability to conditionally show or hide fields based on the state of other data in the form. This is achieved using JavaScript-like expressions in the 'Visible On' property of a DocType field.
This snippet collection showcases various conditions you can use to control field visibility without writing a single line of a Client Script. These expressions are evaluated in real-time by the Frappe framework, making your forms responsive and intuitive.
1 // Show a field only if 'myfield' is not blank (has any value) 2 eval:doc.myfield 3
4 // Show a field only if 'myfield' has a specific value 5 eval:doc.myfield=='My Value' 6
7 // Show a field based on a numerical comparison 8 eval:doc.age > 18 9
10 // Show a field if either of two Checkbox fields are ticked 11 eval:doc.if_crm=='Yes' || doc.if_erp=='Yes' 12
13 // Show a field if a Select field's value is one of several options 14 eval:in_list(["Option A", "Option B"], doc.field2) 15
16 eval:in_list(["Receive", "Pay"], doc.payment_type) && doc.party_type 17
18 // A more complex real-world example from Purchase Order DocType 19 // Shows a button to get items from Material Requests under specific conditions 20 eval:doc.supplier && doc.docstatus===0 && (!(doc.items && doc.items.length) || (doc.items.length==1 && !doc.items[0].item_code)) 21
22 // Another example using in_list for sales segmentation 23 eval:in_list(["IT Outsourcing- Full-time or Part-time", "IT Outsourcing-Enterprise Package"], doc.quotation_segment)
Understanding This Code
What It Does
These snippets provide a set of logical expressions to dynamically control the visibility of a field within a Frappe DocType form. The conditions are evaluated against the current document's data to decide whether a field should be shown or hidden.
When To Use
Use these expressions in the 'Visible On' property of any field within a DocType definition. This is the preferred method for simple, declarative visibility rules that don't require complex logic, avoiding the need for a custom Client Script.
Prerequisites
- •Administrator or System Manager role with access to DocType customization.
- •A basic understanding of the fields and data types within your target DocType.
Key Concepts
Important ideas to understand in this code
The 'doc' Object
In Frappe forms, `doc` is a client-side JavaScript object that holds all the data for the current record being viewed or edited. You can access any field's value using dot notation, like `doc.field_name`.
Learn more'eval:' Prefix
The `eval:` prefix instructs the Frappe framework to evaluate the following string as a JavaScript expression. This allows you to write dynamic conditions directly in the DocType field properties.
Learn morein_list() Function
`in_list()` is a built-in Frappe utility function available in these expressions. It checks if a given value exists within an array. The syntax is `in_list(array_of_values, value_to_check)`.
Learn moreDocType Field Properties
'Visible On' is a property found in the 'Display' section of a field's configuration within a DocType. This is where you insert the `eval:` expressions to control its visibility.
Learn moreStep-by-Step Tutorial
Follow along to understand how this code works
Navigate to the DocType List
From the Awesome Bar, search for 'DocType List' and open it. Find the DocType you wish to modify, for example, 'Sales Order'.
Select the Field to Modify
In the DocType's field list, find the field you want to make conditionally visible. For instance, a custom field named 'delivery_instructions'. Click to expand its properties.
Locate the 'Visible On' Property
Scroll down to the 'Display' section within the field's settings. You will find a textbox labeled 'Visible On'.
Enter the Visibility Condition
Enter your condition, prefixed with `eval:`. Let's say we only want to show 'delivery_instructions' if the 'order_type' is 'Sales'.
eval:doc.order_type=='Sales'Save and Test
Click the 'Save' button at the top right of the DocType page. Now, open or create a new Sales Order record. The 'delivery_instructions' field will only appear when you set the 'Order Type' to 'Sales'.
Common Issues & Solutions
Troubleshoot problems you might encounter