-
Notifications
You must be signed in to change notification settings - Fork 5
/
example.qmd
175 lines (151 loc) · 6.07 KB
/
example.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
---
title: "Forms Documentation"
format:
html:
include-in-header:
- file: submit_form.md
toc: true
filters:
- jlgraves-ubc/forms
form:
id: MyFormID
submit: "Submit"
action: "javascript:submit()"
method: GET
fields:
- text: "This is a form spacer"
- name: Text1
type: text
id: textid
label: "A text field (1)"
required: true
- name: Text2
type: text
id: textid2
label: "Another text field (2)"
- text: "This is a form spacer"
- text: "---"
- name: Radio
type: radio
label: "My Radio Button"
id: radio1
values:
- text: Good
value: 1
- text: Bad
value: 0
- name: Checkbox
type: checkbox
id: checkbox1
label: "My Checkbox"
values:
- text: "High"
value: "hi"
- text: "Low"
value: "lo"
- text: "Mid"
value: "mid"
- name: Selector
type: select
id: selector1
label: My Selector
multiple: true #multiple selections?
size: 3 #number to size
values:
- text: Option 1
value: 1
- text: Option 2
value: 2
- text: Option 3
value: 3
- text: Option 4
value: 4
- name: BigText
id: textarea1
type: textarea
label: Enter lots of text
width: 30 #in rows
height: 30 #in cols
- name: MyEmail
id: email1
type: email
label: "Enter your email"
- name: FileUpload
id: file1
type: file
label: Upload a file
---
This page demonstrates how to use the `form` shortcode. A form consists of a set of YAML keys and a shortcode.
Insert the shortcode where you want the form to appear. The form is wrapped in a `div` which you can use to style the form, using CSS. The default form style uses whatever theme you have chosen from the [Bootswatch](https://bootswatch.com/) themes supported by Quarto.
If you use a custom theme, you will likely need to provide CSS for the form element classes, if you don't like the default.
# Form Elements
:::{.warning}
For most of the form elements that are not intended as labels, you should use HTML-safe names. Calling an form's name `"?><div ali --: !---` is probably a bad idea and will break your form.
:::
The form elements are:
| Key | Purpose | Values | Required? |
| -------- | -------------------------------------------------- | ---------- | ---------------------------- | -------- |
| `action` | path to action | `filepath` | Required |
| `method` | HTTP method used for form submission (GET or POST) | `string` | Optional (Default: `GET`) |
| `submit` | text for submit button | `string` | Optional (Default: `Submit`) |
| `fields` | list of fields | `...` | `fields` | Required |
| `id` | an id for the form | `string` | Optional (Default: `form`) |
This is specified as follows:
```yaml
form:
action: "pathto/action/file.js"
method: GET
submit: "Submit Form"
id: FormID
fields:
- "..."
```
## Form Fields
The `fields` element is a list of fields, as outlined below. All inputs are strings, unless mentioned:
| Key | Description | Required? |
| ---------- | ---------------------------------------------------------------------- | ----------------------------- |
| `name` | The name for the field | Yes |
| `type` | The input type: see list below | Yes |
| `id` | The id for the input | Yes |
| `label` | The label to display for the input | Yes |
| `values` | A list of values for multiple inputs | `radio`, `checkbox`, `select` |
| `width` | `integer`: Width of input | No |
| `height` | `integer`: Height of input | No |
| `required` | `boolean`: Require a response^[Only works for certain types of fields] | No |
| `multiple` | `boolean`: Allow multiple values | No |
| `size` | `integer`: Number of inputs to display | No |
The currently supported input `type`-s are:
| Type | Description | Requireable? | Multiple valued |
| ---------- | --------------------------------- | ------------- | --------------- |
| `text` | Single-line text input | Yes | No |
| `textarea` | A large, multi-line text input | No | No |
| `checkbox` | A series of checkboxes | Yes^[*poorly] | Yes |
| `radio` | Series of radio options | Yes^[*poorly] | No |
| `select` | Dropdown selection, styled by CSS | Yes | No |
| `email` | Email-only text input | No | No |
| `file` | File-submission button | No | No |
## Form Field Values
The `values` for multi-line inputs are specified as
```yaml
form:
...
fields:
- ...:
values:
- text: Radio 1
value: 1
```
- `text` is the label text for the option to be displayed
- `value` is the value selecting the option will select
## Non-field Form Entries
You can also add arbitrary text using the `text` field:
```yaml
form:
...
fields:
- text: "Some text"
- text: ---
```
Using `---` will insert a horizontal rule in the form.
# Example Form
{{< form >}}