You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/AdvancedForms.md
+35-1
Original file line number
Diff line number
Diff line change
@@ -129,10 +129,44 @@ Some well-known names can be interpreted and modify the invoice's settings.
129
129
|`invoice_amount`| The invoice's amount |
130
130
|`invoice_currency`| The invoice's currency |
131
131
| Starts with `invoice_amount_adjustment`| As long its value is computed to be a number, it will adjust the invoice amount accordingly. |
132
+
| Starts with `invoice_amount_multiply_adjustment`| Adjusts the generated invoice amount by multiplying with this value. |
132
133
133
134
## Mirror fields
134
135
135
-
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.
136
+
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.
137
+
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.
138
+
139
+
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.
140
+
Or you can generate percentage-based promo codes based on the `invoice_amount_multiply_adjustment` field.
141
+
142
+
Here's an example of how three promo codes with different discounts can be implemented:
Copy file name to clipboardexpand all lines: docs/Forms.md
+31-29
Original file line number
Diff line number
Diff line change
@@ -1,65 +1,65 @@
1
1
# Forms
2
2
3
-
BTCPay Server's Forms Builder enables you to request specific information from your customer.
3
+
BTCPay Server's Forms Builder enables you to request specific information from your customer.
4
4
5
5
These forms are fully customizable to suit your requirements.
6
-
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.
6
+
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.
7
7
8
-
## Setting up your store's first Custom form.
8
+
## Setting up your store's first Custom form.
9
9
10
-
In this example, we will start with creating a standard form we've pre-made.
11
-
Click on Store Settings and the last tab of your store settings is Forms. Click Forms to create your first Custom Form.
10
+
In this example, we will start with creating a standard form we've pre-made.
11
+
Click on Store Settings and the last tab of your store settings is Forms. Click Forms to create your first Custom Form.
12
12
13
13
14
14
15
-
On the custom forms page, click Create New Form.
16
-
We've pre-made two examples, `Email` and `Address`.
17
-
For this example, click the Address form.
15
+
On the custom forms page, click Create New Form.
16
+
We've pre-made two examples, `Email` and `Address`.
17
+
For this example, click the Address form.
18
18
19
19
20
20
21
-
We can now drag around the fields pre-made by BTCPay Server.
22
-
You can re-order them or create a new field by clicking on the `Add form element` at the bottom of the form.
21
+
We can now drag around the fields pre-made by BTCPay Server.
22
+
You can re-order them or create a new field by clicking on the `Add form element` at the bottom of the form.
23
23
24
24
## Create a custom form.
25
25
26
-
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.
26
+
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.
27
27
28
-
Let's create a custom form in the following steps.
28
+
Let's create a custom form in the following steps.
29
29
We will start at the same settings tab from the previous example, Store settings -> Forms.
30
30
31
-
Click `create form` in the top right.
32
-
We'll start by giving it a name; in the example, we will use `Restaurant`.
33
-
Unlike before, we will start with the empty field that was generated.
31
+
Click `create form` in the top right.
32
+
We'll start by giving it a name; in the example, we will use `Restaurant`.
33
+
Unlike before, we will start with the empty field that was generated.
34
34
35
35
36
36
37
-
1. We will name the first field, `Table number`
37
+
1. We will name the first field, `Table number`
38
38
2. Define the `Type` of the field; we need it to be Text or Number, click on the drop-down and select `Number`.
39
39
40
40
41
41
42
42
3. The label we set for this field as it shows to the customer; in our example, we will name it `Table Number`.
43
-
4. Regarding The name of the field, we replicate the previous field's name, `Table Number`, for consistency.
43
+
4. Regarding The name of the field, we replicate the previous field's name, `Table Number`, for consistency.
44
44
5. We could define a `Default value`; however, we'll keep it empty in the example.
45
-
6.`Helper Text` This is the text provided below the field we are creating to indicate what you request from the customer.
46
-
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.
45
+
6.`Helper Text` This is the text provided below the field we are creating to indicate what you request from the customer.
46
+
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.
47
47
48
48
49
49
50
-
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.
50
+
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.
51
51
52
52
53
53
54
-
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!
54
+
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!
55
55
56
56
57
57
58
-
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.
58
+
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.
59
59
60
60
## Public Forms
61
61
62
-
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.
62
+
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.
63
63
64
64
By default, the invoice currency is set to the store's default currency, and the amount is set to "any".
65
65
@@ -72,11 +72,14 @@ You can configure the form to have a pre-configured currency and amount by creat
72
72
73
73
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.
74
74
75
-
## Adjust invoice amounts based on user input
75
+
## Adjust invoice amounts based on user input
76
76
77
77
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.
78
78
79
-
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.
79
+
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.
80
+
81
+
This functionality currently works for public form usage and for the Point of Sale plugin.
82
+
See the [Mirror Fields](./AdvancedForms/#mirror-fields) section of the Advanced Forms guide for details.
80
83
81
84
### Charging extra based on shipping method
82
85
@@ -86,14 +89,14 @@ Note: This is a simple example. While the invoice amount will be correctly adjus
86
89
87
90
To save the user selected shipping method choice we must do the following instead:
88
91
* 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`.
89
-
* 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.
92
+
* 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.
90
93
91
94
### Promo codes
92
95
93
96
* Create a field of type "text", with the name `promoCode`.
94
-
* 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`.
97
+
* 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`.
95
98
96
-
When the user enters `chocolate` in the promo code field, the invoice amount will be adjusted by -5.
99
+
When the user enters `chocolate` in the promo code field, the invoice amount will be adjusted by -5.
97
100
98
101
### Showing user input on the receipt
99
102
@@ -110,4 +113,3 @@ Only file a [Github issue](https://github.com/btcpayserver/btcpayserver/issues)
110
113
Please check out our [official website](https://btcpayserver.org/) and [FAQ](./FAQ/README.md#btcpay-frequently-asked-questions-and-common-issues) for more details.
0 commit comments