Adding <appview> documentation.

Review URL: https://codereview.chromium.org/921793004

Cr-Commit-Position: refs/heads/master@{#319150}

chrome/common/extensions/api/_api_features.json

@@ -75,6 +75,11 @@
     "contexts": ["blessed_extension", "unblessed_extension", "content_script"],
     "matches": []
   },
+  "appviewTag": {
+    "internal": true,
+    "dependencies": ["permission:appview"],
+    "contexts": ["blessed_extension"]
+  },
   "audioModem": {
     "dependencies": ["permission:audioModem"],
     "contexts": ["blessed_extension"]

chrome/common/extensions/api/appview_tag.idl

+// Copyright 2015 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.
+
+// Use the <code>appview</code> tag to embed other Chrome Apps within your
+// Chrome App. (see <a href=#usage>Usage</a>).
+[documentation_title="<appview> Tag",
+  documentation_namespace="<appview>",
+  documented_in="tags/appview"]
+namespace appviewTag {
+  // This object specifies details and operations to perform on the embedding
+  // request. The app to be embedded can make a decision on whether or not to
+  // allow the embedding and what to embed based on the embedder making the
+  // request.
+  dictionary EmbedRequest {
+    // Optional developer specified data that the app to be embedded can use
+    // when making an embedding decision.
+    object data;
+
+    // Allows the embedding request.
+    //
+    // |url| : Specifies the content to be embedded.
+    static void allow(DOMString url);
+
+    // Prevents the embedding request.
+    static void deny();
+  };
+
+  // An optional function that's called after the embedding request is
+  // completed.
+  //
+  // |success| : True if the embedding request succeded.
+  callback EmbeddingCallback = void (boolean success);
+
+  interface Functions {
+    // Requests another app to be embedded.
+    //
+    // |app| : The extension id of the app to be embedded.
+    // |data| : Optional developer specified data that the app to be embedded
+    //   can use when making an embedding decision.
+    // |callback| : An optional function that's called after the embedding
+    //   request is completed.
+    static void connect(DOMString app, optional any data,
+      optional EmbeddingCallback callback);
+  };
+};

chrome/common/extensions/docs/templates/intros/appview_tag.html

+<h2 id="usage">Usage</h2>
+
+<p>
+Use the <code>appview</code> tag to embed other Chrome Apps within your Chrome
+App.
+</p>
+
+<p>
+The <code>appview</code> runs in a separate process from your app, it doesn't
+inherit the same permissions and is only allowed to interact with your app
+through asynchronous APIs.
+Not all apps can be embedded; apps have to explicitly allow themselves to be
+embedded.
+</p>
+
+<h2 id="embedder">Preparing your app to be embedded</h2>
+
+<p>
+To allow your app to be embedded into another app, you need to add a listener
+to your app's background page:
+</p>
+
+<pre data-filename="background.js">
+chrome.app.runtime.onEmbedRequested.addListener(function(request) {
+  // Allows the embedder to embed foo.html.
+  request.allow("foo.html");
+});
+</pre>
+
+<h2 id="embedded">Embedding another app</h2>
+
+<p>
+To embed another Chrome App in your app, add the <code>appview</code> tag to
+your app's embedder page (this is the app page that will display the
+embedded app) and use the connect API to request the embedding of the other
+app.
+</p>
+
+<pre data-filename="background.js">
+// Creates an &lt;appview&gt; element.
+var appview = document.createElement("appview");
+// Appends the element to the document body.
+document.body.appendChild(appview);
+// Connects the appview to appToEmbed.
+// appToEmbed is the id of the app you are trying to embed.
+appview.connect(appToEmbed);
+</pre>

chrome/common/extensions/docs/templates/json/chrome_sidenav.json

@@ -496,6 +496,10 @@
                 "title": "Webview Tag",
                 "href": "/apps/tags/webview"
               },
+              {
+                "title": "Appview Tag",
+                "href": "/apps/tags/appview"
+              },
               {
                 "title": "Web APIs",
                 "href": "/apps/api_other"

tools/json_schema_compiler/idl_schema.py

@@ -343,7 +343,8 @@ class Namespace(object):
                internal=False,
                platforms=None,
                compiler_options=None,
-               deprecated=None):
+               deprecated=None,
+               documentation_options=None):
     self.namespace = namespace_node
     self.nodoc = nodoc
     self.internal = internal
@@ -355,6 +356,7 @@ class Namespace(object):
     self.callbacks = OrderedDict()
     self.description = description
     self.deprecated = deprecated
+    self.documentation_options = documentation_options
 
   def process(self):
     for node in self.namespace.GetChildren():
@@ -371,10 +373,8 @@ class Namespace(object):
         self.types.append(Enum(node).process())
       else:
         sys.exit('Did not process %s %s' % (node.cls, node))
-    if self.compiler_options is not None:
-      compiler_options = self.compiler_options
-    else:
-      compiler_options = {}
+    compiler_options = self.compiler_options or {}
+    documentation_options = self.documentation_options or {}
     return {'namespace': self.namespace.GetName(),
             'description': self.description,
             'nodoc': self.nodoc,
@@ -384,7 +384,8 @@ class Namespace(object):
             'events': self.events,
             'platforms': self.platforms,
             'compiler_options': compiler_options,
-            'deprecated': self.deprecated}
+            'deprecated': self.deprecated,
+            'documentation_options': documentation_options}
 
   def process_interface(self, node):
     members = []
@@ -412,6 +413,7 @@ class IDLSchema(object):
     platforms = None
     compiler_options = {}
     deprecated = None
+    documentation_options = {}
     for node in self.idl:
       if node.cls == 'Namespace':
         if not description:
@@ -422,7 +424,8 @@ class IDLSchema(object):
         namespace = Namespace(node, description, nodoc, internal,
                               platforms=platforms,
                               compiler_options=compiler_options or None,
-                              deprecated=deprecated)
+                              deprecated=deprecated,
+                              documentation_options=documentation_options)
         namespaces.append(namespace.process())
         nodoc = False
         internal = False
@@ -445,6 +448,12 @@ class IDLSchema(object):
           compiler_options['camel_case_enum_to_string'] = node.value
         elif node.name == 'deprecated':
           deprecated = str(node.value)
+        elif node.name == 'documentation_title':
+          documentation_options['title'] = node.value
+        elif node.name == 'documentation_namespace':
+          documentation_options['namespace'] = node.value
+        elif node.name == 'documented_in':
+          documentation_options['documented_in'] = node.value
         else:
           continue
       else: