createWidget
Create reusable HTML/CSS/JS widgets to embed on pages or email templates via shortcodes, supporting bulk imports, migrations, or scripted generation with automatic cache refresh.
Instructions
Create a widget - Create a new widget (reusable HTML/CSS/JS component). Writes live data.
Cache refresh is automatic. Response includes auto_cache_refreshed: true after successful writes, or auto_cache_refresh: "scheduled" when the refresh is queued to run shortly together with other writes; both are normal and need no refreshSiteCache call. Only if auto_cache_refreshed: false, check auto_cache_refresh_error and retry refreshSiteCache once.
Use when: programmatically adding a new reusable block to embed as <div>[widget=Name]</div> on pages or email templates (a bare shortcode in a page editor is wrapped in <p> on the next admin save). Rare in practice - widgets are usually created via BD admin UI where the editor supports live preview. API creation is useful for bulk imports, cross-site migrations, or scripted widget generation.
Required: widget_name (should be unique per site).
widget_name format: alphanumeric + spaces + hyphens + plus + underscores only ([A-Za-z0-9 -+_]+). Special chars (slashes, dots, ampersands, quotes, brackets, etc.) break [widget=Name] shortcode resolution and are runtime-rejected by the wrapper. Examples: Mortgage Calculator, Service-Card, Email_Validator_v2, C++ Course.
Pre-check before create: BD does NOT enforce uniqueness on widget_name. Duplicates break [widget=Name] shortcode resolution - which widget renders at the shortcode is undefined. Do a server-side filter-find: listWidgets property=widget_name property_value=<proposed> property_operator==. Zero rows = name free; a site row = taken. An is_default true row is BD's own widget: creating its exact name replaces it on this site, only to customise it (e.g. a hero hook getDesignSettings names). Do NOT paginate unfiltered lists looking for the name - on sites with hundreds of custom widgets that burns rate limit for nothing.
On collision (auto-suffix flow): if the proposed name is taken, append -v2 and re-check. Still taken? Try -v3, -v4, ... up through -v10. First free suffix wins. Only if all 10 are taken, ask the user for a different base name. Never silently create a duplicate.
Route by type BEFORE writing values: decide what each piece of code is, then put it in the matching field — HTML → widget_data, CSS → widget_style, JS → widget_javascript. A self-contained block with all three concatenated into widget_data will save successfully but silently break: widget_data strips backslashes on render, mangling regex literals (\d, \s), string escapes (\n, \t), and unicode escapes (\u0022). The other two fields do not strip backslashes. Split by type from the start.
Common fields on create:
widget_data- the HTML contentwidget_style- CSS (scoped to the widget viawidget_classordiv_id)widget_javascript- JS (runs when widget is rendered on a page)widget_html_element- wrapper element (defaultdiv)
See also: updateWidget (modify existing), listWidgets (check if name is taken first), getWidget (verify storage after create).
Writes live data: the widget is available immediately but does nothing until referenced by a [widget=Name] shortcode on a page or email template.
Returns: { status: "success", message: {...createdRecord}, auto_cache_refreshed?: true|false, auto_cache_refresh?: "scheduled", auto_cache_refresh_error?: "..." } including the new widget_id.
Post-create verification (recommended, especially when uncertain about routing): call getWidget once to confirm widget_data contains only HTML, widget_style contains your CSS, and widget_javascript contains your JS wrapped in <script>...</script>. If anything landed in the wrong field, call updateWidget to relocate before the user tests the widget. Proactive relocation here is correct and does NOT violate the "don't relocate without user-reported breakage" rule on updateWidget — that rule applies to subsequent edits, not to self-correcting your own just-created record.
For the full field list, see listWidgets.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"widget_name": "<widget_name>"
},
"name": "createWidget"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| copy_of | No | widget_name of a widget to start from, BD's or this site's: the new widget gets its code, with your replace edits or whole fields applied. For a variant of an existing widget (other members, posts, order or count). | |
| replace | No | With copy_of: change part of the copied code: [{field, find, with}]. If find occurs more than once, add nth (1 = first) or all:true. | |
| own_form | No | true: the required being added belongs to this widget's own form, not the homepage hero search | |
| own_icons | No | true: an icon in the hero search that the search recipe cannot place (a field holding two inputs, such as a price range) | |
| widget_data | No | HTML only. No `<style>`, no `<script>` — 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. Put CSS in `widget_style`, JS in `widget_javascript`. See **Rule: Widget code fields**. | |
| widget_name | Yes | ||
| 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**. | |
| 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**. |