Knowledgebase/Support Documents /Developer Guide

HTML/JS Widgets

Philip Remer
posted this on February 25, 2011 16:26


(Available to Widgetbox Pro members only)

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 Widget page.
2. Click "HTML / JS".
3. Accept the default options 
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.  

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:

TagMeaning
${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.

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 formTags = document.getElementsByTagName("form");
	for (i=0; i < formTags.length; i++) {
		formTags[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”>
 
Topic is closed for comments