Re-commit "Add new user script injection point:

document_idle."

Original code review: http://codereview.chromium.org/339064

BUG=26126
TBR=rafaelw@chromium.org

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@30796 0039d316-1c4b-4281-b951-d872f2087c98

7 files changed, 49 insertions, 6 deletions

diff --git a/chrome/common/extensions/docs/content_scripts.html b/chrome/common/extensions/docs/content_scripts.html
index 51beb4d..feba6ba 100644
--- a/chrome/common/extensions/docs/content_scripts.html
+++ b/chrome/common/extensions/docs/content_scripts.html
@@ -346,7 +346,24 @@ learn about the
   <tr>
     <td>run_at</td>
     <td>string</td>
-    <td>Optional. Controls when the files in <code>js</code> are injected. Can be <code>"document_start"</code> or <code>"document_end"</code>. Defaults to <code>"document_end"</code>. In the case of <code>"document_start"</code>, the files are injected after any files from <code>"css"</code>, but before any other DOM is constructed or any other script is run. In the case of <code>"document_end"</code>, the files are injected after the DOM is complete, but before subresources like images and frames have necessarily loaded.</td>
+    <td>Optional. Controls when the files in <code>js</code> are injected. Can be <code>"document_start"</code>, <code>"document_end"</code>, or <code>"document_idle"</code>. Defaults to <code>"document_idle"</code>.
+    
+    <br><br>
+    
+    In the case of <code>"document_start"</code>, the files are injected after any files from <code>"css"</code>, but before any other DOM is constructed or any other script is run.
+    
+    <br><br>
+    
+    In the case of <code>"document_end"</code>, the files are injected immediately after the DOM is complete, but before subresources like images and frames have loaded.
+    
+    <br><br>
+    
+    In the case of <code>"document_idle"</code>, the browser chooses a time to inject scripts between <code>"document_end"</code> and immediately after the <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#handler-onload">window.onload</a></code> event fires. The exact moment of injection depends on how complex the document is and how long it is taking to load, and is optimized for page load speed.
+    
+    <br><br>
+    
+    <b>NOTE:</b> In <code>document_idle</code>, content scripts may not necessarily receive the window.onload event, because they may run after it has
+    already fired. In most cases, listening for the onload event is unnecessary for content scripts running at <code>document_idle</code> because they are guaranteed to run after the DOM is complete. If your script definitely needs to run after <code>window.onload</code> you can check if it has already fired by using the <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#dom-document-readystate">document.readyState</a></code> property.</td>
   </tr>
 </tbody></table>
 
diff --git a/chrome/common/extensions/docs/static/content_scripts.html b/chrome/common/extensions/docs/static/content_scripts.html
index cbd738f..9f1edf1 100644
--- a/chrome/common/extensions/docs/static/content_scripts.html
+++ b/chrome/common/extensions/docs/static/content_scripts.html
@@ -104,7 +104,24 @@ learn about the
   <tr>
     <td>run_at</td>
     <td>string</td>
-    <td>Optional. Controls when the files in <code>js</code> are injected. Can be <code>"document_start"</code> or <code>"document_end"</code>. Defaults to <code>"document_end"</code>. In the case of <code>"document_start"</code>, the files are injected after any files from <code>"css"</code>, but before any other DOM is constructed or any other script is run. In the case of <code>"document_end"</code>, the files are injected after the DOM is complete, but before subresources like images and frames have necessarily loaded.</td>
+    <td>Optional. Controls when the files in <code>js</code> are injected. Can be <code>"document_start"</code>, <code>"document_end"</code>, or <code>"document_idle"</code>. Defaults to <code>"document_idle"</code>.
+    
+    <br><br>
+    
+    In the case of <code>"document_start"</code>, the files are injected after any files from <code>"css"</code>, but before any other DOM is constructed or any other script is run.
+    
+    <br><br>
+    
+    In the case of <code>"document_end"</code>, the files are injected immediately after the DOM is complete, but before subresources like images and frames have loaded.
+    
+    <br><br>
+    
+    In the case of <code>"document_idle"</code>, the browser chooses a time to inject scripts between <code>"document_end"</code> and immediately after the <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#handler-onload">window.onload</a></code> event fires. The exact moment of injection depends on how complex the document is and how long it is taking to load, and is optimized for page load speed.
+    
+    <br><br>
+    
+    <b>NOTE:</b> In <code>document_idle</code>, content scripts may not necessarily receive the window.onload event, because they may run after it has
+    already fired. In most cases, listening for the onload event is unnecessary for content scripts running at <code>document_idle</code> because they are guaranteed to run after the DOM is complete. If your script definitely needs to run after <code>window.onload</code> you can check if it has already fired by using the <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#dom-document-readystate">document.readyState</a></code> property.</td>
   </tr>
 </table>
 
diff --git a/chrome/common/extensions/extension.cc b/chrome/common/extensions/extension.cc
index 429dfb5..c617232 100644
--- a/chrome/common/extensions/extension.cc
+++ b/chrome/common/extensions/extension.cc
@@ -208,6 +208,8 @@ bool Extension::LoadUserScriptHelper(const DictionaryValue* content_script,
       result->set_run_location(UserScript::DOCUMENT_START);
     } else if (run_location == values::kRunAtDocumentEnd) {
       result->set_run_location(UserScript::DOCUMENT_END);
+    } else if (run_location == values::kRunAtDocumentIdle) {
+      result->set_run_location(UserScript::DOCUMENT_IDLE);
     } else {
       *error = ExtensionErrorUtils::FormatErrorMessage(errors::kInvalidRunAt,
           IntToString(definition_index));
diff --git a/chrome/common/extensions/extension_constants.cc b/chrome/common/extensions/extension_constants.cc
index 8259009..59e7c14 100644
--- a/chrome/common/extensions/extension_constants.cc
+++ b/chrome/common/extensions/extension_constants.cc
@@ -52,6 +52,7 @@ const wchar_t* kOptionsPage = L"options_page";
 namespace extension_manifest_values {
 const char* kRunAtDocumentStart = "document_start";
 const char* kRunAtDocumentEnd = "document_end";
+const char* kRunAtDocumentIdle = "document_idle";
 const char* kPageActionTypeTab = "tab";
 const char* kPageActionTypePermanent = "permanent";
 }  // namespace extension_manifest_values
diff --git a/chrome/common/extensions/extension_constants.h b/chrome/common/extensions/extension_constants.h
index 7f44bf6..b7826a7 100644
--- a/chrome/common/extensions/extension_constants.h
+++ b/chrome/common/extensions/extension_constants.h
@@ -54,6 +54,7 @@ namespace extension_manifest_keys {
 namespace extension_manifest_values {
   extern const char* kRunAtDocumentStart;
   extern const char* kRunAtDocumentEnd;
+  extern const char* kRunAtDocumentIdle;
   extern const char* kPageActionTypeTab;
   extern const char* kPageActionTypePermanent;
 }  // namespace extension_manifest_values
diff --git a/chrome/common/extensions/user_script.h b/chrome/common/extensions/user_script.h
index 28b3aae..bdd1e54 100644
--- a/chrome/common/extensions/user_script.h
+++ b/chrome/common/extensions/user_script.h
@@ -28,6 +28,10 @@ class UserScript {
                      // anything else happens.
     DOCUMENT_END,  // After the entire document is parsed. Same as
                    // DOMContentLoaded.
+    DOCUMENT_IDLE,  // Sometime after DOMContentLoaded, as soon as the document
+                    // is "idle". Currently this uses the simple heuristic of:
+                    // min(DOM_CONTENT_LOADED + TIMEOUT, ONLOAD), but no
+                    // particular injection point is guaranteed.
 
     RUN_LOCATION_LAST  // Leave this as the last item.
   };
@@ -88,9 +92,10 @@ class UserScript {
 
   typedef std::vector<File> FileList;
 
-  // Constructor. Default the run location to document end, which is like
-  // Greasemonkey and probably more useful for typical scripts.
-  UserScript() : run_location_(DOCUMENT_END) {}
+  // Constructor. Default the run location to document idle, which is similar
+  // to Greasemonkey but should result in better page load times for fast-
+  // loading pages.
+  UserScript() : run_location_(DOCUMENT_IDLE) {}
 
   // The place in the document to run the script.
   RunLocation run_location() const { return run_location_; }
diff --git a/chrome/common/extensions/user_script_unittest.cc b/chrome/common/extensions/user_script_unittest.cc
index b171f4e..58ef77e 100644
--- a/chrome/common/extensions/user_script_unittest.cc
+++ b/chrome/common/extensions/user_script_unittest.cc
@@ -122,5 +122,5 @@ TEST(UserScriptTest, Pickle) {
 
 TEST(UserScriptTest, Defaults) {
   UserScript script;
-  ASSERT_EQ(UserScript::DOCUMENT_END, script.run_location());
+  ASSERT_EQ(UserScript::DOCUMENT_IDLE, script.run_location());
 }