Converting UserJS to Opera Extensions

By Chris Mills, Daniel Davis

From Opera 15 onward, Opera 11 & 12’s extension format is no longer supported, and instead, we’ve switched to Chromium’s extension model. Check out our new documentation for developing extensions for Opera 15 and higher and start building your own extensions.

Introduction

This is a quickfire guide to converting a UserJS over to an Opera extension. This is a very straightforward process, although there are a few caveats to be aware of, which will be discussed below. We round off the article with a practical example.

The process

1. First of all, create an empty directory to act as the root directory of the extension.
2. Place your UserJS into an includes folder, inside the root directory — this effectively uses it as an injected script.
3. Create an icon for the extension to use, and place it inside a directory (named something like icons) inside the root directory.
4. Create an appropriate config.xml file and place this inside the root directory)
5. Create an empty HTML document and save it as index.html inside the root directory
6. Select all the contents of the root directory, zip them up, and give the file an .oex extension.
7. You now have an extension that should work fine, although you should test and debug it before you upload it to the Opera extensions site.

Caveats

Sometimes the UserJS doesn't work as an extension, for various reasons. Often it's because an object is accessed directly — location or opera, for example — although this is simple to fix by accessing them from the window object instead (window.location, window.opera, etc.)

A real world example

To prove how easy it is to convert a UserJS into an Opera extension, here's an example that will turn you into an extension developer in a matter of minutes. Start the stopwatch!

Step 1: Find a UserJS

For this example, we'll use a topical HTML5 video UserJS created by a former intern at Opera, Martin Rauscher. His script enables an HTML5 video to be viewed fullscreen. It goes without saying that you should check the license of any script you intend to use and re-publish. In this case, Martin kindly gave me permission but you could equally use scripts released under an open source or otherwise permissive license.

Step 2: Create some directories

Firstly, a home for our extension is needed, eg VideoFullscreen. To comply with the W3C Widget Packaging and Configuration specification we create an empty starting page in here, named index.html. Then we create a sub-directory named includes and into that, we copy our UserJS file (VideoFullscreen.js).

Step 3: Create an icon

You could of course lovingly design your own custom icon but in this example we're being lazy, so let's head on over to the Open Icon Library. There are hundreds of icons available for use although check the license first as some of them require attribution. Of course, it's always nice to mention the source anyway, and in this case the credit goes to the Tango project for this icon representing a fullscreen action. Let's use the 64x64 version as this is the maximum resolution for Opera's extension manager.

Step 4: Create a configuration file

Again, the emphasis is on being lazy, I mean, efficient, so feel free to copy and paste the code below into a blank config.xml file and save it in your extension's root directory:

<?xml version="1.0" encoding="utf-8"?>
<widget xmlns="http://www.w3.org/ns/widgets">
    <name>VideoFullscreen</name>
    <description>Adds fullscreen capability to every HTML5 video element. Just play the video and then hit SHIFT-ENTER or F11.</description>
    <author href="http://rauscheronline.de/">Martin Rauscher (ported by Daniel Davis)</author>
    <icon src="VideoFullscreen.png"/>
</widget>

Remember to change all the details to match your particular extension and give yourself credit as well as the original author.

Step 5: Make an index.html

Make an index.html, which can be blank. If you don't, your extension won't install. If you drag the config.xml into Opera and the textual content of the file is shown, rather than your extension installed in extension developer mode, that's a sign that you've forgotten this step.

Step 6: Wrap it up

The last step is to package it - select the icons and includes directories and the index.html and config.xml files and zip them them up. Finally, change the file extension to .oex - eg our VideoFullscreen.zip becomes VideoFullscreen.oex - that's it! It's ready to be installed by dragging it to the Opera desktop browser.

Step 7: Tweaking and bugfixing

Despite the original UserJS working well, your new extension may not. It's a good idea to check the error console before anything else, but in most cases the problem could be due to the environment structure of Opera extensions, meaning we have to be more specific about some objects we use. In the case of VideoFullscreen.js, the addEventListener() method is used a few times but it's not specified what object we're attaching these events to. The UserJS environment assumes window, which is correct, but the Opera extension environment is more complex so we have to specify window, as in the code below:

window.addEventListener('DOMContentLoaded',init,false);
window.addEventListener('DOMContentLoaded',function(){
	document.getElementsByTagName("body")[0].addEventListener('keydown',keyDownHandler,false);
},false);
window.addEventListener('DOMNodeInserted',init,false);

While we're delving into the code, we could also look for areas to improve. In the case of this script, we could make the following change to make it slightly more efficient:

// Change this:
document.getElementsByTagName("body")[0].addEventListener('keydown',keyDownHandler,false);

// to this:
document.body.addEventListener('keydown',keyDownHandler,false);

We have a detailed article on writing efficient JavaScript which is recommended reading for speeding up not just your extension but web pages and applications too.

Step 8: Releasing it into the wild

Now we've converted it, tested it and tweaked it, we're ready to show it off. We can do this by uploading it to addons.labs.opera.com and telling the world. The extension we made in this tutorial can be found there, or alternatively you can download it here: VideoFullscreen Opera extension. After installing it, you can try it out by finding a page that contains HTML5 video, such as this educational video by Bruce Lawson, and after clicking play, press F11. In an upcoming article we'll look at dealing with the trauma of seeing Bruce Lawson in fullscreen but until then, we look forward to seeing your extensions, both converted and newly created.

Chris Mills

Chris Mills is a web technologist, open standards evangelist and education agitator, currently working at Opera Software in the developer relations team. He spends most of his time writing articles about web standards for dev.opera.com and other publications (such as .net mag and A List Apart), giving talks at universities and industry conferences, and lobbying universities to improve their web education courses. He believes that education is the answer to everything, but in particular he is passionate about using education to improve the overall content quality, accessibility, usability and future-viability of the Web.

He is the creator of the Opera Web standards curriculum, contributor to the WaSP InterACT project, and coauthor of InterACT with web standards: A Holistic Approach to Web Design. In August 2011, he also accepted the position of co-chair of the newly-formed Web Education Community Group.

Outside work he is a heavy metal drummer, proud father of three and lover of good beer.

This article is licensed under a Creative Commons Attribution 3.0 Unported license.