updateWidget
Modify an existing widget by widget_id, changing only supplied fields such as HTML, CSS, JS, or metadata. Changes go live immediately and cache refresh is automatic.
Instructions
Update a widget - Update an existing widget by widget_id. Fields omitted are untouched. Writes live data.
Cache refresh is automatic. Response includes auto_cache_refreshed: true after successful writes; no manual refreshSiteCache call needed. If auto_cache_refreshed: false, check auto_cache_refresh_error and retry refreshSiteCache once.
Use when: editing widget HTML (widget_data), CSS (widget_style), JS (widget_javascript), or metadata. Any page or email referencing this widget via [widget=Name] shortcode will render the updated content on next view.
Required: widget_id.
Common edits:
Content:
widget_data,widget_style,widget_javascriptFramework:
mobile_enabled,ssl_enabled
Renaming via widget_name: DO NOT pass widget_name unless the user explicitly asks to rename the widget. Renaming a widget breaks every [widget=Name] shortcode reference to its old name on every page/email — silently. If the user does ask: same format rules as create ([A-Za-z0-9 -+_]+, runtime-rejected on bad chars); on collision follow the auto-suffix flow (-v2, -v3, ... up to -v10).
See also: createWidget (add new), deleteWidget (remove).
Writes live data: edits go live immediately for new page loads.
Returns: { status: "success", message: {...updatedRecord}, auto_cache_refreshed: true|false, auto_cache_refresh_error?: "..." }.
For the full field list, see listWidgets.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| widget_id | Yes | ||
| widget_data | No | HTML. Render strips backslashes here (`\d`→`d`, `\n`→`n`, `\t`→`t`, `\\`→`\`). JS with stripped escapes throws SyntaxError on parse — every handler unbound, widget renders but no clicks/inputs work. Fix: relocate to `widget_javascript`, do not rewrite JS to avoid backslashes. Never relocate existing `<style>`/`<script>` blocks here — only on user-reported breakage. New content: route by type (CSS→`widget_style`, JS→`widget_javascript`). See **Rule: Widget code fields**. | |
| widget_name | No | ||
| widget_style | No | Raw CSS. No `<style>` wrapper — BD wraps at render. Wholly-wrapped value: outer wrapper stripped on storage; concatenated wrappers not stripped. See **Rule: Widget code fields**. | |
| _clear_fields | No | Column names to clear to empty string. Available on every `update*` operation. Works on base columns AND EAV/`users_meta` rows (rows preserved with `value=""`). To actually clear a field you MUST use this parameter — sending the field with `""` alone is a no-op (BD drops empty values). To remove a `users_meta` row entirely, use `deleteUserMeta`. See **Rule: Clearing fields**. Example: `_clear_fields: ["h2", "hero_link_url"]`. | |
| widget_javascript | No | JS with `<script>...</script>` wrapper required. BD does not auto-wrap; unwrapped content renders as inert text. No backslash-strip on this field — regex literals (`\d`, `\w`, `\s`) AND string escapes (`\n`, `\t`, `\\`) survive intact. See **Rule: Widget code fields**. |