分类： 教程

本教程的目标是介绍框架的各个组成部分。
我们在这里只是浅尝辄止。Frappe 框架拥有
更多功能，使我们能够构建诸如
ERPNext 之类的复杂软件。

您可以通过阅读其余文档来深入了解各个主题。
以下是一些入门主题供您参考：

1. 架构
2. DocType（文档类型）
3. 文档 API
4. 表单 API
5. Bench 命令行工具

需要帮助？

您可以在我们的公共论坛上寻求帮助：discuss.frappe.io

表单脚本是客户端 JavaScript 代码，用于增强表单的用户体验。

假设你想为会员创建一条会员资格记录。为此，你需要
前往“图书馆会员”列表，创建一个新表单，选择会员并填写
其他字段，然后保存。

同样，当你想针对某位会员创建一笔交易时，你需要
新建一个“图书馆交易”表单。

我们可以让这个过程变得更简单。在 library_member.js 中编写以下代码：

frappe.ui.form.on('Library Member', {
 refresh: function(frm) {
 frm.add_custom_button('Create Membership', () => {
 frappe.new_doc('Library Membership', {
 library_member: frm.doc.name
 })
 })
 frm.add_custom_button('Create Transaction', () => {
 frappe.new_doc('Library Transaction', {
 library_member: frm.doc.name
 })
 })
 }
});

现在，刷新页面并前往“图书馆会员”表单。你应该会在右上角看到两个按钮。
点击它们试试看。它们会自动在这些文档中设置
图书馆会员，从而简化操作流程。

这里我们只是浅尝辄止。使用表单脚本，你还可以做更多事情。
在“表单脚本 API”中了解更多关于 API 的信息。

下一步：门户页面

Single DocType is a special type of DocType that stores only one record. It is useful for storing settings or configuration values that are global to the application. The data is stored in a single row in the database, and the form is always available for editing.

Library Settings Controller

Now, let’s write code to use the Library Settings in our validations. We will
update the Library Transaction validation to check the loan period and
maximum number of issued articles.

library_transaction.py

from frappe.model.document import Document
from frappe.model.docstatus import DocStatus

import frappe

class LibraryMembership(Document):
    # check before submitting this document
    def before_submit(self):
        exists = frappe.db.exists(
            "Library Membership",
            {
                "library_member": self.library_member,
                "docstatus": DocStatus.submitted(),
                # check if the membership's end date is later than this membership's start date
                "to_date": (">", self.from_date),
            },
        )
        if exists:
            frappe.throw("There is an active membership for this member")

        # get loan period and compute to_date by adding loan_period to from_date
        loan_period = frappe.db.get_single_value("Library Settings", "loan_period")
        self.to_date = frappe.utils.add_days(self.from_date, loan_period or 30)

We used the tabSingles method to get the Library Settings record. Since it
is a Single DocType, we can directly access its fields. We also used the
frappe.db.get_single_value method to count the number of issued articles for the member.

Library Membership Validation Update

We also need to update the Library Membership validation to use the Library
Settings for the loan period.

library_membership.py

import frappe
from frappe.model.document import Document
from frappe.model.docstatus import DocStatus

class LibraryTransaction(Document):
    def before_submit(self):
        if self.type == "Issue":
            self.validate_issue()
            self.validate_maximum_limit()
            # set the article status to be Issued
            article = frappe.get_doc("Article", self.article)
            article.status = "Issued"
            article.save()

        elif self.type == "Return":
            self.validate_return()
            # set the article status to be Available
            article = frappe.get_doc("Article", self.article)
            article.status = "Available"
            article.save()

    def validate_issue(self):
        self.validate_membership()
        article = frappe.get_doc("Article", self.article)
        # article cannot be issued if it is already issued
        if article.status == "Issued":
            frappe.throw("Article is already issued by another member")

    def validate_return(self):
        article = frappe.get_doc("Article", self.article)
        # article cannot be returned if it is not issued first
        if article.status == "Available":
            frappe.throw("Article cannot be returned without being issued first")

    def validate_maximum_limit(self):
        max_articles = frappe.db.get_single_value("Library Settings", "max_articles")
        count = frappe.db.count(
            "Library Transaction",
            {
                "library_member": self.library_member,
                "type": "Issue",
                "docstatus": DocStatus.submitted(),
            },
        )
        if count >= max_articles:
            frappe.throw("Maximum limit reached for issuing articles")

    def validate_membership(self):
        # check if a valid membership exist for this library member
        valid_membership = frappe.db.exists(
            "Library Membership",
            {
                "library_member": self.library_member,
                "docstatus": DocStatus.submitted(),
                "from_date": ("<", self.date),
                "to_date": (">", self.date),
            },
        )
        if not valid_membership:
            frappe.throw("The member does not have a valid membership")

Now, when you create a Library Membership, the loan period will be automatically
set based on the Library Settings.

Summary

In this tutorial, we learned about different types of doctypes in the framework:

• Master and Transactional DocTypes
• Submittable DocTypes
• Single DocTypes

We also learned how to use Link fields to connect records, fetch values from
linked records, and write validations for our doctypes.