分类： Frappe

Bench 是一个用于管理 Frappe 部署的命令行工具。它提供了一个简便的界面，帮助你轻松设置和管理基于 Frappe 框架的多个站点和应用。

不过，“bench”这个词在不同语境下含义可能不同。我们既用它指代命令行工具，也用它指代目录，这经常会造成混淆。

“你更新 bench 了吗？”

“更新了，这次最新版本的迁移顺利多了。”

“什么？！我是让你更新命令行工具！”

“但愿客户会喜欢第 13 版。”

为了避免这类情况，我们用 “Bench” 指代 bench 目录，用 “Bench CLI” 指代命令行工具。

要安装 Bench CLI 并搭建 Frappe 环境，请按照安装说明操作。

你可能会惊讶地发现，很多 bench 命令其实是由 Frappe 框架提供的，而不是 Bench CLI 本身。一般来说，这些命令都是针对特定站点运行的（可以使用 --site 参数）。即使是像 bench update 这样的命令，也只是对 Frappe 框架命令（如 backup 和 migrate）的简单封装，再加上一些必要的 bench 和系统级操作。

参考资料

1. Bench 命令
2. Frappe 命令
3. 命令参考
4. 扩展 CLI

Google Drive 是 Google 开发的一款文件存储和同步服务。它允许用户存储、同步和共享文件。Google Drive 是 Google Workspace 的重要组成部分，后者是 Google 面向企业推出的按月订阅服务。

你可以使用 Frappe 框架的文件选择器从 Google Drive 中选择任意文件，并将其附加到当前的 DocType 上。例如，你可以将存储在 Google Drive 中的发票 PDF 附加到 Frappe 应用中的采购发票上。

设置

Google Cloud Console

首先，我们需要获取一些凭据，以便访问 Google Drive。你可以使用设置工具，它会引导你在 Google Cloud Console 中创建项目、启用 API 并创建凭据。

如果你还没有创建应用的 API 密钥，请点击创建凭据 > API 密钥。接下来，在API 密钥部分找到你的 API 密钥。你可以打开 API 密钥并对其进行限制。

1. 在应用限制下选择“HTTP 来源”，
2. 在网站限制下添加你的 Frappe 实例的主机名，
3. 在API 限制下选择“限制密钥”并勾选“Google Picker API”。

如果你还没有创建 OAuth 2.0 凭据，请点击创建凭据 > OAuth 客户端 ID。

1. 在应用类型下选择“Web 应用”，
2. 在已授权的 JavaScript 来源下添加你的 Frappe 实例的主机名。

创建凭据后，你可以在“凭据”页面上看到你的客户端 ID。

最后但同样重要的是，你需要配置 OAuth 同意屏幕。这是用户首次使用 Google Drive 选择器时会看到的页面。它会请求用户授权访问其 Google Drive。你可以根据自己的需要进行配置，只需注意在范围页面上添加范围 https://www.googleapis.com/auth/drive.readonly。

你还需要准备好你的应用 ID。这是你的项目编号，可以在IAM 和管理 > 设置下找到。

本节的某些内容基于 Google 创建并共享的作品进行了修改，并根据 Creative Commons 4.0 署名许可中描述的条款使用。

Frappe 实例

现在 Google Picker API 已启用，并且我们拥有了必要的凭据，接下来就可以在你的 Frappe 实例中配置Google 设置了。

1. 打开Google 设置。
2. 勾选启用复选框。
3. 在“Google Drive 选择器”部分，勾选启用 Google Drive 选择器复选框。
4. 输入你的应用 ID、客户端 ID 和 API 密钥。
5. 保存Google 设置并重新加载浏览器窗口。

现在，当你点击侧边栏中的“附加文件”时，你应该能看到 Google Drive 图标。

如果你是第一次点击它，需要授权 Frappe 应用访问你的 Google Drive 文件。

然后 Google Drive 选择器会打开，你可以选择一个文件。

点击左下角的蓝色按钮，将该文件的链接附加到当前 DocType 上。

如果你在寻找技术细节，Google Drive 是在拉取请求 #12715 中引入的。

Razorpay 是印度一款广受欢迎的支付解决方案，企业可以通过其产品套件来接收、处理和发放付款。它让你可以使用信用卡、借记卡和网上银行等支付方式。

集成 Razorpay 客户端结账

Razorpay 支付

集成步骤

在你的代码中引入结账脚本

将以下脚本插入到你的页面中 <script type="text/javascript" src="/assets/js/checkout.min.js"></script>
结账脚本会自动获取 Razorpay 结账脚本，并对其 API 进行封装，提供一些语法糖。

在后端创建订单控制器

def get_razorpay_order(self):
 controller = get_payment_gateway_controller("Razorpay")

 payment_details = {
 "amount": 30000,
 ...
 "reference_doctype": "Conference Participant",
 "reference_docname": self.name,
 ...
 "receipt": self.name
 }

 return controller.create_order(**payment_details)

在客户端使用结账 API 发起支付

function make_payment(ticket) {
 var options = {
 "name": "<checkout modal title>",
 "description": "<checkout modal description>",
 "image": "<checkout modal logo>",
 "prefill": {
 "name": "<customer name>",
 "email": "<customer email>",
 "contact": "<customer phone>"
 },
 "theme": {
 "color": "<modal color>"
 },
 "doctype": "<reference doctype>", // Mandatory
 "docname": "<reference docname mandatory razorpay="new" frappe.checkout.razorpay razorpay.on_open="()"> {
 // SCRIPT TO RUN WHEN MODAL OPENS
 }
 razorpay.on_success = () => {
 // SCRIPT TO RUN ON PAYMENT SUCCESS
 }
 razorpay.on_fail = () => {
 // SCRIPT TO RUN ON PAYMENT FAILURE
 }
 razorpay.init() // Creates the order and opens the modal
}
</reference></reference></modal></customer></customer></customer></checkout></checkout></checkout>

生命周期

1. 在后端创建订单

订单首先在服务器端创建，由 razorpay.init() 触发，为此必须为该文档类型创建一个控制器 get_razorpay_order。服务器方法会设置要收取的金额以及一个唯一的收据 ID，供 Razorpay API 使用。

get_razorpay_order 内部会调用 Razorpay 设置文档类型的 create_order 控制器，然后创建一个集成请求并向 https://api.razorpay.com/v1/orders 发送 POST 请求。

1. 在客户端处理结账

订单创建成功后，会返回 order_id，该值会与集成请求中的订单关联存储。这个 order_id 会被传递给客户端，从而触发 Razorpay 弹窗。支付完成后，根据支付状态调用成功或失败的 API 方法，并将支付 ID 传递给它。

1. 验证支付

API 方法被调用后，交易详情会保存在集成请求中。如果成功，则会调用 authorize_payment 控制器，该控制器使用支付 ID 从 Razorpay API 检查支付状态。一旦授权通过，集成请求会被标记为已完成，随后会调用 reference_doctype 的支付成功钩子。

你可以在他们的文档中了解更多关于 Razorpay 自定义结账的信息

网页表单请求

网页表单请求会为网页表单创建一个私密请求链接。

当表单不应完全公开，但填写者仍然可以在没有用户账号的情况下提交时，就可以使用它。例如，你可以向客户发送客户满意度调查链接，预填客户专属的值，并将内部字段对浏览器隐藏。

何时使用

在以下情况下使用网页表单请求：

1. 填写者应通过私密链接打开表单。
2. 填写者可能没有用户账号。
3. 表单应包含填写者专属的值。
4. 目标文档需要隐藏值，而这些值不应暴露在网页中。

创建请求

创建一个网页表单请求，并选择它所属的网页表单。系统会自动生成一个 URL 安全的键。

该请求可以定义：

• 过期时间：请求键的过期日期和时间。
• 网页表单值：显示在网页表单中、且填写者可编辑的 JSON 值。
• 文档值：提交时应用到目标文档、但不会发送到浏览器的 JSON 值。

请求键会用于网页表单 URL：

/your-web-form-route/new?web_form_request_key=<key>
</key>

你可以从网页表单请求表单中复制此 URL。

要求提供键

在网页表单上启用需要键，以要求提供有效的网页表单请求键。

如果启用了需要键且未提供有效键，则无法打开或提交网页表单。

如果同时启用了需要登录，则两个条件都适用：用户必须已登录，并且必须提供有效的请求键。

预填值和隐藏值

对于应向填写者显示的字段，使用网页表单值。这些字段必须包含在网页表单字段表中。

对于应在创建的文档上设置但不应对填写者可见的字段，使用文档值。这些字段必须存在于目标 DocType 上。

JSON 键必须使用底层字段名，例如 customer 或 survey_source。

示例：

{
 "customer": "CUST-0001",
 "survey_source": "Partner CSAT"
}

过期与使用

如果设置了过期时间，则该请求键在该日期和时间之后无法使用。

对于单次响应的网页表单，请求在成功提交后会被标记为已使用，并链接到创建的目标文档。如果网页表单设置允许，这允许之后使用同一个键来编辑或删除该响应。

对于启用了允许多次响应的网页表单，请求键可以重复用于多次提交，并且不会链接到单个目标文档。

相关网页表单设置

• 允许多次响应：
  如果启用，同一个请求键可以提交多个响应。在此模式下，网页表单请求不能有引用文档名称，因为一个请求可能会创建多个文档。
• 提交后允许编辑：
  如果启用，链接到某个响应的请求键可以打开并编辑该响应。
• 允许删除：
  如果启用，链接到某个响应的请求键可以删除该响应。

你可以自定义你的网页表单，让它更独特，并启用满足你使用场景的功能。

字段布局

你可以在网页表单字段表格中添加 Column Breaks 和 Section Breaks 来更改表单字段的布局。

多步骤网页表单

更新布局能让网页表单看起来更好，但如果网页表单有很多字段，它仍然会变得很长。
我们可以添加 Page Breaks 来将各个部分分隔到不同页面（称为多步骤网页表单）。

你最多可以添加 9 个分页符，这最多只允许 10 个页面。

下面提到的所有自定义选项都可以在网页表单文档的“自定义”选项卡中完成。

提交按钮标签

你可以更改网页表单上提交按钮的标签。

横幅图片

你现在可以在网页表单上添加横幅图片。

面包屑导航

你可以通过添加 JSON 对象来自定义网页表单中的面包屑导航。

只有在网页表单启用了 [list view](/framework/v14/user/en/web-form/settings#list-settings) 时，面包屑导航才会显示。

示例：

提交后页面

你可以设置自定义的成功标题和消息，它们会在用户提交网页表单后显示。

根据访问权限，提交页面上会显示额外的按钮，例如

查看之前的回复

编辑你的回复

查看你的回复
和

提交另一条回复

如果网页表单是通过网页表单请求打开的，这些操作链接会在需要时保留请求密钥。

通过设置 success_url 字段，将你的网页表单配置为在提交后 5 秒重定向到特定 URL。

自定义 CSS

你可以添加自定义 CSS 来更改网页表单的外观

示例：

.web-form-header {
 margin-bottom: 2rem;
 border: 1px solid var(--blue-200) !important;
 border-radius: var(--border-radius);
 background-color: var(--blue-50) !important;
}

.web-form-head {
 border: none !important;
 padding-bottom: 2rem !important;
}

.web-form {
 border: 1px solid var(--dark-border-color) !important;
 border-radius: var(--border-radius);
 padding-top: 2rem !important;
}

客户端脚本

你也可以向网页表单添加自定义客户端脚本

事件处理器

编写一个事件处理器，在字段发生变化时执行操作。

frappe.web_form.on([fieldname], [handler]);

获取值

获取特定字段的值

value = frappe.web_form.get_value([fieldname]);

设置值

设置特定字段的值

frappe.web_form.set_value([fieldname], [value])

验证

frappe.web_form.validate 会在 web_form 保存之前被调用。通过重写 validate 方法来添加自定义
验证。要阻止用户保存，
请返回 false；

frappe.web_form.validate = () => {
 // return false if not valid
}

设置字段属性

frappe.web_form.set_df_property([fieldname], [property], [value]);

表单加载时触发脚本

在表单加载后使用自定义设置初始化表单

frappe.web_form.after_load = () => {
 // init script here
}

示例

如果无效则重置值

frappe.web_form.on('amount', (field, value) => {
 if (value < 1000) {
 frappe.msgprint('Value must be more than 1000');
 field.set_value(0);
 }
});

自定义验证

frappe.web_form.validate = () => {
 let data = frappe.web_form.get_values();
 if (data.amount < 1000) {
 frappe.msgprint('Value must be more than 1000');
 return false;
 }
});

根据值隐藏字段

frappe.web_form.on('amount', (field, value) => {
 if (value < 1000) {
 frappe.web_form.set_df_property('rate', 'hidden', 1);
 }
});

启动时显示消息

frappe.web_form.after_load = () => {
 frappe.msgprint('Please fill all values carefully');
}

网页表单设置

在 Settings 选项卡中有多个复选框，可用于启用和禁用不同的功能。

需要登录

如果你希望允许访客用户提交回复，只需取消勾选 login_required 复选框即可。已登录用户也可以使用。默认情况下该选项是禁用的。

如果你只希望已登录用户提交回复，只需勾选 login_required 复选框即可。

启用后，将会显示允许多次回复、允许提交后编辑、允许删除、允许评论、显示附件和显示列表这些复选框。

需要密钥

当网页表单只能通过网页表单请求中的私钥打开时，请启用需要密钥。

这对于调查问卷或邀请流程非常有用，因为受访者没有用户账号，但表单又不应该公开。请求密钥可以携带可见的预填表单值和隐藏的文档值。

如果同时启用了需要登录，则用户必须已登录并且必须持有有效的请求密钥。

允许多次回复

用于让用户提交多次回复，他们可以在网页表单列表视图中查看这些回复。

启用后，列表设置区域中的显示列表复选框也会被启用。

允许提交后编辑

允许用户编辑已提交的回复。

允许删除

允许用户从网页表单列表视图中删除已提交的回复。

匿名

设置此项后，收到的回复将是匿名的。

应用文档权限

默认情况下，如果用户对不同用户提交的文档有读取权限，这些文档将在网页表单列表视图中可见。但只有勾选了应用文档权限复选框，用户才能从列表视图中打开记录。

允许打印

会添加一个打印按钮用于打印文档。仅在查看模式下可见。

允许评论

会在网页表单下方添加评论区，用户可以在那里交流。所有评论都会关联到该文档。

显示附件

会在附件区域显示文档中附带的所有附件。

最大附件大小（MB）

会限制用户上传大文件。

允许不完整表单

即使必填字段未填写，也允许提交表单。

列表设置

显示列表

会启用 List View，你可以在那里看到所有已提交的表单。你只能打开自己拥有的表单。

如果启用了 apply_document_permissions，你可以打开其他表单。

标题和列表列

你可以更改列表的标题，也可以添加/移除/排列列表视图的列。

侧边栏设置

显示侧边栏

在侧边栏中显示网页表单。选择或创建一个网站侧边栏，你可以在其中添加指向当前网页表单以及其他相关网页表单或网页的链接。

Frappe 提供了一种简便的方法，只需极少的配置就能为你的网站生成表单。这些表单可以是公开的（任何人都可以填写），可以配置为需要登录，也可以通过私有请求链接访问。

创建网页表单

要创建网页表单，在 awesomebar 中输入“new web form”并按回车。

1. 输入标题
2. 选择要为其创建记录的 DocType。
3. 添加一些介绍（可选）。
4. 点击“获取字段”按钮，从所选 doctype 中获取所有字段，或者为你的网页表单选择字段。
5. 发布它，就可以使用了。

自定义网页表单 →

私有网页表单请求 →

标准网页表单

如果你勾选“是标准”复选框，将在网页表单的
module 中创建一个新文件夹。在这个文件夹中，你会看到一个 .py 和 .js 文件
，你可以用它们来配置网页表单。这些文件需要连同你的自定义应用一起
纳入版本控制。你可以在任何站点上安装这个应用，
它都会安装这个网页表单。

Is Standard 字段只有在开发者模式下才会可见。