| OLD | NEW |
|---|
| (Empty) |
| 1 <!-- BEGIN AUTHORED CONTENT --> | |
| 2 | |
| 3 <h2 id="notes">Notes</h2> | |
| 4 | |
| 5 <p> | |
| 6 The Declarative API is a framework to define rules consisting of declarative | |
| 7 conditions and actions. Conditions are evaluated in the browser rather than the | |
| 8 JavaScript engine which reduces roundtrip latencies and allows for very high | |
| 9 efficiency. | |
| 10 </p> | |
| 11 | |
| 12 </p>The Declarative API is an abstract foundation for the <a | |
| 13 href="declarativeWebRequest.html">Declarative Web Request API</a> and | |
| 14 possibly further extension APIs in the future. This page describes the | |
| 15 underlying concepts of all Declarative APIs. | |
| 16 </p> | |
| 17 | |
| 18 <h2 id="manifest">Manifest</h2> | |
| 19 | |
| 20 <p> | |
| 21 You must declare the "declarative" permission in your extension's manifest | |
| 22 to use APIs that are based on this API. | |
| 23 </p> | |
| 24 | |
| 25 <pre>{ | |
| 26 "name": "My extension", | |
| 27 ... | |
| 28 <b> "permissions": [ | |
| 29 "declarative", | |
| 30 ]</b>, | |
| 31 ... | |
| 32 }</pre> | |
| 33 | |
| 34 <h2 id="rules">Rules</h2> | |
| 35 | |
| 36 <p>The simplest possible rule consists of one or more conditions and one or more | |
| 37 actions:</p> | |
| 38 <pre> | |
| 39 var rule = { | |
| 40 conditions: [ /* my conditions */ ], | |
| 41 actions: [ /* my actions */ ] | |
| 42 }; | |
| 43 </pre> | |
| 44 | |
| 45 <p>If any of the conditions is fulfilled, all actions are executed.</p> | |
| 46 | |
| 47 <p>In addition to conditions and actions you may give each rule an identifier, | |
| 48 which simplifies unregistering previously registered rules, and a priority to | |
| 49 define precedences among rules. Priorities are only considered if rules conflict | |
| 50 each other or need to be executed in a specific order.</p> | |
| 51 | |
| 52 <pre> | |
| 53 var rule = { | |
| 54 id: "my rule", // optional, will be generated if not set. | |
| 55 priority: 100, // optional, defaults to 100. | |
| 56 conditions: [ /* my conditions */ ], | |
| 57 actions: [ /* my actions */ ] | |
| 58 }; | |
| 59 </pre> | |
| 60 | |
| 61 <h2 id="eventobjects">Event objects</h2> | |
| 62 | |
| 63 <p> | |
| 64 <a href="events.html">Event objects</a> may support rules. These event objects | |
| 65 don't call a callback function when events happer but test whether any | |
| 66 registered rule has at least one fulfilled condition and execute the actions | |
| 67 associated with this rule. Event objects supporting the declarative API have | |
| 68 three relevant methods: <a href="#method-addRules"><code>addRules()</code></a>, | |
| 69 <a href="#method-removeRules"><code>removeRules()</code></a>, and | |
| 70 <a href="#method-getRules"><code>getRules()</code></a>. | |
| 71 </p> | |
| 72 | |
| 73 <h3 id="addingrules">Adding rules</h3> | |
| 74 | |
| 75 <p> | |
| 76 To add rules call the <code>addRules()</code> function of the event object. It | |
| 77 takes an array of rule instances as its first parameter and a callback function | |
| 78 that is called on completion. | |
| 79 </p> | |
| 80 | |
| 81 <pre> | |
| 82 var rule_list = [rule1, rule2, ...]; | |
| 83 function addRules(rule_list, function callback(details) {...}); | |
| 84 </pre> | |
| 85 | |
| 86 <p> | |
| 87 If the rules were inserted successfully, the <code>details</code> parameter | |
| 88 contains an array of inserted rules appearing in the same order as in the passed | |
| 89 <code>rule_list</code> where the optional parameters <code>id</code> and | |
| 90 <code>priority</code> were filled with the generated values. If any rule is | |
| 91 invalid, e.g., because it contained an invalid condition or action, none of the | |
| 92 rules are added and the <a | |
| 93 href="extension.html#property-lastError">lastError</a> variable is set when | |
| 94 the callback function is called. Each rule in <code>rule_list</code> must | |
| 95 contain a unique identifier that is not currently used by another rule or an | |
| 96 empty identifier. | |
| 97 </p> | |
| 98 | |
| 99 <h3 id="removingrules">Removing rules</h3> | |
| 100 | |
| 101 <p> | |
| 102 To remove rules call the <code>removeRules()</code> function. It accepts an | |
| 103 optional array of rule identifiers as its first parameter and a callback | |
| 104 function as its second parameter. | |
| 105 </p> | |
| 106 | |
| 107 <pre> | |
| 108 var rule_ids = ["id1", "id2", ...]; | |
| 109 function removeRules(rule_ids, function callback() {...}); | |
| 110 </pre> | |
| 111 | |
| 112 <p> | |
| 113 If <code>rule_ids</code> is an array of identifiers, all rules having | |
| 114 identifiers listed in the array are removed. If <code>rule_ids</code> lists an | |
| 115 identifier, that is unknown, this identifier is silently ignored. If | |
| 116 <code>rule_ids</code> is <code>undefined</code>, all registered rules of this | |
| 117 extension are removed. The <code>callback()</code> function is called when the | |
| 118 rules were removed. | |
| 119 </p> | |
| 120 | |
| 121 <h3 id="retrievingrules">Retrieving rules</h3> | |
| 122 | |
| 123 <p> | |
| 124 To retrieve a list of currently registered rules, call the | |
| 125 <code>getRules()</code> function. It accepts an optional array of rule | |
| 126 identifiers with the same semantics as <code>removeRules</code> and a callback | |
| 127 function. | |
| 128 <p> | |
| 129 | |
| 130 <pre> | |
| 131 var rule_ids = ["id1", "id2", ...]; | |
| 132 function getRules(rule_ids, function callback(details) {...}); | |
| 133 </pre> | |
| 134 | |
| 135 <p> | |
| 136 The <code>details</code> parameter passed to the <code>calback()</code> function | |
| 137 refers to an array of rules including filled optional parameters. | |
| 138 </p> | |
| 139 | |
| 140 <!-- END AUTHORED CONTENT --> | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 10392127:
Move declarative API into events API (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src