In prior lessons, we have demonstrated several venues for embedding widgets from various applications. However, there is a unique scenario in which the application interface can be accessed by clicking on a specially formatted hyperlink.
The app can post such links within the body of live feed posts and comments, within chat messages, within task descriptions, and elsewhere. Anywhere the link is clicked, the application's interface will be displayed.
Embedding as a link
6 min
To proceed, press the "New Application" button, and select the primary region for the publication of the solution, as you have done previously.
Within the solution form, click the "Create" button and choose the "Use REST API" type.
Activate the "Add Widgets" option, keeping in mind that this will include "Application Embedding" to the list of authorized scopes. Additionally, include the "Activity stream" scope as it will be necessary for the example.
Download the example provided with this lesson and upload it to your server in the same manner as described in the previous lessons on local integrations.
Enter the paths of the uploaded application in the version form, as previously demonstrated. Copy the values of the client_id and client_secret fields, and paste them into the respective constants in the settings.php file.
Accessibility from an external network
Take heed, it is crucial that the address of the example uploaded to the server is accessible from the external network. This means avoiding localhost and self-signed SSL certificates, amongst other restrictions. Verify the availability of your URL using third-party services, and do not solely rely on the fact that it opens successfully in your browser. Ensure your web server supports frame access, as without this capability, the widgets will not function.
Examine the example code, starting with install.php. Here, we invoke the installApp method, which we have previously encountered, and which will store the authorization tokens in a file for future use.
We will then immediately utilize these tokens in executing the placement.bind method, which only requires two parameters:
- PLACEMENT - The code for the widget placement, in this case a link placement.
- HANDLER - The hyperlink to the widget interface, which will open in the frame when clicked.
Return to the Developer area.
The present page affords you the opportunity to install the app onto your Bitrix24 platform and to evaluate its functionality prior to its release in the Bitrix24.Market.
Enter the address of your Bitrix24 account, where you hold administrative privileges, and press the "Install" button. This will redirect you to the portal and initiate the application installation process. Upon publication in the directory, complete with descriptive content and accompanying screenshots, the installation procedure will be further enhanced, but for now, it is imperative that we confirm the technical viability of the app. Once the installation is complete, Bitrix24 will automatically open the app due to its user interface.
In our scenario, for seamless integration, our app must add certain content to Bitrix24 that includes a link in the required format. Let us suppose that our application serves as an external document management system, but we desire for the documents stored therein to be accessible within the Bitrix24 interface, thereby facilitating discussions with coworkers, for instance.
Let us press the "Upload Documents" button. The app will then insert a live feed post, which includes three links to external documents. We shall confirm that clicking on each link opens a slider, displaying the widget, and that a different document opens each time.
Let us examine the implementation of this remarkable functionality through a straightforward embed.
We will begin by opening the index.php file. All the code can be traced back to a call to the log.blogpost.add method, which incorporates the post into the live feed. However, the most intriguing aspect lies in the way links are formulated within the text of the post.
A link will be considered as an inline widget if it encompasses the path "/marketplace/view/" and a symbolic application code. Furthermore, the link may possess the "Params" parameter, which constitutes an array with arbitrary keys. In this example, I chose to use the "Doc" key, specifying a particular conditional document identifier.
Where does the symbolic code of the app, specified in the $my_app_code variable, originate from?
Let us revisit the developer area and open the solution form. In the upper right corner, there exists an interface that permits you to retrieve or modify the symbolic code of the application. This code is primarily utilized in generating a link to the application in the Bitrix24.Market, as well as within Bitrix24 in the embed links.
We will now delve into the code of the placement.php embed handler, which is straightforward in nature. As our links were generated with the "Doc" parameter, we obtain the value of this parameter in the PLACEMENT_OPTIONS key of the REQUEST array.
The example encompasses three text files with names that align with the possible values of the doc parameter.
Once the slider containing the widget opens and a specific value is transmitted in the placement.php handler, we load and display the contents of the designated file.
In actual cases, we could access a third-party API, extract files from the database of the app, and much more.
The most crucial aspect in this scenario is that our application itself generates links with the appropriate parameters, and it also functions as a tool for visualizing the content of these links from the end-user's perspective.
Resources
Lesson materials:
- Example example25.zip
- SDK CRest visit
- REST API Guide read
- Developer's area visit
- Main embedding locations read