0
# Form Handling
1

2
Comprehensive form interaction capabilities including input field manipulation, form submission, and support for all HTML form element types (text, password, checkbox, radio, select, textarea).
3

4
## Capabilities
5

6
### Form Access and Submission
7

8
Core form functionality for finding forms and submitting them with or without specific submit elements.
9

10
```java { .api }
11
public class HtmlForm extends HtmlElement {
12
    /**
13
     * Submit the form using the default submit method
14
     * @return the Page that loads as a result of form submission
15
     * @throws IOException if submission fails
16
     */
17
    public <P extends Page> P submit() throws IOException;
18
    
19
    /**
20
     * Submit the form using a specific submit element
21
     * @param submitElement the button or input element to use for submission
22
     * @return the Page that loads as a result of form submission  
23
     * @throws IOException if submission fails
24
     */
25
    public <P extends Page> P submit(SubmittableElement submitElement) throws IOException;
26
    
27
    /**
28
     * Get a form input element by its name attribute
29
     * @param name the name attribute value
30
     * @return HtmlElement with matching name, or null if not found
31
     */
32
    public HtmlElement getInputByName(String name);
33
    
34
    /**
35
     * Get all form input elements with the specified name
36
     * @param name the name attribute value
37
     * @return List of HtmlElement objects with matching names
38
     */
39
    public List<HtmlElement> getInputsByName(String name);
40
    
41
    /**
42
     * Get a form input element by its value attribute
43
     * @param value the value attribute to search for
44
     * @return HtmlElement with matching value, or null if not found
45
     */
46
    public HtmlElement getInputByValue(String value);
47
    
48
    /**
49
     * Get a textarea element by its name attribute
50
     * @param name the name attribute value
51
     * @return HtmlTextArea with matching name, or null if not found
52
     */
53
    public HtmlTextArea getTextAreaByName(String name);
54
    
55
    /**
56
     * Get a select element by its name attribute
57
     * @param name the name attribute value
58
     * @return HtmlSelect with matching name, or null if not found
59
     */
60
    public HtmlSelect getSelectByName(String name);
61
    
62
    /**
63
     * Get a button element by its name attribute
64
     * @param name the name attribute value
65
     * @return HtmlButton with matching name, or null if not found
66
     */
67
    public HtmlButton getButtonByName(String name);
68
    
69
    /**
70
     * Get the form's method attribute (GET or POST)
71
     * @return the HTTP method for form submission
72
     */
73
    public String getMethodAttribute();
74
    
75
    /**
76
     * Get the form's action attribute (submission URL)
77
     * @return the URL where the form will be submitted
78
     */
79
    public String getActionAttribute();
80
    
81
    /**
82
     * Get the form's encoding type attribute
83
     * @return the encoding type (e.g., "application/x-www-form-urlencoded")
84
     */
85
    public String getEnctypeAttribute();
86
}
87
```
88

89
**Usage Examples:**
90

91
```java
92
HtmlPage page = webClient.getPage("https://example.com/login");
93
HtmlForm loginForm = page.getFormByName("loginForm");
94

95
// Get form information
96
String method = loginForm.getMethodAttribute(); // "POST"
97
String action = loginForm.getActionAttribute();  // "/authenticate"
98

99
// Find form elements
100
HtmlTextInput username = (HtmlTextInput) loginForm.getInputByName("username");
101
HtmlPasswordInput password = (HtmlPasswordInput) loginForm.getInputByName("password");
102
HtmlSubmitInput submitBtn = (HtmlSubmitInput) loginForm.getInputByValue("Log In");
103

104
// Fill and submit form
105
username.setValue("myuser");
106
password.setValue("mypass");
107
HtmlPage result = loginForm.submit(submitBtn);
108

109
// Or submit without specific button
110
HtmlPage result2 = loginForm.submit();
111
```
112

113
### Input Element Base Class
114

115
Base functionality for all form input elements including value access and state management.
116

117
```java { .api }
118
public abstract class HtmlInput extends HtmlElement {
119
    /**
120
     * Get the input's current value
121
     * @return the current value of the input
122
     */
123
    public String getValue();
124
    
125
    /**
126
     * Set the input's value
127
     * @param value the new value to set
128
     */
129
    public void setValue(String value);
130
    
131
    /**
132
     * Get the input's name attribute
133
     * @return the name attribute value
134
     */
135
    public String getName();
136
    
137
    /**
138
     * Get the input's type attribute
139
     * @return the input type (e.g., "text", "password", "checkbox")
140
     */
141
    public String getType();
142
    
143
    /**
144
     * Check if the input is checked (for checkboxes and radio buttons)
145
     * @return true if the input is checked
146
     */
147
    public boolean isChecked();
148
    
149
    /**
150
     * Set the checked state (for checkboxes and radio buttons)
151
     * @param checked true to check, false to uncheck
152
     */
153
    public void setChecked(boolean checked);
154
    
155
    /**
156
     * Check if the input is read-only
157
     * @return true if the input is read-only
158
     */
159
    public boolean isReadOnly();
160
    
161
    /**
162
     * Check if the input is disabled
163
     * @return true if the input is disabled
164
     */
165
    public boolean isDisabled();
166
}
167
```
168

169
### Text Input Fields
170

171
Handle text input fields with typing simulation and text selection.
172

173
```java { .api }
174
public class HtmlTextInput extends HtmlInput {
175
    /**
176
     * Type text into the field (simulates keyboard input)
177
     * @param text the text to type
178
     * @throws IOException if typing fails
179
     */
180
    public void type(String text) throws IOException;
181
    
182
    /**
183
     * Select all text in the field
184
     */
185
    public void select();
186
    
187
    /**
188
     * Get the maximum length allowed for this input
189
     * @return the maxlength attribute value, or -1 if not set
190
     */
191
    public int getMaxLength();
192
    
193
    /**
194
     * Get the placeholder text
195
     * @return the placeholder attribute value
196
     */
197
    public String getPlaceholder();
198
}
199

200
public class HtmlPasswordInput extends HtmlInput {
201
    // Inherits all HtmlInput methods
202
    // Values are handled securely but API is identical
203
}
204
```
205

206
**Usage Examples:**
207

208
```java
209
HtmlTextInput nameField = (HtmlTextInput) form.getInputByName("fullName");
210
HtmlPasswordInput passField = (HtmlPasswordInput) form.getInputByName("password");
211

212
// Set values directly
213
nameField.setValue("John Doe");
214
passField.setValue("secretpass");
215

216
// Or simulate typing
217
nameField.type("John Doe");
218

219
// Text field specific methods
220
nameField.select(); // Select all text
221
int maxLen = nameField.getMaxLength();
222
String placeholder = nameField.getPlaceholder();
223
```
224

225
### Checkbox and Radio Button Inputs
226

227
Handle boolean input controls with checked state management.
228

229
```java { .api }
230
public class HtmlCheckBoxInput extends HtmlInput {
231
    // Inherits all HtmlInput methods
232
    // Primary interaction through isChecked() and setChecked()
233
}
234

235
public class HtmlRadioButtonInput extends HtmlInput {  
236
    // Inherits all HtmlInput methods
237
    // Setting one radio button in a group unchecks others automatically
238
}
239
```
240

241
**Usage Examples:**
242

243
```java
244
// Checkbox handling
245
HtmlCheckBoxInput newsletter = (HtmlCheckBoxInput) form.getInputByName("newsletter");
246
newsletter.setChecked(true); // Check the box
247
boolean isChecked = newsletter.isChecked();
248

249
// Radio button handling  
250
List<HtmlElement> genderOptions = form.getInputsByName("gender");
251
for (HtmlElement element : genderOptions) {
252
    if (element instanceof HtmlRadioButtonInput) {
253
        HtmlRadioButtonInput radio = (HtmlRadioButtonInput) element;
254
        if ("female".equals(radio.getValue())) {
255
            radio.setChecked(true); // This unchecks other radios in the group
256
        }
257
    }
258
}
259
```
260

261
### Submit and Button Elements
262

263
Handle form submission controls and general button elements.
264

265
```java { .api }
266
public class HtmlSubmitInput extends HtmlInput {
267
    // Inherits all HtmlInput methods
268
    // Can be used with form.submit(submitElement)
269
}
270

271
public class HtmlButton extends HtmlElement {
272
    // Inherits all HtmlElement methods including click()
273
    // Can contain complex content unlike input elements
274
}
275
```
276

277
**Usage Examples:**
278

279
```java
280
// Submit input
281
HtmlSubmitInput submitBtn = (HtmlSubmitInput) form.getInputByValue("Submit");
282
HtmlPage result = form.submit(submitBtn);
283

284
// Button element
285
HtmlButton cancelBtn = (HtmlButton) form.getButtonByName("cancel");
286
Page result2 = cancelBtn.click();
287
```
288

289
### Textarea Elements
290

291
Handle multi-line text input areas with content manipulation.
292

293
```java { .api }
294
public class HtmlTextArea extends HtmlElement {
295
    /**
296
     * Get the text content of the textarea
297
     * @return the current text content
298
     */
299
    public String getText();
300
    
301
    /**
302
     * Set the text content of the textarea
303
     * @param text the new text content
304
     */
305
    public void setText(String text);
306
    
307
    /**
308
     * Type text into the textarea (simulates keyboard input)
309
     * @param text the text to type
310
     * @throws IOException if typing fails
311
     */
312
    public void type(String text) throws IOException;
313
    
314
    /**
315
     * Get the number of rows
316
     * @return the rows attribute value
317
     */
318
    public int getRows();
319
    
320
    /**
321
     * Get the number of columns
322
     * @return the cols attribute value
323
     */
324
    public int getColumns();
325
}
326
```
327

328
**Usage Examples:**
329

330
```java
331
HtmlTextArea comments = form.getTextAreaByName("comments");
332

333
// Set content
334
comments.setText("This is my feedback about the product...");
335

336
// Or simulate typing
337
comments.type("Additional comments here");
338

339
// Get textarea properties
340
String currentText = comments.getText();
341
int rows = comments.getRows();
342
int cols = comments.getColumns();
343
```
344

345
### Select Dropdown Elements
346

347
Handle dropdown select elements with option selection and multiple selection support.
348

349
```java { .api }
350
public class HtmlSelect extends HtmlElement {
351
    /**
352
     * Get all option elements in the select
353
     * @return List of HtmlOption objects
354
     */
355
    public List<HtmlOption> getOptions();
356
    
357
    /**
358
     * Get a specific option by index
359
     * @param index the option index (0-based)
360
     * @return HtmlOption at the specified index
361
     */
362
    public HtmlOption getOption(int index);
363
    
364
    /**
365
     * Get all currently selected options
366
     * @return List of selected HtmlOption objects
367
     */
368
    public List<HtmlOption> getSelectedOptions();
369
    
370
    /**
371
     * Select an option by index
372
     * @param index the index of the option to select
373
     */
374
    public void setSelectedIndex(int index);
375
    
376
    /**
377
     * Check if this is a multiple selection dropdown
378
     * @return true if multiple selections are allowed
379
     */
380
    public boolean isMultiple();
381
}
382

383
public class HtmlOption extends HtmlElement {
384
    /**
385
     * Check if this option is currently selected
386
     * @return true if the option is selected
387
     */
388
    public boolean isSelected();
389
    
390
    /**
391
     * Set the selection state of this option
392
     * @param selected true to select, false to deselect
393
     */
394
    public void setSelected(boolean selected);
395
    
396
    /**
397
     * Get the option's value attribute
398
     * @return the value that will be submitted if this option is selected
399
     */
400
    public String getValue();
401
    
402
    /**
403
     * Get the option's display text
404
     * @return the text content displayed to the user
405
     */
406
    public String getText();
407
}
408
```
409

410
**Usage Examples:**
411

412
```java
413
HtmlSelect countrySelect = form.getSelectByName("country");
414

415
// Select by index
416
countrySelect.setSelectedIndex(2); // Select third option
417

418
// Select by finding specific option
419
List<HtmlOption> options = countrySelect.getOptions();
420
for (HtmlOption option : options) {
421
    if ("US".equals(option.getValue())) {
422
        option.setSelected(true);
423
        break;
424
    }
425
}
426

427
// Get selected values
428
List<HtmlOption> selected = countrySelect.getSelectedOptions();
429
for (HtmlOption option : selected) {
430
    System.out.println("Selected: " + option.getText() + " (" + option.getValue() + ")");
431
}
432

433
// Check if multiple selection is allowed
434
boolean allowsMultiple = countrySelect.isMultiple();
435
```
436

437
### Form Encoding Types
438

439
Constants and utilities for form encoding types.
440

441
```java { .api }
442
public class FormEncodingType {
443
    public static final FormEncodingType URL_ENCODED;
444
    public static final FormEncodingType MULTIPART;
445
    public static final FormEncodingType TEXT_PLAIN;
446
    
447
    /**
448
     * Get the encoding type name
449
     * @return the MIME type string for this encoding
450
     */
451
    public String getName();
452
    
453
    /**
454
     * Get an encoding type instance by name
455
     * @param name the encoding type name
456
     * @return FormEncodingType instance
457
     */
458
    public static FormEncodingType getInstance(String name);
459
}
460
```
461

462
**Usage Examples:**
463

464
```java
465
// Check form encoding type
466
String enctype = form.getEnctypeAttribute();
467
FormEncodingType encodingType = FormEncodingType.getInstance(enctype);
468

469
// Common encoding types
470
FormEncodingType urlEncoded = FormEncodingType.URL_ENCODED; // application/x-www-form-urlencoded
471
FormEncodingType multipart = FormEncodingType.MULTIPART;    // multipart/form-data
472
FormEncodingType textPlain = FormEncodingType.TEXT_PLAIN;   // text/plain
473
```