From 10c574ed9a7b4d5bddeac9450765f3659ac2ea48 Mon Sep 17 00:00:00 2001 From: Dennis Reimann Date: Fri, 1 Dec 2023 13:01:30 +0100 Subject: [PATCH] v1.12: Add amount multiplier example Context: btcpayserver/btcpayserver#5463 --- docs/AdvancedForms.md | 36 +++++++++++++++++++++++++- docs/Forms.md | 60 ++++++++++++++++++++++--------------------- 2 files changed, 66 insertions(+), 30 deletions(-) diff --git a/docs/AdvancedForms.md b/docs/AdvancedForms.md index 7a02067c1e..8fc5a3bcdd 100644 --- a/docs/AdvancedForms.md +++ b/docs/AdvancedForms.md @@ -129,10 +129,44 @@ Some well-known names can be interpreted and modify the invoice's settings. | `invoice_amount` | The invoice's amount | | `invoice_currency` | The invoice's currency | | Starts with `invoice_amount_adjustment` | As long its value is computed to be a number, it will adjust the invoice amount accordingly. | +| Starts with `invoice_amount_multiply_adjustment` | Adjusts the generated invoice amount by multiplying with this value. | ## Mirror fields -A `Mirror` field is defined by the type `mirror`. Its value is set to the name of another field, and upon form submission, that field's value will be copied to the mirror field. The mirror type also has value mapping capabilities so that the referenced field's value can be transformed as it is copied over to the mirror field. For example, you could have a select field with a list of countries, and then create an `invoice_amount_adjustment` field, where you adjust the price of the invoice based on the country selected. +A `Mirror` field is defined by the type `mirror`. Its value is set to the name of another field, and upon form submission, that field's value will be copied to the mirror field. +The mirror type also has value mapping capabilities so that the referenced field's value can be transformed as it is copied over to the mirror field. + +For example, you could have a select field with a list of countries, and then create an `invoice_amount_adjustment` field, where you adjust the price of the invoice based on the country selected. +Or you can generate percentage-based promo codes based on the `invoice_amount_multiply_adjustment` field. + +Here's an example of how three promo codes with different discounts can be implemented: + +- `huge` = 50% discount +- `medium` = 10% discount +- `tiny` = 1% discount + +```json +{ + "fields": [ + { + "name": "promo", + "type": "text", + "label": "Promo Code" + }, + { + "name": "invoice_amount_multiply_adjustment_promo", + "type": "mirror", + "value": "promo", + "label": "Promo Codes", + "valuemap": { + "tiny": "0.99", + "medium": "0.90", + "huge": "0.5" + } + } + ] +} +``` ## Pre-filling form values diff --git a/docs/Forms.md b/docs/Forms.md index 26530adefd..284c149ca5 100644 --- a/docs/Forms.md +++ b/docs/Forms.md @@ -1,65 +1,65 @@ # Forms -BTCPay Server's Forms Builder enables you to request specific information from your customer. +BTCPay Server's Forms Builder enables you to request specific information from your customer. These forms are fully customizable to suit your requirements. -In this introduction, we will go through the visual form builder; if you'd like to do more advanced settings, please visit the [Advanced Forms](./AdvancedForms.md) section of our documentation. +In this introduction, we will go through the visual form builder; if you'd like to do more advanced settings, please visit the [Advanced Forms](./AdvancedForms.md) section of our documentation. -## Setting up your store's first Custom form. +## Setting up your store's first Custom form. -In this example, we will start with creating a standard form we've pre-made. -Click on Store Settings and the last tab of your store settings is Forms. Click Forms to create your first Custom Form. +In this example, we will start with creating a standard form we've pre-made. +Click on Store Settings and the last tab of your store settings is Forms. Click Forms to create your first Custom Form. ![BTCPay Server formbuilder - settings](./img/formbuilder/btcpayformbuilder1.png) -On the custom forms page, click Create New Form. -We've pre-made two examples, `Email` and `Address`. -For this example, click the Address form. +On the custom forms page, click Create New Form. +We've pre-made two examples, `Email` and `Address`. +For this example, click the Address form. ![BTCPay Server formbuilder - Create new form](./img/formbuilder/btcpayformbuilder2.png) -We can now drag around the fields pre-made by BTCPay Server. -You can re-order them or create a new field by clicking on the `Add form element` at the bottom of the form. +We can now drag around the fields pre-made by BTCPay Server. +You can re-order them or create a new field by clicking on the `Add form element` at the bottom of the form. ## Create a custom form. -You might have a different use case. For example if you own a restaurant you need to know the table number, how to call the customer when serving them, allergies, and special requests. +You might have a different use case. For example if you own a restaurant you need to know the table number, how to call the customer when serving them, allergies, and special requests. -Let's create a custom form in the following steps. +Let's create a custom form in the following steps. We will start at the same settings tab from the previous example, Store settings -> Forms. -Click `create form` in the top right. -We'll start by giving it a name; in the example, we will use `Restaurant`. -Unlike before, we will start with the empty field that was generated. +Click `create form` in the top right. +We'll start by giving it a name; in the example, we will use `Restaurant`. +Unlike before, we will start with the empty field that was generated. ![BTCPay Server formbuilder - Create new form](./img/formbuilder/btcpayformbuilder2-1.png) -1. We will name the first field, `Table number` +1. We will name the first field, `Table number` 2. Define the `Type` of the field; we need it to be Text or Number, click on the drop-down and select `Number`. ![BTCPay Server formbuilder - Create new form](./img/formbuilder/btcpayformbuilder2-2.png) 3. The label we set for this field as it shows to the customer; in our example, we will name it `Table Number`. -4. Regarding The name of the field, we replicate the previous field's name, `Table Number`, for consistency. +4. Regarding The name of the field, we replicate the previous field's name, `Table Number`, for consistency. 5. We could define a `Default value`; however, we'll keep it empty in the example. -6. `Helper Text` This is the text provided below the field we are creating to indicate what you request from the customer. -7. Last, we can set two parameters; one is always to make it required to be filled out; in this example, we will set this to yes. And if it's a Constant, users can't change this so we won't use the setting for the example. +6. `Helper Text` This is the text provided below the field we are creating to indicate what you request from the customer. +7. Last, we can set two parameters; one is always to make it required to be filled out; in this example, we will set this to yes. And if it's a Constant, users can't change this so we won't use the setting for the example. ![BTCPay Server formbuilder - Create new form](./img/formbuilder/btcpayformbuilder2-3.png) -After you've filled in the parameters for the field, it should show on the left of your editor how the field displays and functions when the customer interacts with it. +After you've filled in the parameters for the field, it should show on the left of your editor how the field displays and functions when the customer interacts with it. ![BTCPay Server formbuilder - Create new form](./img/formbuilder/btcpayformbuilder2-4.png) -Now that the first field is done, you can click on the `+ Add form element` below your first field and create the rest of the required form fields. Once you've made all the fields, click `Save` in the top right of your screen, and all should be set! +Now that the first field is done, you can click on the `+ Add form element` below your first field and create the rest of the required form fields. Once you've made all the fields, click `Save` in the top right of your screen, and all should be set! ![BTCPay Server formbuilder - Create new form](./img/formbuilder/btcpayformbuilder3.png) -The `Form Builder` makes creating custom forms flexible and easy. If you still require more personalization, as mentioned at the start of this guide, please read on [Advanced Forms](./AdvancedForms.md) to learn about the JSON created in the `Code` tab in the Form builder. +The `Form Builder` makes creating custom forms flexible and easy. If you still require more personalization, as mentioned at the start of this guide, please read on [Advanced Forms](./AdvancedForms.md) to learn about the JSON created in the `Code` tab in the Form builder. ## Public Forms -When `Allow form for public use` is enabled, a form can be used as a way to share a URL, where users must fill in the form and an invoice is then generated. +When `Allow form for public use` is enabled, a form can be used as a way to share a URL, where users must fill in the form and an invoice is then generated. By default, the invoice currency is set to the store's default currency, and the amount is set to "any". @@ -72,11 +72,14 @@ You can configure the form to have a pre-configured currency and amount by creat This can be used as an alternative to the Pay Button, with the added benefit that you can lock in invoice parameters such as amount and currency. - ## Adjust invoice amounts based on user input +## Adjust invoice amounts based on user input In most modern ecommerce scenarios, you need to modify the amount being charged based on user input, such as their preferred shipping method, their country, promotional codes, etc. - The form comes with such functionality as of version 1.11.0. Any field that has its name starts with `invoice_amount_adjustment` and its value is a valid number will automatically adjust the invoice amount. This functionality currently works for public form usage and for the Point of Sale plugin. + The form comes with such functionality as of BTCPay Server version 1.11.0. Any field that has its name start with `invoice_amount_adjustment` (supported since v1.11) or `invoice_amount_multiply_adjustment` (supported since v1.12) and its value being a valid number will automatically adjust the invoice amount. + + This functionality currently works for public form usage and for the Point of Sale plugin. + See the [Mirror Fields](./AdvancedForms/#mirror-fields) section of the Advanced Forms guide for details. ### Charging extra based on shipping method @@ -86,14 +89,14 @@ Note: This is a simple example. While the invoice amount will be correctly adjus To save the user selected shipping method choice we must do the following instead: * Create a field of type "select", with the name `shipping_method`, and options that map to what shipping methods you have available. We will use 2 options: `DHL` with a value of `dhl` and `Fedex` with a value of `fedex`. -* Create a field of type "mirror", with the name `invoice_amount_adjustment_shipping_method`. In `Field to mirror`, select the `shipping_method` field. And in `Value Mapper`, create all the options from `shipping_method` and the value to charge. +* Create a field of type "mirror", with the name `invoice_amount_adjustment_shipping_method`. In `Field to mirror`, select the `shipping_method` field. And in `Value Mapper`, create all the options from `shipping_method` and the value to charge. ### Promo codes * Create a field of type "text", with the name `promoCode`. -* Create a field of type "mirror", with the name `invoice_amount_adjustment_promo`. In `Field to mirror`, select the `promoCode` field. And in `Value Mapper`, create all the promotional codes you wish to have available. For example set `Original Value` to `chocolate` and `Mapped Value` to `-5`. +* Create a field of type "mirror", with the name `invoice_amount_adjustment_promo`. In `Field to mirror`, select the `promoCode` field. And in `Value Mapper`, create all the promotional codes you wish to have available. For example set `Original Value` to `chocolate` and `Mapped Value` to `-5`. -When the user enters `chocolate` in the promo code field, the invoice amount will be adjusted by -5. +When the user enters `chocolate` in the promo code field, the invoice amount will be adjusted by -5. ### Showing user input on the receipt @@ -110,4 +113,3 @@ Only file a [Github issue](https://github.com/btcpayserver/btcpayserver/issues) Please check out our [official website](https://btcpayserver.org/) and [FAQ](./FAQ/README.md#btcpay-frequently-asked-questions-and-common-issues) for more details. !!!include(supporters.html)!!! -