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

chrome/common/extensions/api/declarative_content.json

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 [
   {
     "namespace": "declarativeContent",
     "description": "Use the <code>chrome.declarativeContent</code> API to take actions depending on the content of a page, without requiring permission to read the page's content.",
     "types": [
       {
@@ skipping 30 matching lines @@
       {
         "id": "ShowPageAction",
         "description": "Declarative event action that shows the extension's $(ref:pageAction page action) while the corresponding conditions are met.  This action can be used without <a href=\"declare_permissions#host-permissions\">host permissions</a>, but the extension must have a page action.  If the extension takes the <a href=\"activeTab.html\">activeTab</a> permission, a click on the page action will grant access to the active tab.",
         "type": "object",
         "properties": {
           "instanceType": {
             "type": "string", "enum": ["declarativeContent.ShowPageAction"],
             "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": [
     ],
     "events": [
       {
         "name": "onPageChanged",
         "options": {
           "supportsListeners": false,
           "supportsRules": true,
           "conditions": ["declarativeContent.PageStateMatcher"],
           "actions": [
             "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"
+          ]
+        }
       }
     ]
   }
 ]