0
# Web Form Utilities
1

2
jQuery-based utilities for manipulating web forms and serializing form data to structured JSON objects. These utilities handle complex form structures including nested objects and arrays through bracket notation.
3

4
**Note:** This module requires jQuery to be available and is primarily designed for browser environments.
5

6
## Capabilities
7

8
### Form Serialization
9

10
Convert jQuery form elements to structured JSON objects with support for nested properties and arrays.
11

12
```javascript { .api }
13
/**
14
 * Serialize a form to a JSON object with nested property support
15
 * @param input - jQuery form element to serialize
16
 * @param sep - Property separator for nested objects (default: '.')
17
 * @param dict - Dictionary for field name replacement (name=replacement)
18
 * @returns Structured object representing the form data
19
 */
20
forge.form.serialize(input: jQuery, sep?: string, dict?: {[key: string]: string}): object;
21
```
22

23
**Usage Examples:**
24

25
```javascript
26
// Basic form serialization
27
const form = $('#myForm');
28
const data = forge.form.serialize(form);
29

30
// Custom separator for nested properties
31
const data = forge.form.serialize(form, '_');
32

33
// Field name replacement
34
const data = forge.form.serialize(form, '.', {
35
  'oldFieldName': 'newFieldName',
36
  'user_id': 'userId'
37
});
38
```
39

40
## Supported Form Structures
41

42
### Simple Fields
43

44
Regular input fields are serialized as simple key-value pairs:
45

46
```html
47
<input name="username" value="john">
48
<input name="email" value="john@example.com">
49
```
50

51
Results in:
52
```javascript
53
{
54
  username: "john",
55
  email: "john@example.com"
56
}
57
```
58

59
### Nested Objects
60

61
Use dot notation or custom separators to create nested objects:
62

63
```html
64
<input name="user.name" value="john">
65
<input name="user.profile.age" value="30">
66
<input name="settings.theme" value="dark">
67
```
68

69
Results in:
70
```javascript
71
{
72
  user: {
73
    name: "john",
74
    profile: {
75
      age: "30"
76
    }
77
  },
78
  settings: {
79
    theme: "dark"
80
  }
81
}
82
```
83

84
### Arrays
85

86
Use square bracket notation to create arrays:
87

88
```html
89
<input name="tags[]" value="javascript">
90
<input name="tags[]" value="crypto">
91
<input name="tags[]" value="security">
92
```
93

94
Results in:
95
```javascript
96
{
97
  tags: ["javascript", "crypto", "security"]
98
}
99
```
100

101
### Indexed Arrays
102

103
Specify array indices explicitly:
104

105
```html
106
<input name="users[0].name" value="alice">
107
<input name="users[0].role" value="admin">
108
<input name="users[1].name" value="bob">
109
<input name="users[1].role" value="user">
110
```
111

112
Results in:
113
```javascript
114
{
115
  users: [
116
    { name: "alice", role: "admin" },
117
    { name: "bob", role: "user" }
118
  ]
119
}
120
```
121

122
### Complex Mixed Structures
123

124
Combine objects, arrays, and simple fields:
125

126
```html
127
<input name="title" value="My Form">
128
<input name="metadata.version" value="1.0">
129
<input name="metadata.tags[]" value="form">
130
<input name="metadata.tags[]" value="utility">
131
<input name="sections[0].title" value="Personal Info">
132
<input name="sections[0].fields[]" value="name">
133
<input name="sections[0].fields[]" value="email">
134
<input name="sections[1].title" value="Preferences">
135
<input name="sections[1].fields[]" value="theme">
136
```
137

138
Results in:
139
```javascript
140
{
141
  title: "My Form",
142
  metadata: {
143
    version: "1.0",
144
    tags: ["form", "utility"]
145
  },
146
  sections: [
147
    {
148
      title: "Personal Info",
149
      fields: ["name", "email"]
150
    },
151
    {
152
      title: "Preferences", 
153
      fields: ["theme"]
154
    }
155
  ]
156
}
157
```
158

159
## Field Name Processing
160

161
### Bracket Parsing
162

163
The utility parses bracket notation to determine structure:
164
- `field[]` - Append to array
165
- `field[index]` - Set specific array index  
166
- `field[key]` - Set object property
167
- `field[key][subkey]` - Nested object properties
168

169
### Name Replacement Dictionary
170

171
Use the `dict` parameter to rename fields during serialization:
172

173
```javascript
174
const form = $('#registrationForm');
175
const data = forge.form.serialize(form, '.', {
176
  'user_name': 'username',
177
  'user_email': 'email',
178
  'pwd': 'password'
179
});
180

181
// Input field named 'user_name' becomes 'username' in output
182
// Input field named 'pwd' becomes 'password' in output
183
```
184

185
## Integration Example
186

187
```javascript
188
// Complete form processing example
189
$(document).ready(function() {
190
  $('#submitBtn').click(function() {
191
    const formData = forge.form.serialize($('#userForm'), '.', {
192
      'user_id': 'userId',
193
      'created_at': 'createdAt'
194
    });
195
    
196
    // Send structured data to server
197
    $.ajax({
198
      url: '/api/users',
199
      method: 'POST',
200
      contentType: 'application/json',
201
      data: JSON.stringify(formData),
202
      success: function(response) {
203
        console.log('User created:', response);
204
      }
205
    });
206
  });
207
});
208
```
209

210
## Browser Compatibility
211

212
This module depends on jQuery and is designed for browser environments. It uses jQuery's `serializeArray()` method internally and requires:
213

214
- jQuery library available globally
215
- Modern browser with DOM support
216
- Form elements with proper `name` attributes