The optimal method to extend the capabilities of your application to users is to embed it as a widget in the relevant area of Bitrix24, such as the form of a CRM entity or a task list, for instance.
The REST API offers a mechanism for this, which is outlined in the "Application Embedding" section of the documentation.
Application with widgets
5 min
ЗTo initiate the process, we must press the "New Application" button and choose the principal region for the solution's eventual publication.
Then, we click the "Create" button in the application form and specify the "Use REST API" type, enabling the "Add Widgets" option, which adds "Application Embedding" to the list of permitted scopes.
We must then download the example provided with the tutorial, upload it to a server, and insert the server paths into the version form.
We must also copy the client_id and client_secret values into the settings.php file.
Accessibility from an external network
It is imperative that the uploaded example's URL is publicly accessible, without localhost or self-signed SSL certificates, and that the web server supports access from frames, as this is necessary for the proper functioning of widgets.
Examining the example code, starting with install.php, we find the familiar installApp method, which stores the authorization tokens for later use and immediately employs these tokens to execute the placement.bind method.
This method requires three parameters:
- The PLACEMENT parameter indicates the location of the widget, for instance, the left menu,
- The HANDLER parameter specifies the link to the widget interface,
- the TITLE parameter provides the name of the widget, which in this case serves as the name of the menu item.
Useful
Given that Bitrix24 supports multiple languages and individual users can select their preferred language, it is possible to specify different names for widgets in various languages. Further information on this can be found in the placement.bind method documentation.
Next, we proceed to the developer area, where we can install the application in Bitrix24 for testing purposes before publishing it in Bitrix24.Market.
We specify the address of our Bitrix24 portal, where we hold administrative privileges, and click "Install." This redirects us to the portal and opens the application installation interface. When the application is published in Bitrix24.Market, with descriptions and screenshots included, the installation process will appear more impressive, but for now, we need to ensure its technical functionality. Bitrix24 will automatically open the application after installation is complete, as it has a user interface.
We can confirm that two items have appeared in the left menu: one bearing the name taken from the English application description, which opens a slider with the main application interface when clicked, and the second item, the result of the widget installation, which opens the slider with placement.php.
Both the widget's user interface and the main application URL receive a POST request from Bitrix24 containing the portal data, authorization tokens, and context.
In this example, the contents of the REQUEST array are displayed to demonstrate the differences in the PLACEMENT parameter value; PLACEMENT is DEFAULT on the main application page and LEFT_MENU in the left menu embed widget.
Similarly, the PLACEMENT value will vary for different embed locations, with the PLACEMENT_OPTIONS parameter providing supplementary information, such as the ID of the current deal if the widget is embedded in a deal form, for instance.
There are manifold possible points of integration for widgets within Bitrix24. Hence, in the ensuing lessons, we shall elaborate on the most common forms of embedment.
Resources
Lesson materials:
- Example example21.zip
- SDK CRest visit
- REST API Guide read
- Developer's area visit
- Main embedding locations read