Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the BSD License.
©2012 Google
An Event is an object
that allows you to be notified
when something interesting happens.
Here's an example of using the
chrome.tabs.onCreated event
to be notified whenever there's a new tab:
chrome.tabs.onCreated.addListener(function(tab) {
appendToLog('tabs.onCreated --'
+ ' window: ' + tab.windowId
+ ' tab: ' + tab.id
+ ' index: ' + tab.index
+ ' url: ' + tab.url);
});
As the example shows,
you register for notification using addListener().
The argument to addListener()
is always a function that you define to handle the event,
but the parameters to the function depend on
which event you're handling.
Checking the documentation for
chrome.tabs.onCreated,
you can see that the function has a single parameter:
a Tab object
that has details about the newly created tab.
The declarative event handlers provide a means to define rules consisting of declarative conditions and actions. Conditions are evaluated in the browser rather than the JavaScript engine which reduces roundtrip latencies and allows for very high efficiency.
Declarative event handlers are used for example in the Declarative Web Request API and possibly further extension APIs in the future. This page describes the underlying concepts of all declarative event handlers.
The simplest possible rule consists of one or more conditions and one or more actions:
var rule = {
conditions: [ /* my conditions */ ],
actions: [ /* my actions */ ]
};
If any of the conditions is fulfilled, all actions are executed.
In addition to conditions and actions you may give each rule an identifier, which simplifies unregistering previously registered rules, and a priority to define precedences among rules. Priorities are only considered if rules conflict each other or need to be executed in a specific order. Actions are executed in decendending order of the priority of their rules.
var rule = {
id: "my rule", // optional, will be generated if not set.
priority: 100, // optional, defaults to 100.
conditions: [ /* my conditions */ ],
actions: [ /* my actions */ ]
};
Event objects may support rules. These event objects
don't call a callback function when events happen but test whether any
registered rule has at least one fulfilled condition and execute the actions
associated with this rule. Event objects supporting the declarative API have
three relevant methods: addRules(),
removeRules(), and
getRules().
To add rules call the addRules() function of the event object. It
takes an array of rule instances as its first parameter and a callback function
that is called on completion.
var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});
If the rules were inserted successfully, the details parameter
contains an array of inserted rules appearing in the same order as in the passed
rule_list where the optional parameters id and
priority were filled with the generated values. If any rule is
invalid, e.g., because it contained an invalid condition or action, none of the
rules are added and the lastError variable is set when
the callback function is called. Each rule in rule_list must
contain a unique identifier that is not currently used by another rule or an
empty identifier.
Note: Rules are persistent across browsing sessions. Therefore,
you should install rules during extension installation time using the
chrome.runtime.onInstalled
event. Note that this event is also triggered when an extension is updated.
Therefore, you should first clear previously installed rules and then register
new rules.
To remove rules call the removeRules() function. It accepts an
optional array of rule identifiers as its first parameter and a callback
function as its second parameter.
var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});
If rule_ids is an array of identifiers, all rules having
identifiers listed in the array are removed. If rule_ids lists an
identifier, that is unknown, this identifier is silently ignored. If
rule_ids is undefined, all registered rules of this
extension are removed. The callback() function is called when the
rules were removed.
To retrieve a list of currently registered rules, call the
getRules() function. It accepts an optional array of rule
identifiers with the same semantics as removeRules and a callback
function.
var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(details) {...});
The details parameter passed to the calback() function
refers to an array of rules including filled optional parameters.
Filtered events are a mechanism that allows listeners to specify a subset of events that they are interested in. A listener that makes use of a filter won't be invoked for events that don't pass the filter, which makes the listening code more declarative and efficient - an event page page need not be woken up to handle events it doesn't care about.
Filtered events are intended to allow a transition from manual filtering code like this:
chrome.webNavigation.onCommitted.addListener(function(e) {
if (hasHostSuffix(e.url, 'google.com') ||
hasHostSuffix(e.url, 'google.com.au')) {
// ...
}
});
into this:
chrome.webNavigation.onCommitted.addListener(function(e) {
// ...
}, {url: [{hostSuffix: 'google.com'},
{hostSuffix: 'google.com.au'}]});
Events support specific filters that are meaningful to that event. The list of filters that an event supports will be listed in the documentation for that event in the "filters" section.
When matching URLs (as in the example above), event filters support the same URL matching capabilities as expressable with a UrlFilter, except for scheme and port matching.
Registers an event listener callback to an event.
Deregisters an event listener callback from an event.
Registers rules to handle events.
If you specify the callback parameter, it should specify a function that looks like this:
function(array of Rule rules) {...};
Returns currently registered rules.
The callback parameter should specify a function that looks like this:
function(array of Rule rules) {...};
Unregisters currently registered rules.
If you specify the callback parameter, it should specify a function that looks like this:
function() {...};