API Reference - Widgets

Link: https://support.brilliantdirectories.com/support/solutions/articles/12000108056

← Back to API Reference | Getting Started

Widgets

Widgets are reusable HTML/CSS/JS components that power the front-end of your Brilliant Directories website. They can be created, modified, and rendered via the API.

Model name in URL: data_widgets — DB table: data_widgets
Default values & admin-level visibility: /get responses merge platform Default values (an uncustomized record is returned from the platform Defaults with is_default: true) and, based on the admin account that created the API key, honor the same visibility rules as the View Widgets page (/admin/formViewWidgets.php): widgets whose widget_name is on the admin/Add-On blacklist return a 403 permission error, and forbidden records are silently filtered out of list responses. See Getting Started for details.
Legacy widgets are not returned: the Default widgets merged into a /get list response are limited to those supported by the current version of the software. Widgets that belong only to legacy versions are left out. A widget that supports the current version alongside older ones is still returned, because the check asks whether the current version is among the versions listed in bootstrap_enabled, not whether it is the only one. Widgets customized on the website are returned regardless of the versions they list, and retrieving a single widget by ID is not filtered.

The Widget Object

FieldTypeDescription
widget_idintegerUnique widget ID (primary key, read-only)
widget_namestringWidget name/label required on create
widget_typestringWidget type (default: Widget)
widget_datatextWidget HTML content
widget_styletextWidget CSS styles
widget_javascripttextWidget JavaScript code
widget_settingstextWidget configuration settings (JSON or serialized)
widget_valuestextWidget variable values
widget_classstringCSS class names to apply to the widget container
widget_viewportstringWhere the widget appears: front (public pages), admin (admin panel) or all (both)
widget_html_elementstringHTML element type wrapping the widget (default: div)
div_idstringHTML ID attribute for the widget container
short_codestringShortcode reference for this widget
bootstrap_enabledstringThe software version the widget supports. A widget customized on the website holds a single version number, 4 on current websites; a list sent in an update is saved as its first number. Default widgets can list several versions, comma-separated (4,3). This is the value the Widget Manager's Software Version filter reads. It is not a true or false flag.
ssl_enabledinteger1 if SSL/HTTPS is enabled for this widget
mobile_enabledinteger1 if mobile viewport is enabled
file_typestringFile type of the widget
date_updatedstringDate widget was last updated
updated_bystringUser who last updated this widget
revision_timestamptimestampLast modified timestamp (auto-updated)
customizestringVirtual field for widget customization context
fromcronstringVirtual field indicating cron execution context

List Widgets

GET /api/v2/data_widgets/get
Copy
curl -X GET "https://www.yourdomain.com/api/v2/data_widgets/get?limit=25" \
  -H "X-Api-Key: your-api-key-here"

Retrieve a Widget

GET /api/v2/data_widgets/get/{widget_id}
Copy
curl -X GET "https://www.yourdomain.com/api/v2/data_widgets/get/500" \
  -H "X-Api-Key: your-api-key-here"

Create a Widget

POST /api/v2/data_widgets/create
Copy
curl -X POST "https://www.yourdomain.com/api/v2/data_widgets/create" \
  -H "X-Api-Key: your-api-key-here" \
  -d "widget_name=My+Custom+Banner" \
  -d "widget_data=%3Ch2%3EWelcome%21%3C%2Fh2%3E"
A new widget is always saved with widget_viewport set to front and bootstrap_enabled set to 4, whatever values the request sends. To show the widget in the admin panel or everywhere, change widget_viewport with an update.

Update a Widget

PUT /api/v2/data_widgets/update
Copy
curl -X PUT "https://www.yourdomain.com/api/v2/data_widgets/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "widget_id=500" \
  -d "widget_name=Updated+Banner" \
  -d "widget_data=%3Ch2%3ENew+Content%21%3C%2Fh2%3E"

Delete a Widget

DELETE /api/v2/data_widgets/delete
Copy
curl -X DELETE "https://www.yourdomain.com/api/v2/data_widgets/delete" \
  -H "X-Api-Key: your-api-key-here" \
  -d "widget_id=500"

Render a Widget

POST /api/v2/data_widgets/render

Returns the rendered HTML output of a widget, with all template variables processed. Useful for previewing widget output or embedding rendered content in external applications.

Example Request

Copy
curl -X POST "https://www.yourdomain.com/api/v2/data_widgets/render" \
  -H "X-Api-Key: your-api-key-here" \
  -d "widget_id=500"

Example Response

Copy
{
  "status": "success",
  "message": "Widget rendered successfully",
  "name": "My Widget Name",
  "output": "<h2>Welcome!</h2>"
}

A success response means the widget's code ran without a PHP error.

Error Response

When the widget's PHP code fails, the call returns HTTP 400 with status set to error. The message names the widget, the PHP error and the line of the widget's code where it happened, in the form Widget error in '<widget name>': <PHP error> on line <n>, and line holds the line number on its own. name and output are still returned, and output holds whatever the widget printed before the error. Fatal errors and a widget that stops the request (EG with exit()) are reported the same way; when no line is known, line is 0 and the message has no line number.

Copy
{
  "status": "error",
  "message": "Widget error in 'My Widget Name': Call to undefined function my_helper() on line 4",
  "name": "My Widget Name",
  "output": "<h2>Welcome!</h2>\n<!-- Widget error: My Widget Name -->",
  "line": 4
}