Widgets in Workgroups and Projects: Overview of Placements

Placements add the application interface inside a workgroup or project: an item in the group menu, an item in the extensions menu, or a button in the automation rules designer.

All three placements of the section work in the context of a single group and require the sonet_group scope. A project is a group with extended capabilities, so the placements are displayed both in groups and in projects.

To register a widget, use the placement.bind method and pass the required code in the PLACEMENT parameter.

Quick navigation: all placements

How to Choose a PlacementHow to Choose a Placement

Choose a placement by the task your application solves:

• add a separate screen with application data to a group — SONET_GROUP_DETAIL_TAB
• add an item to the extensions menu of a group — SONET_GROUP_TOOLBAR
• extend the automation of group tasks — SONET_GROUP_ROBOT_DESIGNER_TOOLBAR

The rendering location depends on the interface version. The classic view currently runs in most Bitrix24 accounts, while the new Projects AI view is being rolled out gradually. Projects AI has no extensions menu, so the SONET_GROUP_TOOLBAR item will not appear there. If your application needs an item in the group in both interface versions, use SONET_GROUP_DETAIL_TAB.

How to Get StartedHow to Get Started

1. Choose a placement for your scenario.
2. Register the handler with the placement.bind method and pass the code in the PLACEMENT parameter. The method is available to an administrator only and requires the application context: a placement cannot be bound with a webhook.
3. Complete the application installation. Until then, the widget is not displayed in the interface.
4. Open the workgroup and call the widget. Where exactly the item is located is described on each placement page in the "Where to Find It in the Interface" section.
5. Parse PLACEMENT_OPTIONS in the handler — it carries the call context: the workgroup identifier or the address of the page the widget was opened from.

What the Handler ReceivesWhat the Handler Receives

All placements of the section pass the same set of standard parameters to the handler.

Parameters in the Handler URL Query String

Parameters in the POST Request Body

Bitrix24 adds a URI key to PLACEMENT_OPTIONS — the path with the query string of the page from which the widget was opened. It arrives for any placement, along with the keys of that placement itself. The key is absent if the browser did not send the Referer header or if the widget was opened from a page on a different domain.

How to Parse the Call Context

PLACEMENT_OPTIONS arrives as a JSON string, not as an array: parse it on the handler side before use. The set of keys is specific to each placement and is described in the PLACEMENT_OPTIONS section of this page.

$placement = $_POST['PLACEMENT'] ?? '';
        $options = json_decode($_POST['PLACEMENT_OPTIONS'] ?? '{}', true);
        

options = json.loads(request.form.get("PLACEMENT_OPTIONS", "{}") or "{}")
        

In B24JsSDK, there is no need to parse the string: the $b24.placement.options property returns a ready object, and $b24.placement.placement returns the placement code.

What the Handler Must Return

The handler responds with a regular HTML page — Bitrix24 displays it in a frame in place of the widget. The page must allow embedding: if the application server sends the X-Frame-Options or Content-Security-Policy headers that prohibit framing, an empty area remains in place of the widget. How to fix it is described in the article Site Does Not Allow Connection.

PLACEMENT_OPTIONSPLACEMENT_OPTIONS

The PLACEMENT_OPTIONS value is passed as a JSON string with the call context. The universal URI key arrives for every placement, while the set of the remaining keys is specific to each placement.

Connection with Other ObjectsConnection with Other Objects

Workgroup. The GROUP_ID identifier indicates which group the handler was called for. Workgroup data is returned by the sonet_group.get method.

Group tasks. The SONET_GROUP_ROBOT_DESIGNER_TOOLBAR placement is called from the task automation settings. Data of the tasks themselves is returned by the methods of the tasks section.

Call page. The universal URI key contains the path of the Bitrix24 page the widget was opened from. For SONET_GROUP_TOOLBAR it is the only source of the group identifier: in the path /workgroups/group/10/tasks/ the identifier is 10.

Common MistakesCommon Mistakes

Overview of PlacementsOverview of Placements

Scope: placement, sonet_group

Continue LearningContinue Learning

• Register a Widget Handler placement.bind
• Get Placements Available to the Application placement.list
• Delete a Widget Handler placement.unbind
• Interaction with UI: Overview of Methods
• Methods of BX24 SDK for Widgets
• Interactivity in Applications: Overview of Scenarios and Methods