Skip to content

doctype_link.md

Latest commit

 

History

History
74 lines (59 loc) · 5.9 KB

doctype_link.md

File metadata and controls

74 lines (59 loc) · 5.9 KB

Frappe Core Doctype: DocType Link

The DocType Link Doctype in Frappe is a child table (istable: 1) used within the definition of a parent "DocType". Its purpose is to define and configure the links that appear in a document's dashboard, often under a "Connections" or similarly named section. These links provide quick navigation to related documents or lists.

Core Purpose

  • To establish and configure navigational links from a document of one Doctype to related documents or lists of another Doctype.
  • To populate the "Connections" section in a document's dashboard, making it easier for users to see and access related information.
  • To allow grouping of these links for better organization in the UI.

Key Files Defining DocType Link

  • doctype_link.json: Defines the schema (fields, properties) of this child Doctype.
  • doctype_link.py: Contains the basic server-side Python controller class.

This Doctype does not have its own dedicated client-side JavaScript (.js) file because the rendering of these links in the dashboard is handled by Frappe's generic dashboard and form view rendering engine.

doctype_link.json - Schema Definition

This JSON file specifies the structure for each row in the "Links" child table of a parent "DocType" document.

  • istable: 1: This flag explicitly marks it as a child Doctype.
  • Key Fields:
    • link_doctype (Link to DocType, Required, In List View):
      • The target Doctype to which this link will navigate (e.g., "Sales Order", "Customer", "Report", "ToDo").
    • link_fieldname (Data, Required, In List View):
      • The fieldname in the link_doctype that establishes the relationship with the parent Doctype (the Doctype where this "DocType Link" is defined).
      • For example, if the parent Doctype is "Customer" and link_doctype is "Sales Order", link_fieldname would typically be "customer" (assuming "customer" is the field in "Sales Order" that links to the "Customer" Doctype). This field is used to filter the list of linked documents to show only those related to the current parent document.
    • group (Data, In List View):
      • A label used to group related links together in the document's dashboard. For instance, links might be grouped under "Transactions", "Activities", "Setup", or "Customization".
    • hidden (Check, Default: 0):
      • If checked, this link will not be displayed in the dashboard.
    • custom (Check, Default: 0, Hidden):
      • A system flag indicating if this link was added via customization (e.g., "Customize Form") rather than being part of the standard Doctype definition.
    • is_child_table (Check, Read Only, Fetch From link_doctype.istable):
      • This field is automatically set to true if the link_doctype is itself a child table. It's read-only and its value is fetched from the istable property of the selected link_doctype.
    • parent_doctype (Link to DocType, Depends on is_child_table, Mandatory if is_child_table):
      • If is_child_table is true, this field must specify the parent Doctype of the link_doctype. This is used for creating "internal links" where the link points to a child table that is part of another Doctype.
    • table_fieldname (Data):
      • If is_child_table is true, this field specifies the fieldname of the table field (within the parent_doctype) that holds the records of the link_doctype.
  • Permissions:
    • The permissions array is empty ([]). As a child table, the ability to add, edit, or remove these links is governed by the permissions to modify the parent "DocType" document.
  • track_changes: 1: Changes to these link definitions are versioned.
  • Module: "Core"

doctype_link.py - Server-Side Logic

The Python controller for this Doctype is minimal.

  • DocTypeLink(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 link definition itself) are implemented in this controller.
    • The logic for how these links are fetched, filtered, and displayed in the parent document's dashboard is handled by Frappe's core dashboard rendering utilities.

How It's Used

  1. When defining or customizing a "DocType" (e.g., "Project"):
    • In the "Links" section (which is a table field linked to "DocType Link"), an administrator or developer can add rows.
    • For each row (link definition):
      • Example 1 (Link to related standard Doctype):
        • link_doctype: "Task"
        • link_fieldname: "project" (assuming "Task" has a field named "project" linking to "Project")
        • group: "Activities"
      • Example 2 (Link to a Report filtered by the current document):
        • link_doctype: "Report"
        • link_fieldname: "ref_doctype" (if the report is generic and uses ref_doctype for filtering)
        • group: "Reports"
        • (Additional configuration for which specific report and how to pass the current project name as a filter would typically be handled by how the dashboard interprets these links, or might involve specific conventions for report links).
  2. When a user opens a "Project" document (e.g., "PROJ-001"):
    • Frappe's dashboard rendering logic reads these "DocType Link" entries defined for the "Project" Doctype.
    • It generates links in the "Connections" area of the dashboard.
    • For the "Task" link, it would typically show a count of Tasks where Task.project == "PROJ-001". Clicking this link would navigate the user to the list view of Tasks, pre-filtered for that project.

DocType Links are a key mechanism for creating a connected and navigable user experience in Frappe, allowing users to easily jump to related information from any document form.