README

此插件允许在类似于购物车的捐赠列表中收集捐赠指定。

需求

此插件需要 Craft CMS 4.0.0 或更高版本。

安装

要安装此插件，请按照以下说明操作。

1. 打开您的终端并转到您的 Craft 项目

    cd /path/to/project
   

2. 然后告诉 Composer 加载插件

    composer require tungsten/growdough
   

3. 在控制面板中，转到设置 → 插件，并点击 GrowDough 的“安装”按钮。

设置

• 捐赠 URL：存储账户捐赠表单的完整 URL
• 测试模式启用：允许在 Craft 网站上测试 GrowDough 集成。启用时，GrowDough 中的结账将启用测试模式。

当测试模式启用时，将在表单中添加以下隐藏输入

<input id="growdough_test_mode" name="test_mode" value="true" type="hidden">

变量

getDonationItems

检索会话中存储的捐赠项作为集合（数组）。使用集合在 for 循环中构建项目列表。

{# Get the Donation Items stored in the session. Returns false if there are no Donation Items #}
{% set donationItems = craft.growDough.getDonationItems %}

donationItemInList

检查提供的 id 的捐赠项是否已经在捐赠项列表中。

{% if craft.growDough.donationItemInList(fund.id) %}
  {# If the item is already in the donation list, show disabled button #}
  <a href="#" class="btn disabled" disabled="disabled">Selected</a>
{% else %}
  {# Ir the item is NOT in the donation list, show the button to add it to the list. #}
  <input class="btn give-now" type="submit" title="Add to Donation List" value="Give Now">
{% endif %}

addDonationItemFormTag

打开表单标签以将捐赠项添加到捐赠项列表。

参数

• itemId 捐赠项的唯一 ID
• itemTitle 用于显示的捐赠项标题
• itemAttributes 将作为 JSON 存储的捐赠项属性数组

示例

{{ craft.growDough.addDonationItemFormTag(
  fund.id,
  fund.title,
  {
    'Donation Type': 'Scholarship Fund',
    'Donating To': 'The Erie Art Museum',
    'Designation': fund.title
  }
) }}

formTag

打开表单标签以向 GrowDough 提交捐赠。包括 GrowDough 发布 URL 和所有必需的隐藏字段。

选项

• templateVariables 包含应在 GrowDough 捐赠工作流程（捐赠表单、电子邮件收据、感谢页面等）中使用的模板变量 如果不包含，将提交空 JSON 数组。
• donationItems 包含要覆盖捐赠列表中的项目的数组。 如果不包含，将自动从捐赠列表生成捐赠项数组。
• paymentMethod 如果表单旨在使用预定义的 GrowDough 捐赠表单，请包含预定义的支付方式（信用卡 或 捐赠卡）。
• donationAmount 如果表单旨在使用 GrowDough 捐赠表单上的预定义金额，请包含预定义的捐赠金额。

最常见用途

表单标签通常与 templateVariables 和 paymentType 一起使用。

{{ craft.growDough.formTag({
  'templateVariables': {
    'Variable Key': 'Variable Value',
    'Variable Key': 'Variable Value',
    ...
  },
  'paymentMethod': 'credit_card|giving_card',
  'donationAmount': 100
}) }}

完整变量语法

{{ craft.growDough.formTag({
  'templateVariables': {
    'Variable Key': 'Variable Value',
    'Variable Key': 'Variable Value',
    ...
  },
  'donationItems': [
    {
      "title": "Item title",
      "attributes": {
        "Attribute Key": "Attribute Value",
        "Attribute Key": "Attribute Value",
        ...
      }
    },
    {
      "title": "Item title",
      "attributes": {
        "Attribute Key": "Attribute Value",
        "Attribute Key": "Attribute Value",
        ...
      }
    }
  ],
  'paymentMethod': 'credit_card|giving_card',
  'donationAmount': 100
}) }}

getDonationItemsJson

将捐赠项列表格式化为编码的 JSON 字符串。

{{ craft.growDough.getDonationItemsJson }}

donationsUrl

从插件设置中检索 GrowDough 捐赠 URL。该 URL 用于将捐赠发布到特定账户的 GrowDough 系统。

<form action="{{ craft.growDough.donationsUrl }}" method="post">

givingCardPurchaseUrl

从插件设置中检索 GrowDough 捐赠卡购买 URL。该 URL 用于将所需的捐赠卡金额发布到特定账户的 GrowDough 系统。

<form action="{{ craft.growDough.givingCardPurchaseUrl }}" method="post">

操作

将捐赠项添加到捐赠项

将特定的捐赠项添加到 捐赠列表。如果列表中已存在具有提供的 itemId 的项，则 不会 添加。

使用 addDonationItemFormTag 变量的示例

{{ craft.growDough.addDonationItemFormTag(
  fund.id,
  fund.title,
  {
    'Attribute Key': 'Attribute Value',
    'Attribute Key': 'Attribute Value',
    ...
  }
) }}
  <h3>{{ fund.title }}</h3>
  <input class="btn give-now" type="submit" title="Add to Donation List" value="Give Now">
</form>

直接使用 HTML 表单的示例

{% set itemId = fund.id %}
{% set itemTitle = fund.title %}
{% set itemAttributes = {
  'Attribute Key': 'Attribute Value',
  'Attribute Key': 'Attribute Value',
  ...
} %}
<form method="post" action="" accept-charset="UTF-8">
  <input type="hidden" name="action" value="growDough/addDonationItem">
  <input type="hidden" name="itemId" value="{{ itemId }}">
  <input type="hidden" name="itemTitle" value="{{ itemTitle }}">
  <input type="hidden" name="itemAttributes" value="{{ itemAttributes|json_encode()|e }}">
  <h3>{{ fund.title }}</h3>
  <input class="btn give-now" type="submit" title="Add to Donation List" value="Give Now">
</form>

提交后重定向到另一个页面

默认情况下，表单提交时插件将自动重新加载当前页面。

要覆盖此默认行为，在 PerForm 的 addDonationItemFormTag 之后包含 redirectInput 函数并指定您的重定向目标。

{{ craft.growDough.addDonationItemFormTag(
  fund.id,
  fund.title,
  {
    'Attribute Key': 'Attribute Value',
    'Attribute Key': 'Attribute Value',
    ...
  }
) }}
{{ redirectInput('some/url/here') }}

或者

<form method="post" action="" accept-charset="UTF-8">
  <input type="hidden" name="action" value="actions/growdough/default/add-donation-item">
  <input type="hidden" name="itemId" value="{{ itemId }}">
  <input type="hidden" name="itemTitle" value="{{ itemTitle }}">
  <input type="hidden" name="itemAttributes" value="{{ itemAttributes|json_encode()|e }}">
  {{ redirectInput('some/url/here') }}

removeDonationItem

从 捐赠列表 中删除特定的捐赠项。如果提供的 itemId 在列表中不存在，则忽略该操作。

<a href="{{ url('grow-dough/remove-donation-item', { itemId: itemId }) }}">Remove</i>

可选： 如果想在项目添加后重定向到特定页面，请添加 redirectUrl 参数。如果省略该参数，浏览器将重定向到原始页面（使用 http_referrer）。

<a href="{{ url('grow-dough/remove-donation-item', { itemId: itemId, redirectUrl: 'some/url/here' }) }}">Remove</i>

removeAllDonationItems

从 growDoughItems 会话变量中删除所有捐赠项。这在检查多指定捐赠时非常有用，需要从会话中删除，以防止捐赠完成后仍然存在。

此操作需要在提交 GrowDough 表单时通过 AJAX 调用。

$.get('/growdough/remove-all-donation-items', { deleteAll: true }, function(response) {
  console.log('Deleted ' + response.item_count + ' donation items.');
});

由 Tungsten Creative Group 提供