Velo: Working with the HTML iframe Element

An HTML element allows you to add raw HTML or embed another website within your page. You can also pass data between your page code and the code in an HTML element. That means you can use it in all sorts of situations to do things you can't normally do directly, even when using Velo.

In general, you do not have access to the HTML and full code of your site's pages. This can sometimes be limiting when you want to add 3rd party code to your site. Using an HTML element you can sometimes overcome these limitations by adding raw HTML to your page.

The HTML element creates a sandboxed environment (an iframe) that does not have direct access to the other elements on your page. You can, however, pass data between your page code and the code in an HTML element. This means that widgets or libraries that need access to the rest of your page will not work in an HTML element. But if the widget or library just needs to send data to or receive data from your page elements, you can write code to make it work.

Embedding Another Site

Typically, when you want to embed another site in your site, you add an HTML element and use its settings to add the address of the website you want to embed.

For example, to embed a Wikipedia page in your site, add an HTML element to your page and set its Website Address to be the URL of the page you want to embed.

Embedding a Widget

Typically, when you want to embed a widget in your site, you need to add some code provided by the widget's creator. 

Let's take a look at some of the types of widgets you can embed in your site and some of the types of widgets that will not work properly.

Standalone Widget

Widgets that do not need to know any information about your site will usually work when their code is pasted into an HTML element.

For example, the AccuWeather Current Weather Widget is a widget that displays the current weather. Since it doesn't need to know anything about your page elements, you can add it to your site using an HTML element.

To add an AccuWeather Current Weather Widget to your page:

• From the Embed section of the Add menu, drag an HTML iframe element to your page.
• Go to the Create a Current Weather Widget page, set the parameters for your widget, and get a code snippet.
• In the HTML element's settings panel, select Code and paste the widget code.

Dependent Widget

Widgets that need to know about the Wix elements on your page will not work when their code is pasted into an HTML element.

For example, Google's Website Translator is a widget that translates the contents of your page into another language. Since it needs to know about your page elements to translate them, you can't add it to your site using an HTML element and have it translate the rest of your page. You can, however, add it to an HTML element and have it translate the contents of the element itself.

Using a JavaScript Library

There are many JavaScript libraries that you can use in an HTML element. However, limitations similar to those regarding widgets apply to libraries as well. The library you add will only be able to interact with the elements inside your HTML element. To interact with the library from your page code or to interact with your page elements from the library, you need to use the messaging model described below.

elementFor example, Chart.js is a JavaScript library that you can use to create charts. You can use a <script> tag to link to the Chart.js library and write HTML and JavaScript that will display a chart in an HTML element on your page. You can also send messages between your page and the HTML element so that interactions with your page can affect the chart and interactions with the chart can affect your page.

To see a working example of a site that creates a chart using Chart.js, see the Chart example.

Messaging

You use code to send and receive messages between your page and your HTML element. You can send and receive data as any valid JavaScript type.

Sending a Message from Page Code to an HTML Element

You send a message from your page to an HTML element using the HTML element's postMessage() function.

For example, if your page contains an HTML element with the ID myHtmlElement:

Receiving a Message from Page Code in an HTML Element

You receive a message in your HTML element by creating an event handler for the window.onmessage event in the element's code. You create the event handler within an HTML <script> tag. You get the received data by getting the data property of the event handler's event parameter.

For example, in your HTML element's HTML Code:

Sending a Message from an HTML Element to Page Code

You send a message from your HTML element using the postMessage() function in the element's code. Generally, you will be calling postMessage() from within a function.

For example, in your HTML element's HTML Code:

Receiving a Message from an HTML Element in Page Code

You receive a message in your page code using the HTML element's onMessage() function to bind an event handler. You get the received data by getting the data property of the event handler's event parameter.

For example, if your page contains an HTML element with the ID myHtmlElement:

Example - Messaging Demonstration

In this simple example, we demonstrate sending and receiving messages in both directions. We create a page with two similar sides. One side is built with Wix page elements. The other side is built with HTML in an HTML element.

The left side of the page shown below is created with Wix page elements. It contains:

• A text element that is used to display messages received from the HTML element
• A button element that is used for sending messages to the HTML element
• A text input element that is used for entering the message to send to the HTML element

The right side of the page shown below is created with an HTML element. The element contains HTML that mimics the elements on the left side. 

Using this setup, we demonstrate how to send and receive messages between the page code and HTML element. You can enter text on either side, click the Send Message button, and the text will be displayed in the other side's text label.

Page Code

The following code is added to the code editor. It contains two parts.

First, in the page's onReady() event handler, we set an event handler that runs when the page receives a message from the HTML element. The event handler sets the text of the page's text element to be the data sent from the HTML element.

Then, in an event handler for the page's button, we send a message to the HTML element. The message's data is the value of the text input.

HTML Element Code

The following code is added to the HTML element using the Edit Code button. It contains three main sections.

In the <body> tag, we define the HTML elements that make up our page. Similar to what we created using Wix page elements, we have:

• A <span> that is used to display messages received from the page code
• A <button> that is used for sending messages to the page code
• An <input type="text"> that is used for entering the message to send to the page code

In the <style> tag, we define some styles that are used by the HTML elements mentioned above. These styles aren't actually necessary. We are just using them to mimic the design of the Wix page elements.

In the <script> tag, we define our messaging logic. There are two parts to the messaging logic.

First, when the HTML element loads, we set its onMessage property to an event handler that sets the text of the element's <span> to be the data sent from the page code. This event handler is called each time the HTML element receives a message from the page code.

Next, when the button in the HTML element is clicked, it calls the button_click() function. We define the button_click() function to send the text in the HTML element's text input to the data sent to the page code.