Introduction
Virtual DocFields are powerful features in Empress that allow developers to handle dynamic attributes of a given Document (or Record) in a more efficient and effective manner. They are not stored in the site database but are calculated attributes, which can be useful for representing values that are functions of other static Document attributes.
Understanding Virtual DocFields
Let’s consider a Person’s name, which is most often divided into First, Middle, and Last Name. However, for viewing purposes, it would be practical to have all of them together like “Jon Raphael Doe”. Storing the full name as a separate attribute may not be necessary when the strings can be easily concatenated. This is where Virtual DocFields come into play.
In Empress, you can define three fields for a Person; two for First and Last names, which are stored in the site database, and one that utilizes this data to populate the third field “Full Name”. The “Full Name” field is a Virtual DocField that does not create a corresponding column in the DocType’s table, making the field “Read Only” in the Form Views.
Implementing Virtual DocFields
To use a Virtual DocField, you will need to:
1. Define a Virtual DocField
This is accomplished by checking the “Virtual” checkbox under the DocField’s configuration.
2. Define a Source for the Field
After creating a placeholder for the values, you need to add some code that dictates what the field should show. You can do this in two ways:
- By extending the DocType controllers: Add a Python property with the same name as the virtual field. This is the most flexible way to do this; you could daisy chain an internal API request, or fetch the data from multiple data sources.
class Person(Document):
@property
def age(self):
return frappe.utils.now_datetime() - self.creation
- Using the
DocField.options: This is a bit more restrictive given it allows you to write code directly from Desk. Utils allowed in Server Scripts and Document attributes can be accessed through this.
frappe.utils.now_datetime() - self.creation
Impact on Empress Internals
It’s important to note that Virtual DocFields will not return virtual values since they don’t live in the Site Database. They have no footprint in the respective DocType’s table. You may find corresponding records to give some evidence of their existence in the Custom Field, DocField tables that store DocType’s Meta.
The /api/method/frappe.desk.form.load.getdoc and /api/resource APIs utilize Document.get_valid_dict which will compute Virtual values too. These APIs are used to render the Desk Form views as well.
Conclusion
Virtual DocFields can drastically enhance the efficiency and functionality of your Empress solution. By understanding the implementation and usage of this feature, developers can leverage it to create more dynamic and effective software solutions. Through the careful manipulation of backend APIs, DocType attributes, and other system elements, a Virtual DocField can significantly enhance the customization of business solutions in Empress.