Forms Handling
Relevant source files
The following files were used as context for generating this wiki page:
Forms handling in Cheerio provides a set of methods designed to mirror jQuery's ability to extract and serialize data from HTML form elements. This functionality is crucial for web scraping and automation tasks where form submissions need to be simulated or analyzed. The system primarily focuses on traversing the DOM to find submittable elements and converting their current states (values, selected options, etc.) into standardized formats.
The scope of form handling includes selecting form controls like input, select, and textarea, filtering them based on criteria such as being "disabled" or "unnamed," and serializing their data into URL-encoded strings or arrays of objects.
Sources: src/api/forms.ts, src/api/forms.spec.ts, Readme.md:88-100
Core Serialization Logic
Serialization is the process of taking form elements and their values and turning them into a format suitable for transmission. Cheerio implements two primary methods for this: .serializeArray() and .serialize().
The .serializeArray() Method
This method creates a JavaScript array of objects, ready to be encoded as a JSON string. It filters the current Cheerio selection for form elements and their children, then maps them to a set of name-value pairs.
The logic follows these specific inclusion rules:
- The element must have a
nameattribute that is not an empty string. - The element must not be
disabled. - For checkboxes and radio buttons, they must be in a
checkedstate. - Buttons and file inputs are generally excluded from standard serialization unless they are part of a specific sub-selection.
The diagram above illustrates the decision logic used to determine if an element's data is included in the final output.
Sources: src/api/forms.ts:25-95, src/api/forms.spec.ts:11-85
The .serialize() Method
The .serialize() method encodes a set of form elements as a string for submission. It internally calls .serializeArray() and then transforms the resulting objects into a URL-encoded string.
| Feature | Description |
|---|---|
| Space Encoding | Spaces are converted to + characters instead of %20. |
| Key/Value Delimiter | Name and Value pairs are joined by =. |
| Entry Delimiter | Different form entries are joined by &. |
| Normalization | Line breaks in textareas are standardized to \r\n. |
Sources: src/api/forms.ts:11-20, src/api/forms.spec.ts:123-140
Submittable Element Handling
Cheerio identifies specific tags as submittable. When a form tag is selected, Cheerio automatically looks for nested children that qualify. If individual inputs are selected, it processes them directly.
Select and Option Handling
For <select> elements, the system retrieves the value of the selected <option>. If an <option> does not have a value attribute, its text content is used instead. In the case of multiple selects, every selected option is added as a separate entry in the serialization result.
Input and Textarea Handling
- Textareas: The value is extracted, and any line breaks are normalized to the
\r\nsequence to match standard browser behavior. - Checkboxes/Radios: Only processed if the
checkedproperty is true. If a checkbox is checked but lacks avalueattribute, it defaults to "on". - General Inputs: The
val()method is used to retrieve the current value.
Sources: src/api/forms.ts:40-55, src/api/forms.spec.ts:87-100, src/api/attributes.spec.ts:390-450
API Reference
The following table summarizes the primary form-related methods available on a Cheerio object.
| Method | Parameters | Return Type | Description |
|---|---|---|---|
.serialize() | None | string | Serializes form elements to a URL-encoded string. |
.serializeArray() | None | object[] | Returns an array of objects containing name and value properties. |
.val() | [value] | string | string[] | undefined | Gets or sets the value of form elements. |
Sources: src/api/forms.ts:11-25, src/api/attributes.spec.ts:382
Selection Context
Form methods can be called on a form element or a collection of input elements.
// Example: Serializing a whole form
$('form#login').serialize();
// Example: Serializing specific inputs only
$('input[type="text"]').serializeArray();
Sources: src/api/forms.spec.ts:12-20, src/api/forms.spec.ts:80-85
Conclusion
Forms handling in Cheerio provides a robust implementation of the jQuery form API, enabling developers to extract data from complex HTML structures efficiently. By adhering to standard browser serialization rules—such as ignoring disabled fields and normalizing line endings—it ensures that extracted data is consistent with how a real browser would submit a form. This makes it an essential tool for tasks involving web scraping and automated data extraction.