A Beginners Guide to Cross-Domain Components with Zoid

Zoid is a toolkit to help facilitate the ability to send data between domains. As a software engineer at PayPal, I came across this toolkit when trying to understand how PayPal Checkout works.

“A button on a page that sends money, how can that be secure?”

The first thought some of you might have is,

“iframe it!”

Okay great, but how do we deal with merchant data? What is the total cost for the checkout? Well, you might then say,

“You can use apis or webhooks, duh.”

Also great, but that is a lot of work just to share browser data, can’t we just do it on the browser? The answer is YES!

What is post messaging?

Post messaging allows us to communicate between two domains in one browser instance. Let’s look at an example of the window.postMessage() function. For simplicity sake, let’s use parent as the main page and child as the iframe.

This can be written in reverse as well, sending messages from child to parent.

What problem is Zoid trying to solve?

As you might imagine, implementing post messaging can get pretty crazy and annoying once you start to add multiple listeners to different elements on the page, and have multiple different types of messages coming to each listener.

Zoid solves this problem and more. To keep it simple, we will focus on the above issue with post messaging.

Why should you use Zoid?

Zoid makes post messaging simple by giving you a quick and easy way to make a connection between multiple domains and centralizes each component link by a tag, which is used to namespace the component.

After that, you are able to easily send any type of data between parent and child components, as long as they accept it.

Is Zoid secure?

Yes! Components can’t send or manipulate anything they want on the other domain just by being connected. Each domain will specify what it is allowing the other to do, so as long as you write your components to have limited access to your document, the other components won’t be able to mess with your page.

That being said, always be diligent and careful when dealing with foreign js or webpages!

Basic Tutorial

Zoid-lesson is a repository I wrote to help guide developers who are new to Zoid. I will cover the first three tutorials of this repo below, in a shortened version. If you like the first three, check out the forth tutorial! Tutorial four is where we create an end to end version of a multi-zoid component application and really dig deep into data passing between components.

You can download Zoid and extract it in your project or use the Zoid module and run a builder like Webpack or Babel.

The first tutorial talks about getting a component link up and running. All we have to do for this is add a zoid.create() call to both the parent.js and child.js. The create function returns a Zoid object, which we will use to render the component. By default, Zoid renders the child component in an iframe.

Additionally, we want to add an element that the parent can render the iframe into. To do this we need to call the component.render() function and pass props, which I called options, and element as parameters. component, in this case, is the object returned by zoid.create().

You can only use zoid.create() once per tag, per page. So, the parent.js and child.js need to act as independent apps during transpile time, if you are using something like Webpack. A simple way to test Zoid is to create a parent.html that loads the parent.js and a child.html that loads the child.js.

The second tutorial focuses on customizing the child component’s frame when the parent tries to load it. The zoid.create() functions has many options to customization. For tutorial two, I focus on some of the most common: dimensions, pre-render templates, and contexts.

Below is an example of all three. Before we go into that, I will explain what each one is and how it works.

Dimensions: Dimensions are given as an object of the keys width and height and must be in either px or % string notation. If you are using %, remember it is relative to the element you pass into component.render().

Pre-render Template: The prerenderTemplate is a function that will be called during the construction of the Zoid object. When the Zoid component tries to load, it dynamically pulls the child code to render in the iframe. During this loading time, a prerenderTemplate can be shown.

Contexts: Multiple context options exist in Zoid, but we will focus on two, iframe, which we already talked about, and popup. As mentioned above, iframe is the default, but if we add popup:true in the context object, we can tell Zoid we want it to render as a popup instead.

As a note, I am only editing the parent.js create call. The client.js is still written as above.

One more option I want to touch on during create is props validation. Tutorial three deals with sending data between components using props, and the zoid.create() allows us to have validation for these props. This can be used to require certain props be passed, secure what props can actually be sent, and document what props are expected. This is optional, but a good idea for production code!

Props is an object that has a simple structure. The keys in the props validation object are the same keys you expect in the render props object, the type enforces the expected type of that prop during the render call, and the required key is obviously states if it is required or not.

An import note, these are NOT the actual prop data. This is just a spec of what the Zoid component will expect or require in the render method call. It might seem a little confusing.

Tutorial three is focused on the meat of post messaging, actually passing data. In Zoid, this is extremely simple. The component.render(), referenced above, takes a props object as it’s first parameter. This props object can be filled with virtually anything!

When the parent renders the Zoid component, it attaches an object called xprops to the child’s window object. Technically, the data only flows one way, from parent to child, but there is a way to make the data available two ways. If you notice above, we passed a function as well as a string. The string is copied during the rendering process, but the function it not. It references the original function created by the parent page, so calling updateBackgroundColor actually references the parent document object.

Many options exist for how you can creatively use props. Experiment, have fun, and you did it! You have the basics to create your own cross-domain connect.

More Zoid!

Zoid can do a ton of other cool things that I haven’t covered. If you want to learn more go to https://github.com/krakenjs/zoid. They cover Zoid with React, Zoid with Angular, and Zoid in different contexts.

Thanks for reading!

If you had any trouble following along please visit the zoid-lesson repo where I got into Zoid in more detail per tutorial.

Any constructive feedback is welcome!