Skip to content

defaultvalue.md

Latest commit

 

History

History
74 lines (56 loc) · 5.57 KB

defaultvalue.md

File metadata and controls

74 lines (56 loc) · 5.57 KB

Frappe Core Doctype: DefaultValue

The DefaultValue Doctype in Frappe is a child table (istable: 1) designed to store key-value pairs that represent default settings or preferences. It is primarily used as a child table within the "User" and "Role" Doctypes, and can also be managed via the "User Properties" page.

Core Purpose

  • To allow the definition of default values for various system parameters or field values on a per-user or per-role basis.
  • To provide a flexible mechanism for users to personalize their experience or for administrators to set common defaults for groups of users (via Roles).
  • To enable other Doctypes or system logic to fetch these defaults at runtime to pre-fill fields or control behavior.

Key Files Defining DefaultValue

  • defaultvalue.json: Defines the schema (fields, properties) of this child Doctype.
  • defaultvalue.py: Contains the basic server-side Python controller class and index creation logic.
  • README.md: Provides a brief overview of its purpose and usage context.

This Doctype does not have a dedicated client-side JavaScript (.js) file, as its interaction is typically managed by the parent Doctype's UI or specific settings pages like "User Properties".

defaultvalue.json - Schema Definition

This JSON file specifies the structure for each row in the "DefaultValue" child table.

  • istable: 1: This flag explicitly marks it as a child Doctype.
  • autoname: "hash": Each default value entry is assigned a unique hash ID.
  • Key Fields:
    • defkey (Data, Required, In List View):
      • This field stores the "Key" or identifier for the default setting.
      • This key often corresponds to a fieldname in another Doctype (e.g., "language", "country", "naming_series") or a specific system setting identifier.
    • defvalue (Text, In List View):
      • This field stores the actual "Value" to be used as the default for the corresponding defkey.
      • The fieldtype is "Text", allowing it to store various types of default data (strings, numbers, simple JSON strings, etc.). The interpretation of this value is handled by the logic that consumes these defaults.
  • Permissions:
    • The permissions array is empty ([]). As a child table, its editability and visibility are controlled by the permissions set on its parent Doctype (e.g., "User" or "Role").
  • Module: "Core"

defaultvalue.py - Server-Side Logic

The Python controller for this Doctype is minimal, focusing on database optimization.

  • DefaultValue(Document) Class:
    • This is the standard class definition inheriting from frappe.model.document.Document.
    • The pass statement indicates that no custom server-side methods (like validate, on_update specific to the default value row itself) are implemented in this controller.
    • The logic for applying these default values when new documents are created or when settings are fetched is handled by Frappe's core frappe.defaults module and by the controllers of Doctypes that utilize these defaults.
  • on_doctype_update() (Global Function):
    • This function is executed during bench migrate.
    • It ensures that database indexes are created on the tabDefaultValue table:
      • An index on (parent, defkey): This is crucial for performance when the system needs to quickly fetch a specific default value (identified by defkey) for a particular parent document (e.g., the default "Company" for User "john.doe@example.com").
      • An index on (parent, parenttype): A more general index for querying child table records.

README.md Overview

The README succinctly states: "Child table for User and Role where default keys and values are stored. They can also be created from the User Properties page."

How It's Used

The "DefaultValue" Doctype allows for setting defaults in various contexts:

  1. User Defaults (via "User" Doctype or "User Properties" page):
    • A user (or an administrator editing a user's record) can set personal defaults.
    • Example: User "jane.doe@example.com" might set:
      • defkey: "country", defvalue: "Germany"
      • defkey: "language", defvalue: "de"
    • When Jane creates a new "Address" document, the "Country" field might automatically be pre-filled with "Germany" if the Address Doctype is configured to fetch this default.
  2. Role Defaults (via "Role" Doctype):
    • An administrator can set defaults that apply to all users having a particular role.
    • Example: For the "Sales User" role:
      • defkey: "naming_series" (for Sales Order), defvalue: "SO-"
    • When a "Sales User" creates a new "Sales Order", the "Naming Series" might default to "SO-".
  3. System-Wide Defaults (Historically, some might have been set via "System Settings" or similar parent Doctypes using DefaultValue):
    • While many system-wide defaults are now managed in dedicated "Settings" Doctypes, the DefaultValue mechanism provides a flexible fallback.
  4. Fetching Defaults:
    • Frappe provides utility functions like frappe.defaults.get_user_default(key), frappe.defaults.get_global_default(key), and frappe.defaults.get_defaults() which query the tabDefaultValue table (among other places like "System Settings") to retrieve these values. The system typically checks for user-specific defaults first, then role-based defaults, then global defaults.

The DefaultValue Doctype is a key component in making Frappe adaptable and user-friendly by allowing pre-configuration of common values, reducing repetitive data entry.