bhanditz / operaextensions.js

Opera (.oex) Extensions JavaScript API Compatibility Layer for Chromium-based Opera 15+ (.nex) Extensions

Opera Extensions JavaScript API Compatibility Layer (operaextensions.js)

This library provides a compatibility Layer containing the JavaScript Opera Extension APIs that have been provided in Opera <= version 12.

This library is intended for use in the oex2nex convertor tool. If you want to convert an existing Opera oex extension into an Opera 15+ nex extension then you should download the oex2nex convertor tool directly rather than using this library standalone.

Supported Opera Extension APIs

This library adds support to Chromium for the following Opera (.oex) Extension APIs:

• Widget object
• Windows and Tabs API
• Messaging API
• Button and Badge API
• Popup API
• Resource Loader API
• Screenshot API
• Injected Scripts API *
• URL Filter API
• Context Menus API
• Speed Dial API

* minus support for addEventListener and removeEventListener UserJS events.

Further API reference documentation

The full Opera Extension (.oex) API Documentation is provided for reference in the /docs directory of this repository.

Download this library

You can download a ZIP or TAR.GZ file containing all the operaextensions.js library code or you can clone this repo via Git as follows:

git clone git://github.com/operasoftware/operaextensions.js.git

Building the libraries

Using utilities provided in this library we can build the compatibility library for the different contexts in which it can be used.

The latest builds are provided by default in the /build directory of this repository (see: the Opera Extension Compatibility Libraries section below). If, however, you would like to build these files yourself then the following instructions are for you.

The build utilities included in this library have the following dependencies that first need to be installed:

• Python >= version 1.6
• Java

To build the library from source change directories to the folder in which you cloned this repository and execute the follow code:

cd ./utils
./build.sh

(alternatively, we can replace 'build.sh' above with 'build.bat' if we are running on Windows).

The Opera Extension Compatibility Layer libraries

The following six final build files are provided in this repository:

• /build/operaextensions_background.js - The compatibility file required for code running in an OEX background process.
• /build/operaextensions_injectedscript.js - The compatibility file required for code running in an OEX injected script process.
• /build/operaextensions_popup.js - The compatibility file required for code running in an OEX popup process (and code running in a tab view context such as e.g. an Extension's options page).
• /build/operaextensions_background.min.js - A minified version of /build/operaextensions_background.js for inclusion in your own converted extension.
• /build/operaextensions_injectedscript.min.js - A minified version of /build/operaextensions_injectedscript.js for inclusion in your own converted extension.
• /build/operaextensions_popup.min.js - A minified version of /build/operaextensions_popup.js for inclusion in your own converted extension.

Using the libraries in your own converted extension

Each library available in the /build directory of this repository needs to be included in to your extension according to the guidelines provided below.

Note: It is strongly advised that you use these library files via the oex2nex convertor tool only. The oex2nex convertor tool will parse and modify your existing Opera oex JavaScript code to run correctly under this compatibility layer. The following instructions are intended for debugging purposes only and do not cover the JavaScript code anomalies you will find if you attempt to run this in an unconverted oex extension.

Including the background process library in your converted extension

1. Copy /build/operaextensions_background.min.js to your Opera oex extension's directory (to e.g. /oex_shim/operaextensions_background.min.js)

2. Add a new <script> tag in your background HTML page as follows:

   <script type="application/javascript" src="/oex_shim/operaextensions_background.min.js"></script>

3. Wrap all your existing Opera oex extension code in an opera.isReady function as follows:

   opera.isReady(function() {
      // your old OEX extension code goes here
    });

Including the popup process library in your converted extension

1. Copy /build/operaextensions_popup.min.js to your Opera oex extension's directory (to e.g. /oex_shim/operaextensions_popup.min.js)

2. Add a new <script> tag in all your popup HTML pages (including your options.html page if available) as follows:

   <script type="application/javascript" src="/oex_shim/operaextensions_popup.min.js"></script>

3. Wrap all your existing Opera oex extension code in an opera.isReady function as follows:

   opera.isReady(function() {
      // your old OEX extension code goes here
    });

Including the injected script process library in your converted extension

1. Copy /build/operaextensions_injectedscript.min.js to your Opera oex extension's directory (to e.g. /oex_shim/operaextensions_injectedscript.min.js)

2. Add this path to the content_scripts directive inside your extension's manifest.json file as follows:

   "content_scripts": [
       {
         "matches": ["http://*/*", "https://*/*"],
         "js": ["/oex_shim/operaextensions_injectedscript.min.js"],
         "run_at":"document_start"
       }
   ]

3. Wrap all your existing Opera oex extension code in an opera.isReady function as follows:

   opera.isReady(function() {
      // your old OEX extension code goes here
    });

Feedback

If you find any bugs or issues please report them on the operaextensions.js Issue Tracker.

If you would like to contribute to this project please consider forking this repo and then creating a new Pull Request back to the main code base.

License

Copyright © 2013 Opera Software ASA

See the LICENSE file.