Extensions Docs Server: devtools API

chrome/common/extensions/docs/server2/templates/intros/devtools_inspectedWindow.html

Index: chrome/common/extensions/docs/server2/templates/intros/devtools_inspectedWindow.html
diff --git a/chrome/common/extensions/docs/server2/templates/intros/devtools_inspectedWindow.html b/chrome/common/extensions/docs/server2/templates/intros/devtools_inspectedWindow.html
new file mode 100644
index 0000000000000000000000000000000000000000..69741a474da890eec3b060041dcce9bb16325a97
--- /dev/null
+++ b/chrome/common/extensions/docs/server2/templates/intros/devtools_inspectedWindow.html
@@ -0,0 +1,97 @@
+<p>
+Use <code>chrome.devtools.inspectedWindow</code>
+to interact with the inspected window:
+obtain the tab ID for the inspected page,
+evaluate the code in the context of inspected window,
+reload the page,
+or obtain the list of resources within the page.
+</p><p>
+See <a href="devtools.html">DevTools APIs summary</a> for
+general introduction to using Developer Tools APIs.
+</p>
+
+<h2>Overview</h2>
+<p>
+The <a href="#property-tabId"><code>tabId</code></a> property
+provides the tab identifier that you can use with the
+<a href="tabs.html"><code>chrome.tabs.*</code></a> API calls.
+However, please note that <code>chrome.tabs.*</code> API is not
+exposed to the Developer Tools extension pages due to security considerations
+&mdash; you will need to pass the tab ID to the background page and invoke
+the <code>chrome.tabs.*</code> API functions from there.
+</p>
+<p>
+The <code>eval()</code> method provides the ability for extensions to execute
+JavaScript code in the context of the main frame of the inspected page.
+This method is powerful when used in the right context
+and dangerous when used inappropriately.
+Use the <code>chrome.tabs.executeScript()</code> method
+unless you need the specific functionality
+that the <code>eval()</code> method provides.
+</p>
+<p>Here are the main differences between the
+<code>eval()</code> and <code>chrome.tabs.executeScript()</code> methods:
+</p><ul>
+<li>The <code>eval()</code> method does not
+use an isolated world for the code being evaluated, so the JavaScript state
+of the inspected window is accessible to the code.
+Use this method when access to the JavaScript state of the inspected page
+is required.
+</li><li>
+The execution context of the code being evaluated includes the
+<a href="http://code.google.com/chrome/devtools/docs/console.html">Developer
+Tools console API</a>.
+For example,
+the code can use <code>inspect()</code> and <code>$0</code>.
+</li><li>
+The evaluated code may return a value that is passed to the extension callback.
+The returned value has to be a valid JSON object (it may contain only
+primitive JavaScript types and acyclic references to other JSON
+objects).
+
+<em>Please observe extra care while processing the data received from the
+inspected page &mdash; the execution context is essentially controlled by the
+inspected page; a malicious page may affect the data being returned to the
+extension.</em>
+</li></ul>
+<p class="caution">
+<strong>Important:</strong>
+Due to the security considerations explained above, the
+<a href="tabs.html#method-executeScript"><code
+>chrome.tabs.executeScript()</code></a> method is the preferred way for an
+extension to access DOM data of the inspected page in cases where the access to
+JavaScript state of the inspected page is not required.</em>
+</p><p>
+The <code>reload()</code> method may be used to reload the inspected page.
+Additionally, the caller can specify an override for the user agent string,
+a script that will be injected early upon page load, and an option to force
+reload of cached resources.
+</p><p>
+Use the <code>getResources()</code> call and the <code>onResourceContent</code>
+event to obtain the list of resources (documents, stylesheets, scripts, images
+etc) within the inspected page. The <code>getContent()</code> and <code
+>setContent()</code> methods of the <code>Resource</code> class along with the
+<code>onResourceContentCommitted</code> event may be used to support
+modification of the resource content, for example, by an external editor.
+</p>
+
+<h2 id="overview-examples">Examples</h2>
+<p>The following code checks for the version of jQuery used by the inspected
+page:
+
+<pre>
+chrome.devtools.inspectedWindow.eval(
+    "jQuery.fn.jquery",
+     function(result, isException) {
+       if (isException)
+         console.log("the page is not using jQuery");
+       else
+         console.log("The page is using jQuery v" + result);
+     }
+);
+</pre>
+
+<p>
+You can find more examples that use Developer Tools APIs in
+<a href="samples.html#devtools">Samples</a>.
+</p>