Building Blendle Widgets — Part 1: Architecture

When I started working at Blendle in January, one of my first assignments was to build something that would enable other developers and website owners to easily include pieces of Blendle content. I had a great time thinking and building this thing. We’re working with a number of publishers and large websites to have our widgets included, which is awesome. I’m really proud of what we have built so far, and that’s why I like to share some stuff we struggled with while building and rolling out the Blendle widgets.

In this first post of a series which will consist of several episodes, I’m going to give you an overview of the different components that make up our widgets. This posts is also used to clarify some terminology, which should help to get a better picture.

Host website and Javascript tag
This is the page that implements our widgets. I’ve built a simple page which anyone can use to setup and configure a widget. The generated code can then be added to any page. In another part of this series I’m going to dive into the embed code and the different options considered.

Widget div(s)
All of our widgets are plain HTML nodes, which are inserted by the widget source into the parent page. This has a couple of advantages:

• The widgets can be completely styled by the website’s owner and take over the existing styles automatically. If we’d use an iframe, this would not be the case because the widget would have its own DOM. You can see a couple of examples here, here and here.
• The widget can be of dynamic size and its content can be fully responsive. If an iframe was used, the container could be of a dynamic size, but it would be much harder to create widgets that are responsive and are able to scale down correctly.

Of course, there are some disadvantages as well:

• It is harder to set up for website owners, because we can’t control what kind of CSS they are running. Our CSS is pretty robust, but I can imagine there are still cases where code that is ran in the parent page is conflicting with our CSS. If you look at the Twitter widgets or Facebook plugins, you’ll see that they use iframes to render their fully styled embeddables.
• We can’t trust the parent page and if we need to know if someone is logged in, we need a safe and secure way to do this. If our widgets would be iframes that run on our domain, this would automatically be secure (roughly speaking). This is what our communication frame does.
• Everything we show, is known by the parent page. If the widget would be an iframe, we could securely expose things while the parent page stays in the dark.

Widget source
The widget source consists of 3 parts: widget.js, version.json and bootstrap.js. Widget.js is included by the script tag the site owner adds to his page. The only thing this does is fetch the version.json file. The version.json file returns the revision and the URI to the bootstrap.js file. This enables us to roll out new features without browsers caching stuff we don’t want them to cache. The widget source is hosted in a S3 bucket.

Communication frame and reader frame
The widget code adds one frame to the host on load. This communication frame is a simple html page which is loaded from the blendle.nl domain. This allows us to expose certain calls which require a cookie and we use postMessage for cross-origin communication. I will expand on this in a different post.

The reader frame is added as soon as the visitor clicks on a link in the widget. This launches another iframe, which loads up a normal instance of Blendle. We pass on some parameters so we know we run in ‘embedded’ mode. The reader frame uses the same postMessage strategy to communicate with the parent page.

Blendle backend
The widget connects to the normal backend for the non-authenticated calls. All calls that need authentication are sent via the communication frame. All non-authenticated calls are cached aggressively, and by eliminating those calls from the communication frame we save a few extra steps of work by the browser.

In my next posts, I’d like to expand some more on these topics:

• Communicating with a backend in a secure way from an insecure environment
• Embedtags
• Exposing an API to website owners
• The code structure of the widget itself

I might combine things, or add new area’s if I can think of something worth reading. If you have questions or idea’s on how to improve my posts or the widgets, let me know! I’d love to get some feedback.