src/chrome/common/extensions/api/webview_tag.json

   1 // Copyright 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 [
   6   {
   7     "namespace": "webviewTag",
   8     "description": "Use the <code>webview</code> tag to actively load live content from the web over the network and embed it in your Chrome App. Your app can control the appearance of the <code>webview</code> and interact with the web content, initiate navigations in an embedded web page, react to error events that happen within it, and more (see <a href=\"#usage\">Usage</a>).",
   9     "documentation_options": {
  10       "title": "<webview> Tag",
  11       "namespace": "<webview>"
  12     },
  13     "types": [
  14       {
  15         "id": "InjectDetails",
  16         "type": "object",
  17         "description": "Details of the script or CSS to inject. Either the code or the file property must be set, but both may not be set at the same time.",
  18         "properties": {
  19           "code": {
  20             "type": "string",
  21             "optional": true,
  22             "description": "JavaScript or CSS code to inject."
  23           },
  24           "file": {
  25             "type": "string",
  26             "optional": true,
  27             "description": "JavaScript or CSS file to inject."
  28           }
  29         }
  30       },
  31       {
  32         "id": "ContentWindow",
  33         "type": "object",
  34         "description": "Messaging handle to a guest window.",
  35         "functions": [
  36           {
  37             "name": "postMessage",
  38             "description": "<p>Posts a message to the embedded web content as long as the embedded content is displaying a page from the target origin. This method is available once the page has completed loading. Listen for the <a href=\"#event-contentload\">contentload</a> event and then call the method.</p><p>The guest will be able to send replies to the embedder by posting message to <code>event.source</code> on the message event it receives.</p><p>This API is identical to the <a href=\"https://developer.mozilla.org/en-US/docs/DOM/window.postMessage\">HTML5 postMessage API</a> for communication between web pages. The embedder may listen for replies by adding a <code>message</code> event listener to its own frame.</p>",
  39             "parameters": [
  40               {
  41                 "type": "any",
  42                 "name": "message",
  43                 "description": "Message object to send to the guest."
  44               },
  45               {
  46                 "type": "string",
  47                 "name": "targetOrigin",
  48                 "description": "Specifies what the origin of the guest window must be for the event to be dispatched."
  49               }
  50             ]
  51           }
  52         ]
  53       },
  54       {
  55         "id": "NewWindow",
  56         "type": "object",
  57         "description": "Interface attached to <code>newwindow</code> DOM events.",
  58         "functions": [
  59           {
  60             "name": "attach",
  61             "description": "Attach the requested target page to an existing <code>webview</code> element.",
  62             "parameters": [
  63               {
  64                 "type": "object",
  65                 "name": "webview",
  66                 "description": "The <code>webview</code> element to which the target page should be attached.",
  67                 "properties": {}
  68               }
  69             ]
  70           },
  71           {
  72             "name": "discard",
  73             "description": "Cancel the new window request."
  74           }
  75         ]
  76       },
  77       {
  78         "id": "MediaPermissionRequest",
  79         "type": "object",
  80         "description": "The type of <code>request</code> object which accompanies a <code>media</code> <a href=\"#event-permissionrequest\">permissionrequest</a></code> DOM event.",
  81         "properties": {
  82           "url": {
  83             "description": "The URL of the frame requesting access to user media.",
  84             "type": "string"
  85           }
  86         },
  87         "functions": [
  88           { "name": "allow", "description": "Allow the permission request." },
  89           { "name": "deny", "description": "Deny the permission request." }
  90         ]
  91       },
  92       {
  93         "id": "GeolocationPermissionRequest",
  94         "type": "object",
  95         "description": "The type of <code>request</code> object which accompanies a <code>geolocation</code> <a href=\"#event-permissionrequest\">permissionrequest</a></code> DOM event.",
  96         "properties": {
  97           "url": {
  98             "description": "The URL of the frame requesting access to geolocation data.",
  99             "type": "string"
 100           }
 101         },
 102         "functions": [
 103           { "name": "allow", "description": "Allow the permission request." },
 104           { "name": "deny", "description": "Deny the permission request." }
 105         ]
 106       },
 107       {
 108         "id": "PointerLockPermissionRequest",
 109         "type": "object",
 110         "description": "The type of <code>request</code> object which accompanies a <code>pointerLock</code> <a href=\"#event-permissionrequest\">permissionrequest</a></code> DOM event.",
 111         "properties": {
 112           "userGesture": {
 113             "description": "Whether or not pointer lock was requested as a result of a user input gesture.",
 114             "type": "boolean"
 115           },
 116           "lastUnlockedBySelf": {
 117             "description": "Whether or not the requesting frame was the most recent client to hold pointer lock.",
 118             "type": "boolean"
 119           },
 120           "url": {
 121             "description": "The URL of the frame requesting pointer lock.",
 122             "type": "string"
 123           }
 124         },
 125         "functions": [
 126           { "name": "allow", "description": "Allow the permission request." },
 127           { "name": "deny", "description": "Deny the permission request." }
 128         ]
 129       }
 130     ],
 131     "functions": [
 132       {
 133         "name": "back",
 134         "type": "function",
 135         "description": "Navigates backward one history entry if possible. Equivalent to <code>go(-1)</code>."
 136       },
 137       {
 138         "name": "canGoBack",
 139         "type": "function",
 140         "returns": { "type": "boolean" },
 141         "description": "Indicates whether or not it is possible to navigate backward through history."
 142       },
 143       {
 144         "name": "canGoForward",
 145         "type": "function",
 146         "returns": { "type": "boolean" },
 147         "description": "Indicates whether or not it is possible to navigate forward through history."
 148       },
 149       {
 150         "name": "executeScript",
 151         "type": "function",
 152         "description": "<p>Injects JavaScript code into the guest page.</p><p>The following sample code uses script injection to set the guest page's background color to red:</p><pre>webview.executeScript({ code: \"document.body.bgColor = 'red'\" });</pre>",
 153         "parameters": [
 154           {
 155             "$ref": "InjectDetails",
 156             "name": "details",
 157             "description": "Details of the script to run."
 158           },
 159           {
 160             "type": "function",
 161             "name": "callback",
 162             "optional": true,
 163             "description": "Called after all the JavaScript has been executed.",
 164             "parameters": [
 165               {
 166                 "name": "result",
 167                 "optional": true,
 168                 "type": "array",
 169                 "items": {"type": "any", "minimum": 0},
 170                 "description": "The result of the script in every injected frame."
 171               }
 172             ]
 173           }
 174         ]
 175       },
 176       {
 177         "name": "forward",
 178         "type": "function",
 179         "description": "Navigates forward one history entry if possible. Equivalent to <code>go(1)</code>.",
 180         "parameters": []
 181       },
 182       {
 183         "name": "getProcessId",
 184         "type": "function",
 185         "returns": { "type": "integer" },
 186         "description": "Returns Chrome's internal process ID for the guest web page's current process, allowing embedders to know how many guests would be affected by terminating the process. Two guests will share a process only if they belong to the same app and have the same <a href=\"#partition\">storage partition ID</a>. The call is synchronous and returns the embedder's cached notion of the current process ID. The process ID isn't the same as the operating system's process ID.",
 187         "parameters": []
 188       },
 189       {
 190         "name": "go",
 191         "type": "function",
 192         "description": "Navigates to a history entry using a history index relative to the current navigation. If the requested navigation is impossible, this method has no effect.",
 193         "parameters": [
 194           {
 195             "type": "integer",
 196             "name": "relativeIndex",
 197             "description": "Relative history index to which the webview should be navigated. For example, a value of <code>2</code> will navigate forward 2 history entries if possible; a value of <code>-3</code> will navigate backward 3 entries."
 198           }
 199         ]
 200       },
 201       {
 202         "name": "insertCSS",
 203         "type": "function",
 204         "description": "Injects CSS into the guest page.",
 205         "parameters": [
 206           {
 207             "$ref": "InjectDetails",
 208             "name": "details",
 209             "description": "Details of the CSS to insert."
 210           },
 211           {
 212             "type": "function",
 213             "name": "callback",
 214             "optional": true,
 215             "description": "Called after the CSS has been inserted.",
 216             "parameters": []
 217           }
 218         ]
 219       },
 220       {
 221         "name": "reload",
 222         "type": "function",
 223         "description": "Reloads the current top-level page.",
 224         "parameters": []
 225       },
 226       {
 227         "name": "stop",
 228         "type": "function",
 229         "description": "Stops loading the current &lt;webview> navigation if in progress.",
 230         "parameters": []
 231       },
 232       {
 233         "name": "terminate",
 234         "type": "function",
 235         "description": "Forcibly kills the guest web page's renderer process. This may affect multiple <code>webview</code> tags in the current app if they share the same process, but it will not affect <code>webview</code> tags in other apps.",
 236         "parameters": []
 237       }
 238     ],
 239     "events": [
 240       {
 241         "name": "close",
 242         "options": { "supportsDom": true },
 243         "description": "Fired when the guest window attempts to close itself.<p>The following example code navigates the webview to <code>about:blank</code> when the guest attempts to close itself.</p><pre>webview.addEventListener('close', function() {\r  webview.src = 'about:blank';\r});</pre>",
 244         "parameters": []
 245       },
 246       {
 247         "name": "consolemessage",
 248         "options": { "supportsDom": true },
 249         "description": "Fired when the guest window logs a console message.<p>The following example code forwards all log messages to the embedder's console without regard for log level or other properties.</p><pre>webview.addEventListener('consolemessage', function(e) {\r  console.log('Guest page logged a message: ', e.message);\r});</pre>",
 250         "parameters": [
 251           {
 252             "name": "level",
 253             "description": "The severity level of the log message. Ranges from 0 to 4.",
 254             "type": "integer"
 255           },
 256           {
 257             "name": "message",
 258             "description": "The logged message contents.",
 259             "type": "string"
 260           },
 261           {
 262             "name": "line",
 263             "description": "The line number of the message source.",
 264             "type": "integer"
 265           },
 266           {
 267             "name": "sourceId",
 268             "description": "A string identifying the resource which logged the message.",
 269             "type": "string"
 270           }
 271         ]
 272       },
 273       {
 274         "name": "contentload",
 275         "options": { "supportsDom": true },
 276         "description": "Fired when the guest window fires a <code>load</code> event.<p>The following example code modifies the default font size of the guest's <code>body</code> element after the page loads:</p><pre>webview.addEventListener('contentload', function() {\r  webview.executeScript({ code: 'document.body.style.fontSize = \"42px\"' });\r});</pre>",
 277         "parameters": []
 278       },
 279       {
 280         "name": "exit",
 281         "options": { "supportsDom": true },
 282         "description": "Fired when the process rendering the guest web content has exited.<p>The following example code will show a farewell message whenever the guest page crashes:</p><pre>webview.addEventListener('exit', function(e) {\r  if (e.reason === 'crash') {\r    webview.src = 'data:text/plain,Goodbye, world!';\r  }\r});</pre>",
 283         "parameters": [
 284           {
 285             "name": "processID",
 286             "description": "Chrome's interal ID of the process that exited.",
 287             "type": "integer"
 288           },
 289           {
 290             "name": "reason",
 291             "description": "String indicating the reason for the exit.",
 292             "type": "string",
 293             "enum": ["normal", "abnormal", "crash", "kill"]
 294           }
 295         ]
 296       },
 297       {
 298         "name": "loadabort",
 299         "options": { "supportsDom": true },
 300         "description": "Fired when a top-level load has aborted without committing.",
 301         "parameters": [
 302           {
 303             "name": "url",
 304             "description": "Requested URL.",
 305             "type": "string"
 306           },
 307           {
 308             "name": "isTopLevel",
 309             "description": "Whether the load was top-level or in a subframe.",
 310             "type": "boolean"
 311           },
 312           {
 313             "name": "reason",
 314             "description": "String indicating what type of abort occurred.",
 315             "type": "string",
 316             "enum": ["networkError", "download", "canceled", "sslError", "safeBrowsingError"]
 317           }
 318         ]
 319       },
 320       {
 321         "name": "loadcommit",
 322         "options": { "supportsDom": true },
 323         "description": "Fired when a load has committed.",
 324         "parameters": [
 325           {
 326             "name": "url",
 327             "description": "The URL that committed.",
 328             "type": "string"
 329           },
 330           {
 331             "name": "isTopLevel",
 332             "description": "Whether the load is top-level or in a subframe.",
 333             "type": "boolean"
 334           }
 335         ]
 336       },
 337       {
 338         "name": "loadredirect",
 339         "options": { "supportsDom": true },
 340         "description": "Fired when a top-level load request has redirected to a different URL.",
 341         "parameters": [
 342           {
 343             "name": "oldUrl",
 344             "description": "The requested URL before the redirect.",
 345             "type": "string"
 346           },
 347           {
 348             "name": "newUrl",
 349             "description": "The new URL after the redirect.",
 350             "type": "string"
 351           },
 352           {
 353             "name": "isTopLevel",
 354             "description": "Whether or not the redirect happened at top-level or in a subframe.",
 355             "type": "boolean"
 356           }
 357         ]
 358       },
 359       {
 360         "name": "loadstart",
 361         "options": { "supportsDom": true },
 362         "description": "Fired when a load has begun.",
 363         "parameters": [
 364           {
 365             "name": "url",
 366             "description": "Requested URL.",
 367             "type": "string"
 368           },
 369           {
 370             "name": "isTopLevel",
 371             "description": "Whether the load is top-level or in a subframe.",
 372             "type": "boolean"
 373           }
 374         ]
 375       },
 376       {
 377         "name": "loadstop",
 378         "options": { "supportsDom": true },
 379         "description": "Fired when all loads in the guest page (including all subframes) have completed. Fires in addition to any related <code>loadcommit</code> or <code>loadabort</code> events, which occur per-frame.",
 380         "parameters": []
 381       },
 382       {
 383         "name": "newwindow",
 384         "options": { "supportsDom": true },
 385         "description": "Fired when the guest page attempts to open a new browser window.<p>The following example code will create and navigate a new <code>webview</code> in the embedder for each requested new window:</p><pre>webview.addEventListener('newwindow', function(e) {\r  var newWebview = document.createElement('webview');\r  document.body.appendChild(newWebview);\r  e.window.attach(newWebview);\r});</pre>",
 386         "parameters": [
 387           {
 388             "name": "window",
 389             "description": "An interface that can be used to either attach the requested target page to an existing <code>webview</code> element or explicitly discard the request.",
 390             "$ref": "NewWindow"
 391           },
 392           {
 393             "name": "targetUrl",
 394             "description": "The target URL requested for the new window.",
 395             "type": "string"
 396           },
 397           {
 398             "name": "initialWidth",
 399             "description": "The initial width requested for the new window.",
 400             "type": "number"
 401           },
 402           {
 403             "name": "initialHeight",
 404             "description": "The initial height requested for the new window.",
 405             "type": "number"
 406           },
 407           {
 408             "name": "name",
 409             "description": "The requested name of the new window.",
 410             "type": "string"
 411           },
 412           {
 413             "name": "windowOpenDisposition",
 414             "description": "The requested disposition of the new window.",
 415             "type": "string",
 416             "enum": ["ignore", "save_to_disk", "current_tab", "new_background_tab", "new_foreground_tab", "new_window", "new_popup"]
 417           }
 418         ]
 419       },
 420       {
 421         "name": "permissionrequest",
 422         "options": { "supportsDom": true },
 423         "description": "Fired when the guest page needs to request special permission from the embedder.<p>The following example code will grant the guest page access to the <code>webkitGetUserMedia</code> API. Note that an app using this example code must itself specify <code>audioCapture</code> and/or <code>videoCapture</code> manifest permissions:</p><pre>webview.addEventListener('permissionrequest', function(e) {\r  if (e.permission === 'media') {\r    e.request.allow();\r  }\r});</pre>",
 424         "parameters": [
 425           {
 426             "name": "permission",
 427             "description": "The type of permission being requested.",
 428             "type": "string",
 429             "enum": ["media", "geolocation", "pointerLock"]
 430           },
 431           {
 432             "name": "requestId",
 433             "description": "An number which uniquely identifies this request from the guest.",
 434             "type": "integer"
 435           },
 436           {
 437             "name": "request",
 438             "type": "object",
 439             "properties": {},
 440             "description": "An object which holds details of the requested permission. Depending on the type of permission requested, this may be a $ref:MediaPermissionRequest, $ref:GeolocationPermissionRequest, or a $ref:PointerLockPermissionRequest."
 441           }
 442         ]
 443       },
 444       {
 445         "name": "responsive",
 446         "options": { "supportsDom": true },
 447         "description": "Fired when the process rendering the guest web content has become responsive again after being unresponsive.<p>The following example code will fade the <code>webview</code> element in or out as it becomes responsive or unresponsive:</p><pre>webview.style.webkitTransition = 'opacity 250ms';\rwebview.addEventListener('unresponsive', function() {\r  webview.style.opacity = '0.5';\r});\rwebview.addEventListener('responsive', function() {\r  webview.style.opacity = '1';\r});</pre>",
 448         "parameters": [
 449           {
 450             "name": "processID",
 451             "description": "Chrome's internal ID of the process that became responsive.",
 452             "type": "integer"
 453           }
 454         ]
 455       },
 456       {
 457         "name": "sizechanged",
 458         "options": { "supportsDom": true },
 459         "description": "Fired when the embedded web content has been resized. Only fires if <code>autosize</code> is enabled.",
 460         "parameters": [
 461           {
 462             "name": "oldWidth",
 463             "description": "Old width of embedded web content.",
 464             "type": "number"
 465           },
 466           {
 467             "name": "oldHeight",
 468             "description": "Old height of embedded web content.",
 469             "type": "number"
 470           },
 471           {
 472             "name": "newWidth",
 473             "description": "New width of embedded web content.",
 474             "type": "number"
 475           },
 476           {
 477             "name": "newHeight",
 478             "description": "New height of embedded web content.",
 479             "type": "number"
 480           }
 481         ]
 482       },
 483       {
 484         "name": "unresponsive",
 485         "options": { "supportsDom": true },
 486         "description": "Fired when the process rendering the guest web content has become unresponsive. This event will be generated once with a matching responsive event if the guest begins to respond again.",
 487         "parameters": [
 488           {
 489             "name": "processID",
 490             "description": "Chrome's internal ID of the process that has become unresponsive.",
 491             "type": "integer"
 492           }
 493         ]
 494       }
 495     ],
 496     "properties": {
 497       "contentWindow": {
 498         "$ref": "ContentWindow",
 499         "description": "Object reference which can be used to post messages into the guest page."
 500       }
 501     }
 502   }
 503 ]
 504