Skip to main content

Generating embeddable Help widgets from a Drupal 8 site

Senior Front-End Developer
Jun 09, 2016

When a problem arises in today’s attention deprived world, we can’t expect our customers to go search for a solution in the documentation. Documentation sites can be complex, they often store the documentation for multiple products and each of the products might have many features. In the best case you will frustrate your customer, in the worst case they might simply give up before finding the information they need.

That is why we developed the Walkhub Help Widget to help site owners guide their visitors to the right documentation content - right inside an application or web site. The simplest way to try out WalkHub Help Widgets is embedthedocs.com, but you can also set up your own widget creation interface easily if you have basic knowledge of web development. In this blogpost, we will guide you through the steps you need to take to replicate the functionality of EmbedTheDocs using Drupal as a content store.

EmbedTheDocs, the free UI for creating Help Widgets

In April we launched EmbedTheDocs.com, a service that lets you create an embeddable Help Widget. Our goal was to make it so simple that you should be able to create one under 2 minutes. Our widget allows users to list a series of online help content (such as technical documentation, articles, blog posts, videos, walkthroughs… anything linkable) relevant to a user’s context, that will open in the same browser window in a separate iframe. Once created on embedthedocs.com, the widget can be placed on any site via its unique embedcode. Anyone can freely try it out on our site after a quick registration.

Step-by-step tutorial: generating widgets from your own Drupal site

EmbedTheDocs is sufficient if you only need to create a few Help Widgets. In case you need something more complex, you want to have your own interface, add custom functionality to your widgets, or generate the content for the widget automatically in reaction to the user’s context, this article is for you.

As the EmbedTheDocs site is written on top of Drupal 8 CMS, it is possible to replicate the widget creation feature on other Drupal 8 sites, too. In this section, you will be guided through the process of replicating the widget creation feature, as on embedthedocs.com.

The following steps can be implemented either on an existing Drupal 8 site, or on a newly installed instance. If you don’t have a Drupal 8 site yet, you can install Drupal 8 on your localhost or a dedicated server (we recommend to test the features first on a local server) by following the standard Drupal installation instructions.

I. Setting up the widget elements with Paragraphs

The WalkHub Help Widget contains 3 different types of elements: groups, links and walkthroughs. Groups can be used as dividers for links and walkthroughs, but it’s not obligatory to add one. Links can target any content on the web. The YouTube video links will receive a YouTube icon in the widget and the video goes full screen when you click on its title. The third element is the WalkHub walkthrough, which can be added to the widget using its unique URL after you created one on next.walkhub.net. It’s free to add as many walkthroughs as you want on this site. Also, as WalkHub is open-source, you can fork or download it from GitHub.

Paragraphs module is a very powerful implementation of Drupal’s entity system. With the pre-defined paragraph types it is easy to compose content (e.g landing pages). So you could create other types of paragraphs that let you add different elements to your widgets (e.g. a video paragraph, with a proprietary video not hosted on Youtube).

Example widget with groups, links and walkthroughs
  1. Install the Paragraphs module with its dependencies (if you have Drush, use drush en paragraphs), go to /admin/structure/paragraphs_type and click on Add paragraph type. Type “Group” in the label field, then click on Save and manage fields.
Group paragraph type
  • Add a new plain text field with the label “Group name”. Then save the settings of the paragraph type.
  • Group name field in group paragraph type
  • Navigate back to /admin/structure/paragraphs_type where you can now see your first paragraph type listed.
  • Paragraph type list with group
  • Next create the second paragraph type. This paragraph’s label should be “Link” and will contain 3 fields: description (plain text), link (link) and title (plain text), the last two fields have to be required. The field list of the link paragraph type should look like this:
  • Field list of link paragraph type
  • The last paragraph type’s label is “Walkthrough” with one “Walkthrough link” field (link), which has to be set as required.
  • Field list of walkthrough paragraph type
  • Now you have all three necessary paragraph types: Group, Link, Walkthrough.
  • Paragraph type list

    Important! When adding the paragraph types and their fields, the machine names play key roles. The system will only work properly if you use the correct machine names for the paragraph types and fields.

    II. Creating the Widget content type

    1. Go to /admin/structure/types and click Add content type. The new content type’s name should be “Widget” (the other settings can remain in the default state).
    Add widget content type
  • Delete the automatically added “Body” field, and add a new one of the Paragraph type and label it “Widget elements”. The allowed number has to be unlimited so that users can add as many help items to a widget as they want to.
  • Widget content type settings
  • No other fields are needed for the widget creation, so let’s add a new node of this content type. Go to node/add/widget and feel free to add as many Widget elements as you want. The result should look like the following:
  • New widget node

    III. Making the widget come alive

    If you followed the steps in chapters I and II, you should now have a widget content type with one multiple value field for the three paragraph types. In the third chapter of this tutorial we install a complementary module for adding the content processing feature.

    1. Install the auxiliary module from https://www.drupal.org/sandbox/kittiradovics/2738613 into /module folder or in any subfolder of /module. Get more info on installing sandbox projects.
    2. Enable the Help Widget data processor module via /admin/modules, then go back to your previously created test widget node.
      This module’s first main function is to transform the paragraph elements’ content to a special JSON format, which can be processed by the WalkHub server in order to generate the widget iframe from the widget node.
      The Help Widgets are generated with the assistance of WalkHub, a microservice written in GO and React.js. The Drupal 8 site generates the resource in JSON, then WalkHub processes and displays it. For more information on the relationship, check our previous blogpost on EmbedTheDocs. You can also set up your own WalkHub server so that you can create walkthroughs on a system you control. This also lets you use your own server to display the widget iframe instead of ours.
    3. The content’s URL looks like /node/{nid} (replacing {nid} with the content’s id). If you modify this url to /json/{nid}, you will get the raw JSON formatted output of the test widget content (processable by the WalkHub server). The JSON output of the example is the following:
    JSON output of widget node
    The output is generated by helpwidget_data_processor/src/Controller/JSONOutputController.php. This file fetches the paragraph elements and their fields and pushes the text contents in an array. Then the JSON formatted output is generated by the JsonResponse class. The path for the text is defined in helpwidget_data_processor/helpwidget_data_processor.routing.yml file.
  • In order to get the WalkHub server to process the JSON formatted output and render the widget, an embed code is needed. Go to admin/structure/block, scroll down to the Content region and click on the Place block button, choose Generated embed code block. You can use the default settings.
  • Place Generate embed code block
    The block is created by helpwidget_data_processor/src/Plugin/Block/EmbedCodeBlock.php, which composes the embeddable code and also inserts it into the page’s source code so that the user can see the result after every modification in the bottom right corner of the widget node.
  • The WalkHub server uses CORS headers when receiving the JSON formatted output. Drupal has an excellent module for sending CORS headers. Download and install the CORS module (or use drush en cors) and go to /admin/config/services/cors. Paste the following string in the domains field: *|http://next.walkhub.net|OPTIONS,POST,GET|Origin,Content-Type,Accept,X-CSRF-Token|true
  • CORS module settings
  • Go back to your widget node, and now you can see the embeddable code and the rendered widget in the bottom right corner. If you copy and paste the embed code into any of your sites’ HTML source, you will get the same button as on the widget node’s page.
  • If the result is not as expected, try to solve it by clearing the Drupal cache in /admin/config/development/performance.
    Feel free to extend the features or theme the widget node’s page.

    Got stuck somewhere? Do you need help? Contact us for support!

    How to choose between Embedthedocs.com and your own Drupal 8 site?

    EmbedTheDocs.com is a convenient way to try out what the Help Widgets offer. If what you need are only a few widgets, EmbedTheDocs.com will suffice.

    Your own, private Help Widgets system can offer some extras that proprietary and/or confidential materials may even require:

    • Store your help contents on the server of your choice, with your security and permission settings.
    • Have full control over access and management of your custom data stored in the Drupal system.
    • Customize the appearance of the widget nodes (Drupal enables easy theming).

    Kitti started to work at Pronovix in June 2015 as an iTrainee, and this was the first time she met with web programming. During the trainee programme, she evolved a lot on the field of theming and Drupal site building with the assistance of her colleagues. Now she is a Front-End Developer and Site Builder at Pronovix and she also takes part in Devportal architecturing.

    Newsletter

    Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.

     

    Subscribe