From 8d40714f78ed74f134e7fca5acf24a6a5c3de175 Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Fri, 28 Aug 2015 23:20:59 -0700 Subject: [PATCH] Standardize web-view-tag --- docs/api/web-view-tag.md | 227 ++++++++++++++++++++++----------------- 1 file changed, 129 insertions(+), 98 deletions(-) diff --git a/docs/api/web-view-tag.md b/docs/api/web-view-tag.md index f8490b624c73..e555607b6b03 100644 --- a/docs/api/web-view-tag.md +++ b/docs/api/web-view-tag.md @@ -1,12 +1,12 @@ -# `` tag +# The `` tag Use the `webview` tag to embed 'guest' content (such as web pages) in your -Electron app. The guest content is contained within the `webview` container; -an embedder page within your app controls how the guest content is laid out and +Electron app. The guest content is contained within the `webview` container. +An embedder page within your app controls how the guest content is laid out and rendered. -Different from the `iframe`, the `webview` runs in a separate process than your -app; it doesn't have the same permissions as your web page and all interactions +Different from an `iframe`, the `webview` runs in a separate process than your +app. It doesn't have the same permissions as your web page and all interactions between your app and embedded content will be asynchronous. This keeps your app safe from the embedded content. @@ -45,9 +45,11 @@ and displays a "loading..." message during the load time: ``` -## Tag attributes +## Tag Attributes -### src +The `webview` tag has the following attributes: + +### `src` ```html @@ -61,7 +63,7 @@ Assigning `src` its own value will reload the current page. The `src` attribute can also accept data URLs, such as `data:text/plain,Hello, world!`. -### autosize +### `autosize` ```html @@ -69,11 +71,11 @@ The `src` attribute can also accept data URLs, such as If "on", the `webview` container will automatically resize within the bounds specified by the attributes `minwidth`, `minheight`, `maxwidth`, and -`maxheight`. These contraints do not impact the `webview` UNLESS `autosize` is +`maxheight`. These constraints do not impact the `webview` UNLESS `autosize` is enabled. When `autosize` is enabled, the `webview` container size cannot be less than the minimum values or greater than the maximum. -### nodeintegration +### `nodeintegration` ```html @@ -82,7 +84,7 @@ than the minimum values or greater than the maximum. If "on", the guest page in `webview` will have node integration and can use node APIs like `require` and `process` to access low level system resources. -### plugins +### `plugins` ```html @@ -90,7 +92,7 @@ APIs like `require` and `process` to access low level system resources. If "on", the guest page in `webview` will be able to use browser plugins. -### preload +### `preload` ```html @@ -102,9 +104,9 @@ will be loaded by `require` in guest page under the hood. When the guest page doesn't have node integration this script will still have access to all Node APIs, but global objects injected by Node will be deleted -after this script has done execution. +after this script has completed execution. -### httpreferrer +### `httpreferrer` ```html @@ -112,15 +114,16 @@ after this script has done execution. Sets the referrer URL for the guest page. -### useragent +### `useragent` ```html ``` -Sets the user agent for the guest page before the page is navigated to. Once the page is loaded, use the `setUserAgent` method to change the user agent. +Sets the user agent for the guest page before the page is navigated to. Once the +page is loaded, use the `setUserAgent` method to change the user agent. -### disablewebsecurity +### `disablewebsecurity` ```html @@ -130,7 +133,10 @@ If "on", the guest page will have web security disabled. ## Methods -The webview element must be loaded before using the methods. +The `webview` tag has the following methods: + +**Note**: The webview element must be loaded before using the methods. + **Example** ```javascript webview.addEventListener("dom-ready", function() { @@ -138,194 +144,195 @@ webview.addEventListener("dom-ready", function() { }); ``` -### ``.getUrl() +### `.getUrl()` Returns URL of guest page. -### ``.getTitle() +### `.getTitle()` Returns the title of guest page. -### ``.isLoading() +### `.isLoading()` -Returns whether guest page is still loading resources. +Returns a boolean whether guest page is still loading resources. -### ``.isWaitingForResponse() +### `.isWaitingForResponse()` -Returns whether guest page is waiting for a first-response for the main resource -of the page. +Returns a boolean whether guest page is waiting for a first-response for the +main resource of the page. -### ``.stop() +### `.stop()` Stops any pending navigation. -### ``.reload() +### `.reload()` Reloads guest page. -### ``.reloadIgnoringCache() +### `.reloadIgnoringCache()` Reloads guest page and ignores cache. -### ``.canGoBack() +### `.canGoBack()` -Returns whether guest page can go back. +Returns a boolean whether guest page can go back. -### ``.canGoForward() +### `.canGoForward()` -Returns whether guest page can go forward. +Returns a boolean whether guest page can go forward. -### ``.canGoToOffset(offset) +### `.canGoToOffset(offset)` * `offset` Integer -Returns whether guest page can go to `offset`. +Returns a boolean whether guest page can go to `offset`. -### ``.clearHistory() +### `.clearHistory()` Clears the navigation history. -### ``.goBack() +### `.goBack()` Makes guest page go back. -### ``.goForward() +### `.goForward()` Makes guest page go forward. -### ``.goToIndex(index) +### `.goToIndex(index)` * `index` Integer Navigates to the specified absolute index. -### ``.goToOffset(offset) +### `.goToOffset(offset)` * `offset` Integer Navigates to the specified offset from the "current entry". -### ``.isCrashed() +### `.isCrashed()` Whether the renderer process has crashed. -### ``.setUserAgent(userAgent) +### `.setUserAgent(userAgent)` * `userAgent` String Overrides the user agent for guest page. -### ``.getUserAgent() +### `.getUserAgent()` -Returns a `String` represents the user agent for guest page. +Returns a `String` representing the user agent for guest page. -### ``.insertCSS(css) +### `.insertCSS(css)` * `css` String Injects CSS into guest page. -### ``.executeJavaScript(code, userGesture) +### `.executeJavaScript(code, userGesture)` * `code` String -* `userGesture` Boolean - Default false +* `userGesture` Boolean - Default `false`. -Evaluates `code` in page. If `userGesture` is set will create user gesture context, -HTML api like `requestFullScreen` which require user action can take advantage -of this option for automation. +Evaluates `code` in page. If `userGesture` is set, it will create user gesture +context. HTML API like `requestFullScreen` which require user action can take +advantage of this option for automation. -### ``.openDevTools() +### `.openDevTools()` Opens a devtools window for guest page. -### ``.closeDevTools() +### `.closeDevTools()` Closes the devtools window of guest page. -### ``.isDevToolsOpened() +### `.isDevToolsOpened()` -Returns whether guest page has a devtools window attached. +Returns a boolean whether guest page has a devtools window attached. -### ``.inspectElement(x, y) +### `.inspectElement(x, y)` * `x` Integer * `y` Integer Starts inspecting element at position (`x`, `y`) of guest page. -### ``.inspectServiceWorker() +### `.inspectServiceWorker()` Opens the devtools for the service worker context present in the guest page. -### ``.setAudioMuted(muted) +### `.setAudioMuted(muted)` -+ `muted` Boolean +* `muted` Boolean Set guest page muted. -### ``.isAudioMuted() +### `.isAudioMuted()` Returns whether guest page has been muted. -### ``.undo() +### `.undo()` Executes editing command `undo` in page. -### ``.redo() +### `.redo()` Executes editing command `redo` in page. -### ``.cut() +### `.cut()` Executes editing command `cut` in page. -### ``.copy() +### `.copy()` Executes editing command `copy` in page. -### ``.paste() +### `.paste()` Executes editing command `paste` in page. -### ``.pasteAndMatchStyle() +### `.pasteAndMatchStyle()` Executes editing command `pasteAndMatchStyle` in page. -### ``.delete() +### `.delete()` Executes editing command `delete` in page. -### ``.selectAll() +### `.selectAll()` Executes editing command `selectAll` in page. -### ``.unselect() +### `.unselect()` Executes editing command `unselect` in page. -### ``.replace(text) +### ``.replaceMisspelling(text) +### `.replaceMisspelling(text)` * `text` String Executes editing command `replaceMisspelling` in page. -### ``.print([options]) +### `.print([options])` -Prints webview's web page. Same with `webContents.print([options])`. +Prints `webview`'s web page. Same with `webContents.print([options])`. -### ``.printToPDF(options, callback) +### `.printToPDF(options, callback)` Prints webview's web page as PDF, Same with `webContents.printToPDF(options, callback)` -### ``.send(channel[, args...]) +### `.send(channel[, args...])` * `channel` String +* `arg` (optional) Send `args..` to guest page via `channel` in asynchronous message, the guest page can handle it by listening to the `channel` event of `ipc` module. @@ -335,7 +342,11 @@ examples. ## DOM events -### load-commit +The following DOM events are available to the `webview` tag: + +### Event: 'load-commit' + +Returns: * `url` String * `isMainFrame` Boolean @@ -344,12 +355,14 @@ Fired when a load has committed. This includes navigation within the current document as well as subframe document-level loads, but does not include asynchronous resource loads. -### did-finish-load +### Event: 'did-finish-load' Fired when the navigation is done, i.e. the spinner of the tab will stop -spinning, and the `onload` event was dispatched. +spinning, and the `onload` event is dispatched. -### did-fail-load +### Event: 'did-fail-load' + +Returns: * `errorCode` Integer * `errorDescription` String @@ -357,21 +370,25 @@ spinning, and the `onload` event was dispatched. This event is like `did-finish-load`, but fired when the load failed or was cancelled, e.g. `window.stop()` is invoked. -### did-frame-finish-load +### Event: 'did-frame-finish-load' + +Returns: * `isMainFrame` Boolean Fired when a frame has done navigation. -### did-start-loading +### Event: 'did-start-loading' Corresponds to the points in time when the spinner of the tab starts spinning. -### did-stop-loading +### Event: 'did-stop-loading' Corresponds to the points in time when the spinner of the tab stops spinning. -### did-get-response-details +### Event: 'did-get-response-details' + +Returns: * `status` Boolean * `newUrl` String @@ -384,7 +401,9 @@ Corresponds to the points in time when the spinner of the tab stops spinning. Fired when details regarding a requested resource is available. `status` indicates socket connection to download the resource. -### did-get-redirect-request +### Event: 'did-get-redirect-request' + +Returns: * `oldUrl` String * `newUrl` String @@ -392,11 +411,13 @@ Fired when details regarding a requested resource is available. Fired when a redirect was received while requesting a resource. -### dom-ready +### Event: 'dom-ready' Fired when document in the given frame is loaded. -### page-title-set +### Event: 'page-title-set' + +Returns: * `title` String * `explicitSet` Boolean @@ -404,21 +425,25 @@ Fired when document in the given frame is loaded. Fired when page title is set during navigation. `explicitSet` is false when title is synthesised from file url. -### page-favicon-updated +### Event: 'page-favicon-updated' -* `favicons` Array - Array of Urls +Returns: + +* `favicons` Array - Array of Urls. Fired when page receives favicon urls. -### enter-html-full-screen +### Event: 'enter-html-full-screen' -Fired when page enters fullscreen triggered by html api. +Fired when page enters fullscreen triggered by HTML API. -### leave-html-full-screen +### Event: 'leave-html-full-screen' -Fired when page leaves fullscreen triggered by html api. +Fired when page leaves fullscreen triggered by HTML API. -### console-message +### Event: 'console-message' + +Returns: * `level` Integer * `message` String @@ -436,7 +461,9 @@ webview.addEventListener('console-message', function(e) { }); ``` -### new-window +### Event: 'new-window' + +Returns: * `url` String * `frameName` String @@ -453,7 +480,7 @@ webview.addEventListener('new-window', function(e) { }); ``` -### close +### Event: 'close' Fired when the guest page attempts to close itself. @@ -466,7 +493,9 @@ webview.addEventListener('close', function() { }); ``` -### ipc-message +### Event: 'ipc-message' + +Returns: * `channel` String * `args` Array @@ -493,21 +522,23 @@ ipc.on('ping', function() { }); ``` -### crashed +### Event: 'crashed' Fired when the renderer process is crashed. -### gpu-crashed +### Event: 'gpu-crashed' Fired when the gpu process is crashed. -### plugin-crashed +### Event: 'plugin-crashed' + +Returns: * `name` String * `version` String Fired when a plugin process is crashed. -### destroyed +### Event: 'destroyed' Fired when the WebContents is destroyed.