<- Back to Main Documentation

SimplicityBlocks™ Vanilla JS Communication Test Page


This page describes the various ways to communicate between the host page and your embedded widget.

Our sample widget and this test page are built using Vanilla JavaScript. We do this to simplify the explanation of the concepts. Your widgets can be built using any framework you wish.

The <simplicity-block> that is embedded in this page is configured as a nonmodal overlay on the bottom right so you can click on test buttons while the widget is displayed.


In the SimplicityBlocks™ widget configuration area you can define as many attributes as you like (reference the attributes documentation).

There are two attributes set up for the sample rating widget. They are: rh (Rating Heading) and ch (Comment Heading). These attributes are assigned by the web page developer implementing the SimplicityBlock™ in their web page by assiging the attributes values in the simplicity-block tag.

Inside the Host Page

As shown below the <simplicity-block> component is embedded in the web page and has the two attributes set with text desired for the rating heading and the comment heading.


    <simplicity-block sbid="73B48DCA" id="sblock" rh="Rate this Product" ch="Enter your Comment"></simplicity-block>

Inside the Widget

There are two span tags with id's inside the widget that allow the JavaScript to set the text.

    <h1><span id="ratehead"></span></h1>

    <label for="commentField" class="xspace clabel"><span id="commenthead"></span></label>


The javascript code inside the widget reads the URL parameters at load time and sets the text based on this values.

    //the getParameterByName reads the value of the parameter namepassed to the function
    function getParameterByName(name, url) {
        if (!url) url = window.location.href;
        name = name.replace(/[\[\]]/g, "\\$&");
        var regex = new RegExp("[?&]" + name + "(=([^&#]*)|&|#|$)"),
            results = regex.exec(url);
        if (!results) return null;
        if (!results[2]) return '';
        return decodeURIComponent(results[2].replace(/\+/g, " "));
    (function () {
        let rhead = document.getElementById("ratehead");
        rhead.innerText = getParameterByName("rh");
        let chead = document.getElementById("commenthead");
        chead.innerText = getParameterByName("ch");

Changing Attributes Programmatically in Host Page

The following code is the click event handler for the "Change Attributes" button below.

    let caButton = document.getElementById("changeattributes");
    caButton.addEventListener("click", function () {
        let sbEl = document.getElementById("sblock");
        sbEl.setAttribute("rh", "New Rating Heading");

Click on the "Change Attributes" button below (keep the widget displayed when doing this) wil execute the above code. This causes a reload of the widget with the parameters changed to the new value in the Rating Heading.

Close Button

The Simplicity Blocks™ allows for the configuration of a round close button displayed at the top right of the widget container. If this style does not work for you, you can define that button as 0px and have a close button within your own widget. The demo rating widget here has a "CLOSE" button defined with an event handler that sends a close command to the <simplicity-block> component.

The following code is the "CLOSE" button click event handler inside of the widget. The handler sends a postMessage to the parent element with an object that has a key of name and a value pf 'close'.

    let closeButton = document.getElementById("close");
    closeButton.addEventListener("click", function () {
        window.parent.postMessage({name: 'close'}, "*");

sendMessage Method

The <simplicity-block> component has a generic method available that can be used by the host to communicate with your widget without the need for a full re-load as is the case with attribute changes. The sendMessage method takes an object as its single argument. You can define the object however you want as the component simply passes that to your widget via a postMessage.

JavaScript Inside the Widget

The code below shows the handler inside of our demonstration rating widget that responds to the event that is triggered by the Host page executing the sendMessage method.

Note that the sendMessage method simply passes an object through to your event handler. You can specify the structure of this object as anything you want.

    //the widget code exoects an object with two keys: cmd and color
    //you can define this object however you want. The information just needs to be communicated to the host page author.
    window.addEventListener("message", function (event) {
        if (event.data.cmd == "bcolor") {
            document.body.style.backgroundColor = event.data.color;
    }, false);

Code Inside the Host

The code inside the host creates the object the widget expects along with the necessary values and then passes that object as an argumnent with the sendMessage method.

Here is the code inside this demo page that executes the sendMessage method:

    let sendObject = {cmd: "bcolor", color:"#ffcc99"};
    let smButton = document.getElementById("sendmessage");
    smButton.addEventListener("click", function () {
        let sbEl = document.getElementById("sblock");

Click the button below to execute the above code. Keep the rating widget displayed so you can see the background color change when you click the button. Note that the widget did not have to reload to execute the code.

open Method

The open method is called on the SimplicityBlocks™ instance to trigger the opening of the widget. This can be useful in cases where you do not want to use a launcher or in cases where you want other items on your page to also open the widget (e.g., text links or other buttons).

or Text Link to Open

Here is the code inside this demo page that executes the open method:

    let openButton = document.getElementById("openbutton");
    openButton.addEventListener("click", function () {
        let sbEl = document.getElementById("sblock");

close Method

The close method is called on the SimplicityBlocks™ instance to trigger the closing of the widget. This can be useful in cases where you do not want to use a launcher or in cases where you want other items on your page to also close the widget (e.g., text links or other buttons).

or Text Link to Close

Here is the code inside this demo page that executes the close method:

    let closeButton = document.getElementById("closebutton");
    closeButton.addEventListener("click", function () {
        let sbEl = document.getElementById("sblock");

Trigger Event to Host

Your widget can also trigger an event that the <simplicity-block> component will pass to the host page through the sbnotify event.

Your widget creates an event by using a postMessage method to the parent window (window.parent.postMessage). The host page adds a listener for the sbnotify event onto the <simplicity-block> component.

Using the demo Rating Widget when you select a rating, enter a comment and then click on the "SEND" button, the widget code does a postMessage and passes an object with it. The event handler in the host page receives the sbnotify event and then reads value from the passed object which are in the event's data field. For demonstration purposes this demo page simply does a JavaScript alert to display the values of the rating and the comment.

Widget JavaScript Code

    let sendButton = document.getElementById("sb");
    let getComment = document.getElementById("commentField");
    sendButton.addEventListener("click", function () {
        window.parent.postMessage({rating: currentRating, comment: getComment.value}, "*");

Host Page Event Handler Code

    let bel = document.getElementById("sblock");
    bel.addEventListener("sbnotify", function(event) {
        let displayMessage = "Rating: " + event.detail.rating + "\n" + "Comment: " + event.detail.comment;