ray
102 lines
4.4 KiB
Markdown
102 lines
4.4 KiB
Markdown
# Adding a New Site Configuration Setting
|
||
|
||
When adding a single new setting to the Site Configuration modal, you MUST update **6 places** across
|
||
the codebase. Missing any one will cause silent failures.
|
||
|
||
## Checklist (ordered, follow exactly)
|
||
|
||
### 1. `settings.js` — Add default value
|
||
```javascript
|
||
// In the `let appSettings = { ... }` block (~line 8)
|
||
notifyBeforePromised: 0, // 0 = off, 15/30/60 = minutes before promised time
|
||
```
|
||
|
||
### 2. `settings.js` — Populate form on load (`populateSiteSettingsForm`)
|
||
```javascript
|
||
// ~line 244
|
||
setValue('notify-before-promised', appSettings.notifyBeforePromised, 0);
|
||
```
|
||
Use `setChecked()` for checkboxes/toggles, `setValue()` for selects/inputs.
|
||
|
||
### 3. `settings.js` — Save handler (`setupUnifiedSiteSettingsModalHandlers`) ×2
|
||
There are TWO save handlers that must both read the new field:
|
||
```javascript
|
||
// ~line 277 (inside setupUnifiedSiteSettingsModalHandlers)
|
||
appSettings.notifyBeforePromised = parseInt(document.getElementById('notify-before-promised')?.value ?? '0');
|
||
|
||
// ~line 1008 (window.saveSiteSettings bridge — repair-orders inline onclick)
|
||
appSettings.notifyBeforePromised = parseInt(document.getElementById('notify-before-promised')?.value ?? '0');
|
||
```
|
||
Use `replace_all=true` when patching since the two blocks are identical.
|
||
|
||
### 4. `settings.js` — Auto-save binding (`attachSiteSettingsAutoSave`)
|
||
```javascript
|
||
// ~line 559
|
||
bind('notify-before-promised', 'change', (el) => appSettings.notifyBeforePromised = parseInt(el.value || '0'));
|
||
```
|
||
Use `'change'` for selects, `'change'` for checkboxes.
|
||
|
||
### 5. `settings.js` — Realtime sync (`subscribeToRealtimeSettings`)
|
||
```javascript
|
||
// ~line 677
|
||
setIfSafe('notify-before-promised', String(appSettings.notifyBeforePromised ?? 0));
|
||
```
|
||
Use `String()` for value fields, `!!` + `'checked'` for checkbox fields.
|
||
|
||
### 6. ALL FOUR HTML pages — Add the form control
|
||
- `repair-orders.html` — inside `#site-settings-modal` → Notifications card
|
||
- `appointments.html` — inside `#site-settings-modal` → Notifications card
|
||
- `customers.html` — inside `#site-settings-modal` → Notifications card
|
||
- `index.html` — inside `#site-settings-modal` → Notifications card
|
||
|
||
All four pages need the identical HTML block. Find the `Critical Alerts` toggle section
|
||
and add the new control right after it, before the closing `</div>` of the Notifications card.
|
||
|
||
Template for a select dropdown:
|
||
```html
|
||
<div>
|
||
<label class="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">Setting Label</label>
|
||
<p class="text-xs text-gray-500 dark:text-gray-400 mb-2">Help text explaining the setting</p>
|
||
<select id="setting-id" class="w-full p-3 border border-gray-300 dark:border-gray-600 rounded-lg bg-white dark:bg-gray-800 focus:ring-2 focus:ring-purple-500 focus:outline-none">
|
||
<option value="0">Off</option>
|
||
<option value="15">15 minutes before</option>
|
||
<option value="30">30 minutes before</option>
|
||
<option value="60">1 hour before</option>
|
||
</select>
|
||
</div>
|
||
```
|
||
|
||
Template for a toggle switch:
|
||
```html
|
||
<div class="flex items-center justify-between">
|
||
<div>
|
||
<label class="text-sm font-medium text-gray-700 dark:text-gray-300">Toggle Label</label>
|
||
<p class="text-xs text-gray-500 dark:text-gray-400">Help text</p>
|
||
</div>
|
||
<label class="toggle-switch">
|
||
<input type="checkbox" id="toggle-id">
|
||
<span class="slider"></span>
|
||
</label>
|
||
</div>
|
||
```
|
||
|
||
## Verification
|
||
|
||
After all changes, verify with curl:
|
||
```bash
|
||
# settings.js should have 6 references (default, populate, save×2, auto-save, realtime)
|
||
curl -sk https://localhost/settings.js | grep -c 'newFieldName'
|
||
|
||
# Each page should have exactly 1 reference (the element)
|
||
for page in repair-orders.html appointments.html customers.html index.html; do
|
||
echo "$page: $(curl -sk https://localhost/$page | grep -c 'element-id')"
|
||
done
|
||
```
|
||
|
||
## Common mistakes
|
||
|
||
- **Forgetting the second save handler**: `window.saveSiteSettings` (the bridge at file end) is a DUPLICATE of the handler inside `setupUnifiedSiteSettingsModalHandlers`. Both must read the new field.
|
||
- **Missing a page**: All 4 pages use the same `settings.js` backend, so the form control must exist on all 4 or `getElementById` returns null.
|
||
- **Wrong `bind` event type**: Use `'change'` for selects and checkboxes, not `'input'`.
|
||
- **HTML ID mismatch**: The `id` attribute in HTML must exactly match the `document.getElementById()` call in JS.
|