Prepare declarativeContent API for new script injection feature. Added Javascript types and functio…

chrome/common/extensions/api/declarative_content.json

Index: chrome/common/extensions/api/declarative_content.json
diff --git a/chrome/common/extensions/api/declarative_content.json b/chrome/common/extensions/api/declarative_content.json
index 7c383b58e2488cde704d5bc0a362beb348feebd4..507f3b71e0c95e98490a357b4298d0100bec8f1d 100644
--- a/chrome/common/extensions/api/declarative_content.json
+++ b/chrome/common/extensions/api/declarative_content.json
@@ -48,6 +48,29 @@
             "nodoc": true
           }
         }
+      },
+      {
+        "id": "RequestContentScript",
+        "description": "Declarative event action that injects a content script.",
+        "type": "object",
+        "properties": {
+          "css": {
+            "type": "array",
+            "optional": true,
+            "description": "Names of CSS files to be injected as a part of content script.",
+            "items": { "type": "string" }
+          },
+          "js": {
+            "type": "array",
+            "optional": true,
+            "description": "Names of Javascript files to be injected as a part of content script.",
+            "items": { "type": "string" }
+          },
+          "instanceType": {
+            "type": "string", "enum": ["declarativeContent.RequestContentScript"],
+            "nodoc": true
+          }
+        }
       }
     ],
     "functions": [
@@ -63,6 +86,42 @@
             "declarativeContent.ShowPageAction"
           ]
         }
+      },
+      {
+        "name": "onDocumentStart",

[Jeffrey Yasskin, 2014/06/27 22:03:41]

I'm skeptical of adding three new events for this, and especially of treating
them all separately in the browser code. Semantically, one way to view the
run_at restriction might be to think of it as another predicate on the
PageStateMatcher: minLoadPhase ∈ ['document_start', 'document_end',
'document_idle']. We could have this default to 'document_idle' to match run_at,
although we wouldn't really want it to slow down the appearance of a page
action.

[Mark Dittmer, 2014/06/30 11:50:35]

Ben and I discussed this and we both felt that the separate events are more in
keeping with an event-based API. Having a predicate that denotes the "when"
(rather than the choice of event denoting this) feels odd in an events-based
approach. Is the concern memory consumption for managing the rules registries,
or do you feel that developers will be confused/overwhelmed by the number of
events?

Aside: I think "minLoadPhase" would be a misleading choice. We skip scripts that
missed document_start or document_end on the basis that multiple scripts with
different insertion times (but from the same extension) may expect that they not
be inserted out of order.

+        "description": "Declarative event that fires just before the document object model is constructed.",
+        "options": {
+          "supportsListeners": false,
+          "supportsRules": true,
+          "conditions": ["declarativeContent.PageStateMatcher"],
+          "actions": [
+            "declarativeContent.RequestContentScript"
+          ]
+        }
+      },
+      {
+        "name": "onDocumentEnd",
+        "description": "Declarative event that fires just after the document object model is constructed.",
+        "options": {
+          "supportsListeners": false,
+          "supportsRules": true,
+          "conditions": ["declarativeContent.PageStateMatcher"],
+          "actions": [
+            "declarativeContent.RequestContentScript"
+          ]
+        }
+      },
+      {
+        "name": "onDocumentIdle",
+        "description": "Declarative event that fires sometime after the page has loaded. This event fires after onDocumentStart and onDocumentEnd, and is intended for performing actions that do not require precise timing.",
+        "options": {
+          "supportsListeners": false,
+          "supportsRules": true,
+          "conditions": ["declarativeContent.PageStateMatcher"],
+          "actions": [
+            "declarativeContent.RequestContentScript"
+          ]
+        }
       }
     ]
   }