Skip to content

Commit a1e4cff

Browse files
troyhackstroyhacks
committed
Updated example usermod readme with new updates.
1 parent 9ae7958 commit a1e4cff

1 file changed

Lines changed: 23 additions & 26 deletions

File tree

‎usermods/usermod_v2_example/README.md‎

Lines changed: 23 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Example Usermod - Settings Page Demo
22

3-
This is a minimal example demonstrating the auto-discovery settings page system for WLED usermods.
3+
A minimal example demonstrating the auto-discovery settings page system for WLED usermods.
44

55
## Files
66

@@ -21,6 +21,8 @@ The build system (`tools/cdata.js`) automatically:
2121
- Generates `wled00/html_usermod_settings_registry.h`
2222
- Serves pages at `/settings_<name>` URLs
2323

24+
If a usermod has `CONFIG_FIELDS` declared but no settings page, a skeleton is auto-generated at build time.
25+
2426
### 2. Config Fields with Defaults Declaration
2527

2628
In your usermod header, add a `CONFIG_FIELDS` comment with field names and default values:
@@ -50,7 +52,6 @@ private:
5052
char myColor[32] = "#ff0000";
5153
uint16_t mySpeed = 100;
5254

53-
// String constants matching CONFIG_FIELDS
5455
static const char _name[];
5556
static const char _enabled[];
5657
static const char _debugMode[];
@@ -94,32 +95,27 @@ inline const char ExampleUsermod::_mySpeed[] PROGMEM = "mySpeed";
9495
<html>
9596
<head><title>Example Usermod Settings</title></head>
9697
<body>
97-
<div id="error-msg"></div>
98-
<div id="saved-msg"></div>
99-
100-
<input type='checkbox' name='enabled'>
101-
<input type='checkbox' name='debugMode'>
102-
<input type='color' name='myColor' value='#ff0000'>
103-
<input type='number' name='mySpeed' value='100'>
104-
105-
<button id='save-btn'>Save</button>
106-
98+
<form>
99+
<input type='checkbox' name='enabled'>
100+
<input type='checkbox' name='debugMode'>
101+
<input type='color' name='myColor' value='#ff0000'>
102+
<input type='number' name='mySpeed' value='100'>
103+
<button type="submit">Save</button>
104+
</form>
107105
<script src="/settings-core.js"></script>
108-
<script>
109-
umCfg.initPage('Example', { saveButton: '#save-btn' });
110-
</script>
106+
<script>umCfg.initPage('Example');</script>
111107
</body>
112108
</html>
113109
```
114110

115-
**Note:** Fields are auto-discovered from form elements — no need to list them explicitly!
116-
117-
The `initPage()` helper:
118-
1. Fetches defaults from C++ (via `/json/usermod-fields`)
119-
2. Loads config from `cfg.json`
120-
3. Merges with defaults
121-
4. Populates all form elements
122-
5. Wires up the save button
111+
**That's it.** `umCfg.initPage()` handles everything:
112+
- Auto-discovers all form fields by `name` attribute
113+
- Auto-finds the submit button
114+
- Auto-inserts status elements (error/success messages) if missing
115+
- Fetches defaults from C++ via `/json/usermod-fields`
116+
- Loads config from `cfg.json`
117+
- Merges with defaults and populates form
118+
- Wires up the save button
123119

124120
### 5. Registering the Usermod
125121

@@ -142,9 +138,9 @@ void registerUsermods() {
142138

143139
3. **No duplication**: Field definitions live in `CONFIG_FIELDS` (C++), not duplicated in HTML/JS.
144140

145-
4. **Defaults from C++**: The `CONFIG_FIELDS` comment includes default values. These are parsed at build time and served via `/json/usermod-fields`.
141+
4. **Defaults from C++**: The `CONFIG_FIELDS` comment includes default values. Parsed at build time and served via `/json/usermod-fields`.
146142

147-
5. **Validation**: If the loaded config is missing expected fields, a warning is shown.
143+
5. **Auto-discovery**: Form fields, submit button, and status elements are all auto-discovered — no explicit configuration needed.
148144

149145
## umCfg Helper API
150146

@@ -157,7 +153,8 @@ void registerUsermods() {
157153
| `await umCfg.getDefaults(umName)` | Get default values from C++ |
158154
| `await umCfg.validate(umName, config)` | Returns missing field names |
159155
| `umCfg.withDefaults(config, defaults)` | Apply defaults to loaded config |
160-
| `umCfg.initPage(umName, fields, options)` | Initialize page with minimal code |
156+
| `umCfg.initPage(umName)` | Initialize page — fully auto-discovered |
157+
| `umCfg.initPage(umName, options)` | With options (saveButton, etc.) |
161158
| `umCfg.showError(msg)` | Show error message |
162159
| `umCfg.showSuccess(msg)` | Show success message (auto-hides) |
163160
| `umCfg.hideMessages()` | Hide error/success messages |

0 commit comments

Comments
 (0)