Saying Hello World to Opera Extensions

This documentation relates to Opera's now deprecated .oex Extension API framework for Opera versions <= 12.15 and also provided by our OEX2NEX shim library.

For the latest Opera Extensions API documentation for Opera versions > 12.15 please consult the latest Opera Extensions API documentation online.

Introduction

This article walks you through the basic steps to create your first Opera extension. You will create a toolbar button, which when pressed will open a popup that displays a Hello World! message. Opera extensions are written using regular open web standards, so all you need to get started is a copy of Opera 11 and your text editor or IDE of choice.

Configuring an extension

First, you'll create the extension configuration file, which holds the meta data describing the extension. This is where information such as the extension name, author and icon for the extension manager is specified. Opera extensions use the W3C Widgets packaging and configuration format, which you may be familiar with from Opera Widgets.

Go ahead and create a bare bones configuration file as follows:

<?xml version="1.0" encoding="utf-8"?>
<widget xmlns="http://www.w3.org/ns/widgets">
  <name>Hello extensions!</name>
  <description>A simple hello world example</description>
    <author href="yourURL" email="yourEMail">Enter your name here</author>
    <icon src="hello.png"/>
</widget>

Save this file as config.xml in your development folder.

Creating an extension icon

You may have noticed the icon element in the config file. This specifies the icon used in the extensions manager and the Opera extensions site. We recommend creating an icon of 64×64 pixels for this.

Download the hello.png icon and save it in the "icons" folder inside your development folder.

Add a button to the Opera toolbar

Once you've configured your extension, you can start to create the actual code. Create a button, which is then added to the toolbar. This can be done with the following code:

<!doctype html>
<html lang="en">
  <head>
    <script>
       window.addEventListener("load", function(){
        var theButton;
        var ToolbarUIItemProperties = {
          title: "Hello World",
          icon: "hello-button.png",
          popup: {
            href: "popup.html",
            width: 110,
            height: 30
          }
        }
        theButton = opera.contexts.toolbar.createItem(ToolbarUIItemProperties);
        opera.contexts.toolbar.addItem(theButton);
      }, false);
    </script>
  </head>
  <body>
  </body>
</html>

Save this file as index.html in your development directory.

Any Opera extension requires a start file, commonly called index.html. A different filename could be used but it would have to be specified in the config.xml file using the <content src=""/> syntax. This file is a bare bones HTML template with a script that creates the UI elements. The body of this document isn't used.

The script will create a toolbar item (a button) with a number of properties. A tooltip is created along with an 18×18 icon. A popup belonging to the button is also created with a specified size, along with a reference to where the popup UI is defined.

You can download the hello-button.png icon and save it in your development directory.

Creating a popup

You've already created a button, and specified the size of the popup, so you just need to create the contents. This is just an HTML document, with its viewport set to the specified size. You can use any HTML, CSS, JavaScript or any other web technologies as you would normally use on a web page. This is a hello world example, so you'll create a page which says just that:

<!doctype html>
<html lang="en">
  <head>
    <title>Hello World!</title>
    <style>
      h1 {
        font: 14px helvetica, arial, sans-serif;
        text-align: center;
       }
    </style>
  </head>
  <body>
    <h1>Hello World!</h1>
  </body>
</html>

Go ahead and save this as popup.html in your development directory.

Packaging and installing the extension

You've almost got a finished extension. While developing, you can drag the config.xml file into Opera which will install it in Developer Mode. This aids development by allowing you to update your files and refresh the extension with the click of a button, rather than continually uninstalling and reinstalling.

When you're happy with your work and ready to release it, all you have left to do is to select all the files and zip them up. Once that is done, you can rename the zip file to HelloExtension.oex (remember to replace the .zip extension) and you're done.

Note on zipping extensions

You need to make sure you zip up your extension so that the files and directories that comprise it are in the root of the zip, and not inside a folder. To ensure this, make sure that you zip up the files inside your extension directory, and not the directory itself. Subtle, but it makes all the difference.

You can download the finished HelloExtension extension.

To install it as a regular user, i.e. not in Developer Mode, just drag the extension into Opera and it will ask you if you want to install it. You will see the icon you specified along with the meta data. Switch to a tab and try clicking on your newly created toolbar icon.

Try experimenting with the different properties of the toolbar button and the popup contents, until you feel comfortable with the process.