Move declarative API into events API

chrome/common/extensions/docs/static/events.html

Index: chrome/common/extensions/docs/static/events.html
diff --git a/chrome/common/extensions/docs/static/events.html b/chrome/common/extensions/docs/static/events.html
index dfb508955788688b1756ed2b046c1361d5dd9332..d734653141b2998b0b348845b629d8238bcae94e 100644
--- a/chrome/common/extensions/docs/static/events.html
+++ b/chrome/common/extensions/docs/static/events.html
@@ -46,3 +46,125 @@ bool hasListener(function callback(...))
 </pre>
 
 <!-- [PENDING: explain removeListener and hasListener] -->
+

[battre, 2012/05/09 16:28:08]

I have mostly just moved the text. It will need to be adapted to the new
context. I would do this in a separate CL.

+
+<h2 id="declarative">Declarative Event Handlers</h2>
+
+<p>
+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.
+</p>
+
+<p>Declarative event handlers are used for example in the <a
+  href="declarativeWebRequest.html">Declarative Web Request API</a> and possibly
+further extension APIs in the future. This page describes the underlying
+concepts of all declarative event handlers.
+</p>
+
+<h3 id="rules">Rules</h3>
+
+<p>The simplest possible rule consists of one or more conditions and one or more
+actions:</p>
+<pre>
+var rule = {
+  conditions: [ /* my conditions */ ],
+  actions: [ /* my actions */ ]
+};
+</pre>
+
+<p>If any of the conditions is fulfilled, all actions are executed.</p>
+
+<p>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.</p>
+
+<pre>
+var rule = {
+  id: "my rule",  // optional, will be generated if not set.
+  priority: 100,  // optional, defaults to 100.
+  conditions: [ /* my conditions */ ],
+  actions: [ /* my actions */ ]
+};
+</pre>
+
+<h3 id="eventobjects">Event objects</h3>
+
+<p>
+<a href="events.html">Event objects</a> may support rules. These event objects
+don't call a callback function when events happer 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: <a href="#method-addRules"><code>addRules()</code></a>,
+<a href="#method-removeRules"><code>removeRules()</code></a>, and
+<a href="#method-getRules"><code>getRules()</code></a>.
+</p>
+
+<h3 id="addingrules">Adding rules</h3>
+
+<p>
+To add rules call the <code>addRules()</code> 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.
+</p>
+
+<pre>
+var rule_list = [rule1, rule2, ...];
+function addRules(rule_list, function callback(details) {...});
+</pre>
+
+<p>
+If the rules were inserted successfully, the <code>details</code> parameter
+contains an array of inserted rules appearing in the same order as in the passed
+<code>rule_list</code> where the optional parameters <code>id</code> and
+<code>priority</code> 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 <a
+  href="extension.html#property-lastError">lastError</a> variable is set when
+the callback function is called. Each rule in <code>rule_list</code> must
+contain a unique identifier that is not currently used by another rule or an
+empty identifier.
+</p>
+
+<h3 id="removingrules">Removing rules</h3>
+
+<p>
+To remove rules call the <code>removeRules()</code> function. It accepts an
+optional array of rule identifiers as its first parameter and a callback
+function as its second parameter.
+</p>
+
+<pre>
+var rule_ids = ["id1", "id2", ...];
+function removeRules(rule_ids, function callback() {...});
+</pre>
+
+<p>
+If <code>rule_ids</code> is an array of identifiers, all rules having
+identifiers listed in the array are removed. If <code>rule_ids</code> lists an
+identifier, that is unknown, this identifier is silently ignored. If
+<code>rule_ids</code> is <code>undefined</code>, all registered rules of this
+extension are removed. The <code>callback()</code> function is called when the
+rules were removed.
+</p>
+
+<h3 id="retrievingrules">Retrieving rules</h3>
+
+<p>
+To retrieve a list of currently registered rules, call the
+<code>getRules()</code> function. It accepts an optional array of rule
+identifiers with the same semantics as <code>removeRules</code> and a callback
+function.
+<p>
+
+<pre>
+var rule_ids = ["id1", "id2", ...];
+function getRules(rule_ids, function callback(details) {...});
+</pre>
+
+<p>
+The <code>details</code> parameter passed to the <code>calback()</code> function
+refers to an array of rules including filled optional parameters.
+</p>