Opera: User JavaScript Available methods and events

Take Control with User JavaScript

Available methods and events

window.opera.defineMagicVariable
window.opera.defineMagicFunction
window.opera.addEventListener
window.opera.removeEventListener
window.opera.setOverrideHistoryNavigationMode
window.opera.getOverrideHistoryNavigationMode

window.opera.defineMagicVariable

This method can be used by User JavaScripts to override global variables defined by regular scripts. It accepts three parameters:

Name: String giving the name of the variable to be overridden.
Getter: Function to be run whenever a script attempts to access the contents of the variable. Any value returned by the function is used as the value of the variable. The function will be passed a single parameter; the current value of the variable.
Setter: Optional; function to be run whenever a script attempts to set the value of the variable. The function will be passed a single parameter; the value that the script was attempting to assign to the variable. If no setter function is required, the value null must be used instead.

For example:

window.opera.defineMagicVariable(
	  'isGoodBrowser',
	  function (curVal) { return true; },
	  function (newVal) { if(!newVal) { window.status = 'Repairing script'; } }
	);

window.opera.defineMagicFunction

This method can be used by User JavaScripts to override global functions defined by regular scripts. It accepts two parameters:

Name

String giving the name of the variable to be overridden.

Implementation

Function to be run in place of the function defined by the page. The function will be passed the following parameters:

A reference to the real function defined by the page.
The object that would have been referred to by the 'this' keyword in the real function.
Any parameters that would have been passed to the real function (each is passed as a separate parameter to the magic function).

For example:

window.opera.defineMagicFunction(
	  'getLayer',
	  function ( oRealFunc, oThis, oParam1, oParam2 ) {
	    return oParam1.getElementById('oParam2').style;
	  }
	);

This example overrides a function 'f'. If the 'this' object refers to the window object, it returns false. Otherwise it just runs the real function instead:

window.opera.defineMagicFunction(
	  'f',
	  function( real, thisObject ) {
	    if( thisObject == window ) {
	      return false;
	    } else {
	      return real.apply( thisObject, arguments.slice(2) );
	    }
	  }
	);

window.opera.addEventListener

This is the generic method used to add listeners for User JavaScript events. When an event is detected, the event handler is passed a UserJSEvent object (which is also available through window.event). In addition to the usual event properties, the UserJSEvent object may also populate the 'element', 'event', 'listener', 'eventCancelled', 'propagationStopped', 'source' and 'returnValue' properties, depending on what type of event was being detected. Some events can be cancelled using preventDefault, and this may be used to prevent the script or event handler from being executed.

Listeners for the User JavaScript events can be added almost anywhere within a User JavaScript file. Listeners can not be added by the handler functions for regular events, or by scripts activated by timers. The following events can be detected:

BeforeExternalScript: Fired when a SCRIPT element with a SRC attribute is encountered. The script element is available as the element attribute of the UserJSEvent. If cancelled, the external source is not loaded and the script element is not executed. In addition, if it is cancelled, the BeforeScript event will not fire.
BeforeScript: Fired before a SCRIPT element is executed. The script element is available as the element attribute of the UserJSEvent. The content of the script is available as the text property of the script element, and is also writable: UserJSEvent.element.text = UserJSEvent.element.text.replace(/!=\s*null/,''); The BeforeScript event is fired for inline scripts as well as external scripts, including scripts with a type that Opera normally does not execute (such as VBScript). If cancelled, the script element is not executed.
AfterScript: Fired after a SCRIPT element has finished executing. The script element is available as the element attribute of the UserJSEvent.
BeforeEvent: Fired before a regular event is fired, regardless of whether such an event would be handled by any event handlers. The regular event is available as the event attribute of the UserJSEvent. If cancelled, the regular event is not fired, its default action is performed, and any associated BeforeEventListener events are not fired.
BeforeEvent.type: Like BeforeEvent, but fired only for events of the specified type (for example, BeforeEvent.click). In Opera 8, if any listeners are registered for a matching BeforeEvent.type event, no BeforeEvent event is fired. In Opera 9, both will fire.
AfterEvent: Fired after a regular event has been fired and handled but before its default action has been performed. The regular event is available as the event attribute of the UserJSEvent. If cancelled, any attempts by a regular event handler to cancel the regular event will be ignored. The UserJSEvent object will also have the eventCancelled property, that will be set to true if any regular event handlers have cancelled the event.
AfterEvent.type: Like AfterEvent, but fired only for events of the specified type (for example, AfterEvent.click). In Opera 8, if any listeners are registered for a matching AfterEvent.type event, no AfterEvent event is fired. In Opera 9, both will fire.
BeforeEventListener: Fired before a listener for a regular event is called. The regular event is available as the event attribute of the UserJSEvent, and the listener to be called is available as the listener attribute of the UserJSEvent. If cancelled, the regular event listener will not be called.
BeforeEventListener.type: Like BeforeEventListener, but fired only for events of the specified type (for example, BeforeEventListener.click). In Opera 8, if any listeners are registered for a matching BeforeEventListener.type event, no BeforeEventListener event is fired. In Opera 9, both will fire.
AfterEventListener: Fired after a listener for regular events is called. The regular event is available as the event attribute of the UserJSEvent, and the listener to be called is available as the listener attribute of the UserJSEvent. If cancelled, any attempts by a regular event handler to cancel the regular event propagation will be ignored. The UserJSEvent object will also have the propagationStopped property, that will be set to true if any regular event handlers have cancelled the event propagation.
AfterEventListener.type: Like AfterEventListener, but fired only for events of the specified type (for example, AfterEventListener.click). In Opera 8, if any listeners are registered for a matching AfterEventListener.type event, no AfterEventListener event is fired. In Opera 9, both will fire.
BeforeJavascriptURL: Fired before a javascript: URL is executed. The JavaScript code to be executed (everything after the 'javascript:' in the URL) is available as the source attribute of the UserJSEvent, and is also writable. If cancelled, the javascript: URL is not executed.
AfterJavascriptURL: Fired after a javascript: URL is executed. The JavaScript code that was executed (everything after the 'javascript:' in the URL) is available as the source attribute of the UserJSEvent, and any value returned by that code is available as the returnValue attribute of the UserJSEvent. The returnValue is also writable. If cancelled, any returned value will not be used as the source of a new page.

window.opera.removeEventListener

This can be used to remove User JavaScript event listeners that were added using window.opera.addEventListener. This cannot be used if the event listener was added as an anonymous function. For further details, see the W3C DOM Level 2 Events - Event registration interfaces specification.

window.opera.setOverrideHistoryNavigationMode

This method can be used by User JavaScripts to set what history navigation mode Opera should use for the current document. It accepts one parameter:

Mode: One of 'automatic', 'compatible', or 'fast'.

See the knowledge base article for more details.

window.opera.getOverrideHistoryNavigationMode

Retrieves the last value of history navigation mode that was set for the current document using setOverrideHistoryNavigationMode. Defaults to 'automatic'.

The UserJSEvent object

This is the event object passed to User JavaScript event handler functions (it is also available through window.event). As well as the usual event object properties, it has a few that are specific to User JavaScript events. While many of the properties serve little purpose in User JavaScript (for example, the currentTarget, srcElement, and target properties all reference window.opera), the following properties and methods are the most useful:

element: Object, readonly: the script element. All the usual DOM methods are available, such as getAttribute and setAttribute. Available for 'BeforeExternalScript', 'BeforeScript', and 'AfterScript' events.
element.text: String, read-write: the script that is about to be executed. Available for 'BeforeScript' and 'AfterScript' events. Unlike normal page scripts, User JavaScripts are allowed to see the script source from any domain, not just those that are served from the same domain as the current page.
event: Object, readonly: the regular event object. Available for 'BeforeEvent' and 'AfterEvent' events.
eventCancelled: Boolean, readonly: says if an event handler has cancelled the event. Available for 'AfterEvent' events.
listener: Function, readonly: a reference to the event handler function. Available for 'BeforeEventListener' and 'AfterEventListener' events.
preventDefault: Function, readonly: Prevents the default action, for example; prevent a script from being executed, prevent an event from firing, or prevent an event handler from blocking a form submission. Available for all events, but has no effect with 'AfterScript' events.
propagationStopped: Boolean, read-write: says if an event handler has stopped propagation of the event. Available for 'AfterEventListener' events.
returnValue: String, read-write: the value returned by the script. Available for 'AfterJavascriptURL' events.
source: String, read-write: the script that is about to execute or has been executed. Available for 'BeforeJavascriptURL' and 'AfterJavascriptURL' events.
type: String, readonly: the type of the event that was detected; for example: 'BeforeJavascriptURL'. Available for all events.

Opera