HTML/JS Widgets at Widgetbox

An HTML/JS widget, formerly known as a Hosted HTML widget, contains HTML and/or JavaScript code hosted by Widgetbox.

You can author your HTML/JS widget using the Widgetbox editor, which allows you to code, preview and debug your widget on a single page. Users who subscribe to your widget will receive a copy of it served by Widgetbox.

When you make an HTML/JS widget on Widgetbox, you can start from scratch or by modifying a Hello World example widget.

“Hello World” Widget

When you make an HTML/JS widget, you can begin by using our “Hello World” example widget. This widget demonstrates how you can use Widget Settings in your Widget Code to create a user-customizable widget.

Comments built into Hello World’s Widget Settings and Widget Code will help you understand the interaction between these two panels. Here’s how to get started:

1. Access the Make a New Widget start page.
2. Click “HTML / JS”.
3. Accept the default options shown below.
Make a New Widget - Hello World

4. Click Continue

Good start! You’ve just made a widget named “My Widget”. It’s not shared in the Widgetbox gallery, so play around with it as much as you like!

Widget Code Editor

When you make an HTML/JS widget, you’ll have a chance to use our new Widget Code editor. It includes two time-saving features: automatic tag completion and colored syntax highlighting. Type in the name of your favorite HTML tag without the “angle brackets” and press tab: we’ll insert the brackets and closing tag for you.

Widget Settings

Here’s the HTML of a simple HTML/JS widget that lets the user make a personal greeting.

Hello from ${config.your_name}

The ${config.your_name} is a parameter that the user subscribing to the widget will fill in. Learn more about configuration parameters in our forums.

Configuring an Existing JavaScript-based Widget

If you have an existing widget, and users get it by putting a <script> tag on their site, here’s what the HTML/JS code might look like:

<script src="http://domain.com/myscript.js?${config.userID}"></script>

This would insert a user ID into the script’s URL, letting your server know how to generate the returned JavaScript.

Here’s another common way JavaScript widgets set up their per-user configuration:

<script>
      var userID = ${config.userID};
    </script>
    <script src="http://domain.com/myscript.js?${config.userID}"></script>

Useful Variables

These are replacement tags that you can use in a HTML/JS widget:

Tag	Meaning
`${widget.height}`	The height of the widget, as configured by the person subscribing to it.
`${widget.width}`	The width of the widget, as configured by the person subscribing to it.
`${widget.location}`	The URL of the page the widget is being displayed on. For example, `http://myblog.typepad.com/some-post`. The page’s query string, if any, is not included.

Let Your Users Change Colors and Fonts

Users love being able to customize the look and feel of a widget to fit their web page. Here’s a template for building color and font configurability into your HTML/JS widget.

Widget

Configuration screen

This is what the widget’s configuration screen looks like when building it in the widget editor:

The source code for the above widget.

<style type="text/css">
	  body /* Widgets are rendered in an iFrame so 'body' applies just to the widget */ { 
		color: ${config.text-color};
	  	background-color: ${config.background-color}; 
	  	font-family: ${config.fontFamily}; 
	  	font-size: 10pt;
	  	width: ${widget.width}px; 
	  	height: ${widget.height}px;
	  }
</style>

<p style="text-align:center;font-weight:bold;">Hello World!</p>

What Sort of Content Can I Put In an HTML/JS Widget?

They can contain pretty much anything HTML allows: CSS, Javascript, Flash, etc.

However, HTML tags like <body>, <html>, <title>, <head> cannot be used in HTML/JS widgets. If you save a widget with these tags, they are replaced with comments.

For example, the following code…

<html>
    <head >
        Here is some head content.
    </head>
    <body>
        Here is some body content.
    </body>
    </html>

…becomes:

<!--html tag not allowed-->
    <!--head tag not allowed-->
        Here is some head content.
    <!--head tag not allowed-->
    <!--body tag not allowed-->
        Here is some body content.
    <!--body tag not allowed-->
    <!--html tag not allowed-->

Links in HTML/JS Widgets

Widgetbox places each widget in an iframe, for security reasons (discussed here).

This creates a gotcha. When you click a link in a widget, the new page is rendered in the widget’s space rather than refreshing the whole browser window, *unless* you put in a target=”_new” or “_top”.

The following bit of JavaScript does exactly that. Paste it into a hosted or remote widget, and it will cause all links to pop up in a new browser window. Change _blank to _top to make links render in the existing browser window.

<script>
	var i;
	var aTags = document.getElementsByTagName(“a”);
	for (i=0; i < aTags.length; i++) {
		aTags[i].setAttribute(“target”, “_blank”);
	}
	
	var areaTags = document.getElementsByTagName(“area”);
	for (i=0; i < areaTags.length; i++) {
		areaTags[i].setAttribute(“target”, “_blank”);
	}
</script>

If you’re using a form, try adding target=“_blank” to the form tag itself. Like so:

<form action=“something” target=“_blank”>