API Reference - Widget Placements

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

← Back to API Reference | Getting Started

Widget Placements

Widget Placements define where individual widgets appear within sidebars and page layouts on your directory site. Each record associates a widget with a sidebar or post type page, controls its display order, and tracks its active status.

Model name in URL: data_widgets_rel — DB table: data_widgets_rel

The Widget Placement Object

FieldTypeDescription
rel_idintegerUnique placement ID (primary key, read-only)
widget_idstringName or identifier of the widget being placed required on create
data_idstringID of the post type or page context where this widget appears required on create
page_typestringPage template type this placement applies to (EG profile, search); empty for all
activeintegerWhether this placement is active and the widget is rendered: 1 active, 0 inactive required on create
display_orderintegerSort order position of this widget within its sidebar; lower numbers appear first required on create
date_updatedstringDate this placement was last updated (format: YYYYMMDDHHMMSS)
updated_bystringUsername or identifier of the admin who last updated this placement
sidebar_idintegerID of the sidebar this widget is placed in; 0 if not sidebar-specific required on create
website_idintegerSite ID for multi-site contexts; 0 for the current site
revision_timestamptimestampTimestamp of the last modification to this record (auto-managed)

List Widget Placements

GET /api/v2/data_widgets_rel/get

Example Request

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

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "rel_id": "1112",
      "widget_id": "Bootstrap Theme - Module - Newsletter Sign Up Form",
      "data_id": "20",
      "page_type": "",
      "active": "1",
      "display_order": "2",
      "date_updated": "",
      "updated_by": "",
      "sidebar_id": "0",
      "website_id": "0",
      "revision_timestamp": "2017-02-14 18:24:37"
    },
    {
      "rel_id": "1111",
      "widget_id": "Bootstrap Theme - Banner - Responsive Size",
      "data_id": "20",
      "page_type": "",
      "active": "1",
      "display_order": "1",
      "date_updated": "",
      "updated_by": "",
      "sidebar_id": "0",
      "website_id": "0",
      "revision_timestamp": "2017-02-14 18:24:37"
    }
  ],
  "total": "245",
  "current_page": 1,
  "total_pages": 10,
  "next_page": "MipfKjI="
}

Retrieve a Widget Placement

GET /api/v2/data_widgets_rel/get/{rel_id}

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/data_widgets_rel/get/1112" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "rel_id": "1112",
      "widget_id": "Bootstrap Theme - Module - Newsletter Sign Up Form",
      "data_id": "20",
      "page_type": "",
      "active": "1",
      "display_order": "2",
      "date_updated": "",
      "updated_by": "",
      "sidebar_id": "0",
      "website_id": "0",
      "revision_timestamp": "2017-02-14 18:24:37"
    }
  ],
  "total": "1",
  "current_page": 1,
  "total_pages": 1
}

Create a Widget Placement

POST /api/v2/data_widgets_rel/create

Example Request

Copy
curl -X POST "https://www.yourdomain.com/api/v2/data_widgets_rel/create" \
  -H "X-Api-Key: your-api-key-here" \
  -d "widget_id=My+Custom+Widget" \
  -d "data_id=1" \
  -d "sidebar_id=3" \
  -d "active=1" \
  -d "display_order=5"

Example Response

Copy
{
  "status": "success",
  "message": {
    "rel_id": "1200",
    "widget_id": "My Custom Widget",
    "data_id": "1",
    "page_type": null,
    "active": "1",
    "display_order": "5",
    "date_updated": null,
    "updated_by": null,
    "sidebar_id": "3",
    "website_id": null,
    "revision_timestamp": null
  }
}

Update a Widget Placement

PUT /api/v2/data_widgets_rel/update

Example Request

Copy
curl -X PUT "https://www.yourdomain.com/api/v2/data_widgets_rel/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "rel_id=1200" \
  -d "display_order=2" \
  -d "active=0"

Example Response

Copy
{
  "status": "success",
  "message": {
    "rel_id": "1200",
    "widget_id": "My Custom Widget",
    "data_id": "1",
    "page_type": null,
    "active": "0",
    "display_order": "2",
    "date_updated": null,
    "updated_by": null,
    "sidebar_id": "3",
    "website_id": null,
    "revision_timestamp": "2026-04-03 10:00:00"
  }
}

Delete a Widget Placement

DELETE /api/v2/data_widgets_rel/delete

Example Request

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

Example Response

Copy
{
  "status": "success",
  "message": "data_widgets_rel record was deleted"
}