Third party JavaScript – an improvement

If you’ve ever released a JavaScript widget, one which people can include within their site or even if you’re one of those people that has had to copy one of those ugly chunks of code and somehow come to terms with placing it in your previously clean HTML, I’m sure you’ll appreciate a cleaner and less scarring alternative. After all, anything’s got to be better than this:

<div id="widget_133332_g_foobar"></div>
<script>
    widget_133332_v_height = '233px';
    widget_133332_v_width = '200px';
    widget_133332_h_align = true;
    widget_133332_v_align = false;
    widget_133332__debug = false;
    widget_133332_id = 'Foo';
</script>
<script src="http://some-widget-url.com/script?id=widget_133332"></script>

And within script?id=widget_133332 there will be something like this:

document.write('<div id="widget_133332">...</div>');
document.write('<div id="widget_133332_a_sec">...</div>');
document.write('<div id="widget_133332_b_sec">...</div>');
document.write('<div id="widget_133332_c_sec">...</div>');

I’m not complaining; it’s not all that bad. However it could be done better; much better!

I decided to have a proper go at creating one of these. There were a couple of barriers to completion that required some extra work along the way; I’m releasing that extra work as a small stand-alone library that you can use within your 3^rd party scripts. Here’s an example chunk-of-code:

<script src="http://some-service.com/widget.js?id=2323">
({
    width: 200,
    height: 400,
    id: 'my-widget',
    keywords: ['apple', 'orange', 'banana']
})
</script>

Nicer to look at and much easier to use than the status quo! The JSON-like syntax is very easy-to-follow, even if you’ve never seen anything like it. The library used to enable this unique technique is called embedHelper.

The idea is that the user will copy a piece of code similar to that above on to their site. widget.js (the 3^rd party script) will contain this small helper-library plus the code required to make the widget work. embedHelper gives you access to the configuration within the script tag, additionally it lets you access the query string within the src attribute as key-value pairings (an object).

The pseudo-JSON within the SCRIPT tag will be ignored by the browser because there is a src attribute (that’s why browsers look for the JavaScript). However we can still get at it via the innerHTML DOM property. Then we can eval* the psuedo-JSON and use it within our 3^rd party script.

* – For this purpose eval (or (new Function())()) is okay to use in my opinion. The arguments against it do not outweigh the clear benefits. Don’t jump on the “eval is evil” bandwagon just for the sake of it!

The following methods are available under the embedHelper namespace:

• embedHelper.getConfig( [ defaults1, defaults2 ] ): This will return a configuration object, just as the user defined. If you have any default settings that you want to merge with the user’s configuration (obviously giving the user’s options precedence) then you can pass them as arguments (the last one will have precedence over previous ones).

  var defaults = { widgetColor: 'red', widgetBackgroundColor: 'white' }; var options = embedHelper.getConfig( defaults );

• embedHelper.getQueryParams(): This will return an object corresponding to the query string parameters included in the src attribute of the “parent” SCRIPT tag. This can be used as an alternative to configure the widget. As with getConfig you can pass default objects to this method too; note this was only added as a convenience – I doubt it’ll be that useful.

  // E.g. <script src="http://url.com/script.js?foo=bar"></script> var query = embedHelper.getQueryParams(); query.foo; // => "bar"

• embedHelper.insert( domArray | htmlString | domNode ): This is a convenience function for those of you who are bound to claim that document.write is the only way to inject into the DOM at the position of the SCRIPT tag. This method does exactly that and accepts either a dom node (or fragment), an array of DOM nodes (or an array-like object – like jQuery’s) , or an HTML string:

  /* These will be inserted at the position of the <SCRIPT/> tag */ embedHelper.insert('<div id="foo">...</div>'); embedHelper.insert( document.createElement('div') ); embedHelper.insert( [aDiv, anAnchor, aSpan] ); embedHelper.insert( jQuery('<div/>') );

• embedHelper.scriptRef: For advanced usage, you can get a reference to the SCRIPT element.

  var script = embedHelper.scriptRef; // Note: this is not a function. jQuery('<div>Foo</div>').insertAfter(script);

No initialisation is needed before having access to the above methods and properties; these methods can be called at any time. It’s best to place the helper “library” at the top of your widget.js file (your 3^rd party script). It’s very important that it exists in the file requested from the SCRIPT tag, not in another file request separately.

The library is quite small – around 1kb (minified). You can download it and the demo files at Github!

Thanks for reading! Please share your thoughts with me on Twitter. Have a great day!