Skip to content

Commit 0c57ac9

Browse files
NicolasDorierdennisreimann
NicolasDorier
and
dennisreimann
authored
Add user documentation for Forms (#1251)
* Add user documentation for Forms * Formatting improvements --------- Co-authored-by: Dennis Reimann <[email protected]>
1 parent 1914e73 commit 0c57ac9

File tree

4 files changed

+146
-0
lines changed

4 files changed

+146
-0
lines changed

‎docs/.vuepress/config.js

+1
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@ const sidebarUserGuide = [
8080
children: [['/Refund', 'Refunds']]
8181
},
8282
['/Payouts', 'Payouts'],
83+
['/Forms', 'Forms'],
8384
['/Apps', 'Apps'],
8485
['/Accounting', 'Accounting'],
8586
{

‎docs/.vuepress/styles/index.styl

+4
Original file line numberDiff line numberDiff line change
@@ -449,6 +449,10 @@ h5, h6 {
449449
background: transparent;
450450
}
451451

452+
table code {
453+
white-space: nowrap;
454+
}
455+
452456
th, td {
453457
border-color: var(--btcpay-body-border-light);
454458
}

‎docs/Forms.md

+141
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Forms
2+
3+
BTCPay Server's Forms feature enables you to request that your customer complete a form before proceeding with a payment.
4+
5+
These forms are fully customizable to suit your requirements.
6+
7+
Example of form definition:
8+
9+
```json
10+
{
11+
"fields": [
12+
{
13+
"name": "buyerEmail",
14+
"constant": false,
15+
"type": "email",
16+
"value": null,
17+
"required": true,
18+
"label": "Enter your email",
19+
"helpText": "This is help text",
20+
"fields": []
21+
},
22+
{
23+
"name": "buyerName",
24+
"constant": false,
25+
"type": "text",
26+
"value": null,
27+
"required": true,
28+
"label": "Name",
29+
"helpText": null,
30+
"fields": []
31+
},
32+
{
33+
"name": "buyerAddress1",
34+
"constant": false,
35+
"type": "text",
36+
"value": null,
37+
"required": true,
38+
"label": "Address Line 1",
39+
"helpText": null,
40+
"validationErrors": [],
41+
"fields": []
42+
},
43+
{
44+
"name": "buyerAddress2",
45+
"constant": false,
46+
"type": "text",
47+
"value": null,
48+
"required": false,
49+
"label": "Address Line 2",
50+
"helpText": null,
51+
"fields": []
52+
},
53+
{
54+
"name": "buyerCity",
55+
"constant": false,
56+
"type": "text",
57+
"value": null,
58+
"required": true,
59+
"label": "City",
60+
"helpText": null,
61+
"fields": []
62+
},
63+
{
64+
"name": "buyerZip",
65+
"constant": false,
66+
"type": "text",
67+
"value": null,
68+
"required": false,
69+
"label": "Postcode",
70+
"helpText": null,
71+
"fields": []
72+
},
73+
{
74+
"name": "buyerState",
75+
"constant": false,
76+
"type": "text",
77+
"value": null,
78+
"required": false,
79+
"label": "State",
80+
"helpText": null,
81+
"fields": []
82+
},
83+
{
84+
"name": "buyerCountry",
85+
"constant": false,
86+
"type": "text",
87+
"value": null,
88+
"required": true,
89+
"label": "Country",
90+
"helpText": null,
91+
"fields": []
92+
}
93+
]
94+
}
95+
```
96+
97+
Output:
98+
99+
![Form](./img/Forms-1.png 'Form')
100+
101+
In a field definition, only the following fields can be set:
102+
103+
| Field | Description |
104+
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
105+
| `.fields.constant` | If `true`, the `.value` must be set in the form definition, and the user will not be able to change the field's value. ( example: the form definition's version) |
106+
| `.fields.type` | The HTML input type `text`, `radio`, `checkbox`, `password`, `hidden`, `button`, `color`, `date`, `datetime-local`, `month`, `week`, `time`, `email`, `number`, `range`, `search`, `url`, `select`, `tel` |
107+
| `.fields.options` | If `.fields.type` is `select`, the list of selectable values |
108+
| `.fields.options.text` | The text displayed for this option |
109+
| `.fields.options.value` | The value of the field if this option is selected |
110+
| `.fields.type=fieldset` | Create a HTML `fieldset` around the children `.fields.fields` (see below) |
111+
| `.fields.name` | The JSON property name of the field as it will appear in the invoice's metadata |
112+
| `.fields.value` | The default value of the field |
113+
| `.fields.required` | if `true`, the field will be required |
114+
| `.fields.label` | The label of the field |
115+
| `.fields.helpText` | Additional text to provide an explanation for the field. |
116+
| `.fields.fields` | You can organize your fields in a hierarchy, allowing child fields to be nested within the invoice's metadata. This structure can help you better organize and manage the collected information, making it easier to access and interpret. For example, if you have a form that collects customer information, you can group the fields under a parent field called customer. Within this parent field, you might have child fields like name, email, and address. |
117+
118+
The values of the fields are stored in the metadata of the invoice.
119+
120+
## Well-known field names
121+
122+
The field name represents the JSON property name that stores the user-provided value in the invoice's metadata.
123+
124+
Some well-known names can be interpreted and modify the invoice's settings.
125+
126+
| Field name | Description |
127+
| ------------------ | ---------------------- |
128+
| `invoice_amount` | The invoice's amount |
129+
| `invoice_currency` | The invoice's currency |
130+
131+
## Pre-filling form values
132+
133+
You can pre-fill the fields of an invoice automatically by adding query strings to the form's URL, such as `?your_field=value`.
134+
135+
Here are some use cases for this feature:
136+
137+
- `Assisting user input`: Pre-fill fields with known customer information to make it easier for them to complete the form. For example, if you already know a customer's email address, you can pre-fill the email field to save them time.
138+
- `Personalization`: Customize the form based on customer preferences or segmentation. For instance, if you have different customer tiers, you can pre-fill the form with relevant data, such as their membership level or specific offers.
139+
- `Tracking`: Track the source of customer visits by using hidden fields and pre-filled values. For example, you can create different links with pre-filled `utm_media` values for each marketing channel (e.g., Twitter, Facebook, email). This helps you analyze the effectiveness of your marketing efforts.
140+
141+
- `A/B testing`: Pre-fill fields with different values to test different versions of a form, enabling you to optimize the user experience and conversion rates.

‎docs/img/Forms-1.png

8.46 KB
Loading

0 commit comments

Comments
 (0)