src/chrome/common/extensions/docs/templates/intros/events.html

   1 <p>
   2 An <code>Event</code> is an object
   3 that allows you to be notified
   4 when something interesting happens.
   5 Here's an example of using the
   6 <code>chrome.alarms.onAlarm</code> event
   7 to be notified whenever an alarm has elapsed:
   8 </p>
   9
  10 <pre>
  11 chrome.alarms.onAlarm.<b>addListener(function(</b>alarm<b>) {</b>
  12   appendToLog('alarms.onAlarm --'
  13               + ' name: '          + alarm.name
  14               + ' scheduledTime: ' + alarm.scheduledTime);
  15 <b>});</b>
  16 </pre>
  17
  18 <p>
  19 As the example shows,
  20 you register for notification using <code>addListener()</code>.
  21 The argument to <code>addListener()</code>
  22 is always a function that you define to handle the event,
  23 but the parameters to the function depend on
  24 which event you're handling.
  25 Checking the documentation for
  26 $(ref:alarms.onAlarm),
  27 you can see that the function has a single parameter:
  28 an $(ref:alarms.Alarm) object
  29 that has details about the elapsed alarm.
  30 </p>
  31
  32 Example APIs using Events:
  33 $(ref:alarms),
  34 {{?is_apps}}
  35 $(ref:app.runtime),
  36 $(ref:app.window),
  37 {{/is_apps}}
  38 $(ref:i18n),
  39 $(ref:identity),
  40 $(ref:runtime).
  41 Most <a href="api_index">chrome APIs</a> do.
  42
  43 {{^is_apps}}
  44 <div class="doc-family extensions">
  45 <h2 id="declarative">Declarative Event Handlers</h2>
  46
  47 <p>
  48 The declarative event handlers provide a means to define rules consisting of
  49 declarative conditions and actions. Conditions are evaluated in the browser
  50 rather than the JavaScript engine which reduces roundtrip latencies and allows
  51 for very high efficiency.
  52 </p>
  53
  54 <p>Declarative event handlers are used for example in the <a
  55 href="declarativeWebRequest">Declarative Web Request API</a> and <a
  56 href="declarativeContent">Declarative Content API</a>. This page describes
  57 the underlying concepts of all declarative event handlers.
  58 </p>
  59
  60 <h3 id="rules">Rules</h3>
  61
  62 <p>The simplest possible rule consists of one or more conditions and one or more
  63 actions:</p>
  64 <pre>
  65 var rule = {
  66   conditions: [ /* my conditions */ ],
  67   actions: [ /* my actions */ ]
  68 };
  69 </pre>
  70
  71 <p>If any of the conditions is fulfilled, all actions are executed.</p>
  72
  73 <p>In addition to conditions and actions you may give each rule an identifier,
  74 which simplifies unregistering previously registered rules, and a priority to
  75 define precedences among rules. Priorities are only considered if rules conflict
  76 each other or need to be executed in a specific order. Actions are executed in
  77 descending order of the priority of their rules.</p>
  78
  79 <pre>
  80 var rule = {
  81   id: "my rule",  // optional, will be generated if not set.
  82   priority: 100,  // optional, defaults to 100.
  83   conditions: [ /* my conditions */ ],
  84   actions: [ /* my actions */ ]
  85 };
  86 </pre>
  87
  88 <h3 id="eventobjects">Event objects</h3>
  89
  90 <p>
  91 <a href="events">Event objects</a> may support rules. These event objects
  92 don't call a callback function when events happen but test whether any
  93 registered rule has at least one fulfilled condition and execute the actions
  94 associated with this rule. Event objects supporting the declarative API have
  95 three relevant methods: $(ref:events.Event.addRules),
  96 $(ref:events.Event.removeRules), and
  97 $(ref:events.Event.getRules).
  98 </p>
  99
 100 <h3 id="addingrules">Adding rules</h3>
 101
 102 <p>
 103 To add rules call the <code>addRules()</code> function of the event object. It
 104 takes an array of rule instances as its first parameter and a callback function
 105 that is called on completion.
 106 </p>
 107
 108 <pre>
 109 var rule_list = [rule1, rule2, ...];
 110 function addRules(rule_list, function callback(details) {...});
 111 </pre>
 112
 113 <p>
 114 If the rules were inserted successfully, the <code>details</code> parameter
 115 contains an array of inserted rules appearing in the same order as in the passed
 116 <code>rule_list</code> where the optional parameters <code>id</code> and
 117 <code>priority</code> were filled with the generated values. If any rule is
 118 invalid, e.g., because it contained an invalid condition or action, none of the
 119 rules are added and the
 120   $(ref:runtime.lastError) variable is set when
 121 the callback function is called. Each rule in <code>rule_list</code> must
 122 contain a unique identifier that is not currently used by another rule or an
 123 empty identifier.
 124 </p>
 125
 126 <p class="note">
 127 <strong>Note:</strong> Rules are persistent across browsing sessions. Therefore,
 128 you should install rules during extension installation time using the
 129 <code>$(ref:runtime.onInstalled)</code>
 130 event. Note that this event is also triggered when an extension is updated.
 131 Therefore, you should first clear previously installed rules and then register
 132 new rules.
 133 </p>
 134
 135 <h3 id="removingrules">Removing rules</h3>
 136
 137 <p>
 138 To remove rules call the <code>removeRules()</code> function. It accepts an
 139 optional array of rule identifiers as its first parameter and a callback
 140 function as its second parameter.
 141 </p>
 142
 143 <pre>
 144 var rule_ids = ["id1", "id2", ...];
 145 function removeRules(rule_ids, function callback() {...});
 146 </pre>
 147
 148 <p>
 149 If <code>rule_ids</code> is an array of identifiers, all rules having
 150 identifiers listed in the array are removed. If <code>rule_ids</code> lists an
 151 identifier, that is unknown, this identifier is silently ignored. If
 152 <code>rule_ids</code> is <code>undefined</code>, all registered rules of this
 153 extension are removed. The <code>callback()</code> function is called when the
 154 rules were removed.
 155 </p>
 156
 157 <h3 id="retrievingrules">Retrieving rules</h3>
 158
 159 <p>
 160 To retrieve a list of currently registered rules, call the
 161 <code>getRules()</code> function. It accepts an optional array of rule
 162 identifiers with the same semantics as <code>removeRules</code> and a callback
 163 function.
 164 </p>
 165
 166 <pre>
 167 var rule_ids = ["id1", "id2", ...];
 168 function getRules(rule_ids, function callback(details) {...});
 169 </pre>
 170
 171 <p>
 172 The <code>details</code> parameter passed to the <code>callback()</code> function
 173 refers to an array of rules including filled optional parameters.
 174 </p>
 175
 176 <h3 id="performance">Performance</h3>
 177
 178 <p>
 179 To achieve maximum performance, you should keep the following guidelines in
 180 mind:
 181 <ul>
 182   <li><p>Register and unregister rules in bulk. After each
 183   registration or unregistration, Chrome needs to update internal data
 184   structures. This update is an expensive operation.</p>
 185   <p>Instead of</p>
 186   <pre>
 187 var rule1 = {...};
 188 var rule2 = {...};
 189 chrome.declarativeWebRequest.onRequest.addRules([rule1]);
 190 chrome.declarativeWebRequest.onRequest.addRules([rule2]);</pre>
 191   <p>prefer to write</p>
 192   <pre>
 193 var rule1 = {...};
 194 var rule2 = {...};
 195 chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);</pre>
 196   <li>Prefer substring matching over matching using regular expressions in a
 197   $(ref:events.UrlFilter).  Substring based matching is extremely fast.
 198   <p>Instead of</p>
 199   <pre>
 200 var match = new chrome.declarativeWebRequest.RequestMatcher({
 201     url: {urlMatches: "example.com/[^?]*foo" } });</pre>
 202   <p>prefer to write</p>
 203   <pre>
 204 var match = new chrome.declarativeWebRequest.RequestMatcher({
 205     url: {hostSuffix: "example.com", pathContains: "foo"} });</pre>
 206   <li>If you have many rules that all share the same actions, you may merge
 207   the rules into one because rules trigger their actions as soon as a single
 208   condition is fulfilled. This speeds up the matching and reduces memory
 209   consumption for duplicate action sets.
 210   <p>Instead of</p>
 211   <pre>
 212 var condition1 = new chrome.declarativeWebRequest.RequestMatcher({
 213     url: { hostSuffix: 'example.com' } });
 214 var condition2 = new chrome.declarativeWebRequest.RequestMatcher({
 215     url: { hostSuffix: 'foobar.com' } });
 216 var rule1 = { conditions: [condition1],
 217               actions: [new chrome.declarativeWebRequest.CancelRequest()]};
 218 var rule2 = { conditions: [condition2],
 219               actions: [new chrome.declarativeWebRequest.CancelRequest()]};
 220 chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);</pre>
 221   <p>prefer to write</p>
 222   <pre>
 223 var rule = { conditions: [condition1, condition2],
 224              actions: [new chrome.declarativeWebRequest.CancelRequest()]};
 225 chrome.declarativeWebRequest.onRequest.addRules([rule]);</pre>
 226 </ul>
 227 </p>
 228 </div>
 229 {{/is_apps}}
 230
 231 {{^is_apps}}
 232 <div class="doc-family extensions">
 233 <h2 id="filtered">Filtered events</h2>
 234
 235 <p>Filtered events are a mechanism that allows listeners to specify a subset of
 236 events that they are interested in. A listener that makes use of a filter won't
 237 be invoked for events that don't pass the filter, which makes the listening
 238 code more declarative and efficient - an <a href="event_pages">event
 239   page</a> page need not be woken up to handle events it doesn't care
 240 about.</p>
 241
 242 <p>Filtered events are intended to allow a transition from manual filtering
 243 code like this:</p>
 244
 245 <pre>
 246 chrome.webNavigation.onCommitted.addListener(function(e) {
 247   if (hasHostSuffix(e.url, 'google.com') ||
 248       hasHostSuffix(e.url, 'google.com.au')) {
 249     // ...
 250   }
 251 });
 252 </pre>
 253
 254 <p>into this:</p>
 255
 256 <pre>
 257 chrome.webNavigation.onCommitted.addListener(function(e) {
 258   // ...
 259 }, {url: [{hostSuffix: 'google.com'},
 260           {hostSuffix: 'google.com.au'}]});
 261 </pre>
 262
 263 <p>Events support specific filters that are meaningful to that event. The list
 264 of filters that an event supports will be listed in the documentation for that
 265 event in the "filters" section.</p>
 266
 267 <p>When matching URLs (as in the example above), event filters support the same
 268 URL matching capabilities as expressible with a
 269   $(ref:events.UrlFilter), except for scheme and port
 270 matching.</p>
 271
 272 </div>
 273 {{/is_apps}}