updateWidget
Edit an existing widget's HTML, CSS, JavaScript, or metadata by widget ID. Changes go live immediately with automatic cache refresh, so page and email shortcode references render updated content.
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_javascriptVisibility:
widget_viewport(front/admin/both)Framework:
bootstrap_enabled,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**. |