mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions 1

Merge pull request #2657 from atom/jl-std-docs-9

Browse source 
Standardize Docs: web-frame, web-view-tag, window-open
This commit is contained in:
Jessica Lord 2015-09-02 18:44:32 -07:00
commit c2dcccf7c7
3 changed files with 175 additions and 136 deletions
Download patch file Download diff file Expand all files Collapse all files

35
docs/api/web-frame.md
View file

@ -1,4 +1,4 @@
# web-frame # webFrame
The `web-frame` module allows you to customize the rendering of the current The `web-frame` module allows you to customize the rendering of the current
web page. web page.
@ -7,40 +7,45 @@ An example of zooming current page to 200%.
```javascript ```javascript
var webFrame = require('web-frame'); var webFrame = require('web-frame');
webFrame.setZoomFactor(2); webFrame.setZoomFactor(2);
``` ```
## webFrame.setZoomFactor(factor) ## Methods
* `factor` Number - Zoom factor The `web-frame` module has the following methods:
Changes the zoom factor to the specified factor, zoom factor is ### `webFrame.setZoomFactor(factor)`
zoom percent / 100, so 300% = 3.0.
## webFrame.getZoomFactor() * `factor` Number - Zoom factor.
Changes the zoom factor to the specified factor. Zoom factor is
zoom percent divided by 100, so 300% = 3.0.
### `webFrame.getZoomFactor()`
Returns the current zoom factor. Returns the current zoom factor.
## webFrame.setZoomLevel(level) ### `webFrame.setZoomLevel(level)`
* `level` Number - Zoom level * `level` Number - Zoom level
Changes the zoom level to the specified level, 0 is "original size", and each Changes the zoom level to the specified level. The original size is 0 and each
increment above or below represents zooming 20% larger or smaller to default increment above or below represents zooming 20% larger or smaller to default
limits of 300% and 50% of original size, respectively. limits of 300% and 50% of original size, respectively.
## webFrame.getZoomLevel() ### `webFrame.getZoomLevel()`
Returns the current zoom level. Returns the current zoom level.
## webFrame.setZoomLevelLimits(minimumLevel, maximumLevel) ### `webFrame.setZoomLevelLimits(minimumLevel, maximumLevel)`
* `minimumLevel` Number * `minimumLevel` Number
* `maximumLevel` Number * `maximumLevel` Number
Sets the maximum and minimum zoom level. Sets the maximum and minimum zoom level.
## webFrame.setSpellCheckProvider(language, autoCorrectWord, provider) ### `webFrame.setSpellCheckProvider(language, autoCorrectWord, provider)`
* `language` String * `language` String
* `autoCorrectWord` Boolean * `autoCorrectWord` Boolean
@ -61,7 +66,7 @@ require('web-frame').setSpellCheckProvider("en-US", true, {
}); });
``` ```
## webFrame.registerUrlSchemeAsSecure(scheme) ### `webFrame.registerUrlSchemeAsSecure(scheme)`
* `scheme` String * `scheme` String
@ -71,11 +76,11 @@ Secure schemes do not trigger mixed content warnings. For example, `https` and
`data` are secure schemes because they cannot be corrupted by active network `data` are secure schemes because they cannot be corrupted by active network
attackers. attackers.
## webFrame.registerUrlSchemeAsBypassingCsp(scheme) ### `webFrame.registerUrlSchemeAsBypassingCsp(scheme)`
* `scheme` String * `scheme` String
Resources will be loaded from this `scheme` regardless of Resources will be loaded from this `scheme` regardless of the current page's
page's Content Security Policy. Content Security Policy.
[spellchecker]: https://github.com/atom/node-spellchecker [spellchecker]: https://github.com/atom/node-spellchecker

239
docs/api/web-view-tag.md
View file

@ -1,12 +1,12 @@
# `<webview>` tag # The `<webview>` tag
Use the `webview` tag to embed 'guest' content (such as web pages) in your 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; 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 An embedded page within your app controls how the guest content is laid out and
rendered. rendered.
Different from the `iframe`, the `webview` runs in a separate process than your Unlike 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 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 between your app and embedded content will be asynchronous. This keeps your app
safe from the embedded content. safe from the embedded content.
@ -45,9 +45,11 @@ and displays a "loading..." message during the load time:
</script> </script>
``` ```
## Tag attributes ## Tag Attributes
### src The `webview` tag has the following attributes:
### `src`
```html ```html
<webview src="https://www.github.com/"></webview> <webview src="https://www.github.com/"></webview>
@ -61,7 +63,7 @@ Assigning `src` its own value will reload the current page.
The `src` attribute can also accept data URLs, such as The `src` attribute can also accept data URLs, such as
`data:text/plain,Hello, world!`. `data:text/plain,Hello, world!`.
### autosize ### `autosize`
```html ```html
<webview src="https://www.github.com/" autosize="on" minwidth="576" minheight="432"></webview> <webview src="https://www.github.com/" autosize="on" minwidth="576" minheight="432"></webview>
@ -69,11 +71,11 @@ The `src` attribute can also accept data URLs, such as
If "on", the `webview` container will automatically resize within the If "on", the `webview` container will automatically resize within the
bounds specified by the attributes `minwidth`, `minheight`, `maxwidth`, and 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 enabled. When `autosize` is enabled, the `webview` container size cannot be less
than the minimum values or greater than the maximum. than the minimum values or greater than the maximum.
### nodeintegration ### `nodeintegration`
```html ```html
<webview src="http://www.google.com/" nodeintegration></webview> <webview src="http://www.google.com/" nodeintegration></webview>
@ -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 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. APIs like `require` and `process` to access low level system resources.
### plugins ### `plugins`
```html ```html
<webview src="https://www.github.com/" plugins></webview> <webview src="https://www.github.com/" plugins></webview>
@ -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. If "on", the guest page in `webview` will be able to use browser plugins.
### preload ### `preload`
```html ```html
<webview src="https://www.github.com/" preload="./test.js"></webview> <webview src="https://www.github.com/" preload="./test.js"></webview>
@ -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 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 access to all Node APIs, but global objects injected by Node will be deleted
after this script has done execution. after this script has finished executing.
### httpreferrer ### `httpreferrer`
```html ```html
<webview src="https://www.github.com/" httpreferrer="http://cheng.guru"></webview> <webview src="https://www.github.com/" httpreferrer="http://cheng.guru"></webview>
@ -112,15 +114,16 @@ after this script has done execution.
Sets the referrer URL for the guest page. Sets the referrer URL for the guest page.
### useragent ### `useragent`
```html ```html
<webview src="https://www.github.com/" useragent="Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko"></webview> <webview src="https://www.github.com/" useragent="Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko"></webview>
``` ```
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 ```html
<webview src="https://www.github.com/" disablewebsecurity></webview> <webview src="https://www.github.com/" disablewebsecurity></webview>
@ -130,7 +133,10 @@ If "on", the guest page will have web security disabled.
## Methods ## 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** **Example**
```javascript ```javascript
webview.addEventListener("dom-ready", function() { webview.addEventListener("dom-ready", function() {
@ -138,194 +144,195 @@ webview.addEventListener("dom-ready", function() {
}); });
``` ```
### `<webview>`.getUrl() ### `<webview>.getUrl()`
Returns URL of guest page. Returns URL of guest page.
### `<webview>`.getTitle() ### `<webview>.getTitle()`
Returns the title of guest page. Returns the title of guest page.
### `<webview>`.isLoading() ### `<webview>.isLoading()`
Returns whether guest page is still loading resources. Returns a boolean whether guest page is still loading resources.
### `<webview>`.isWaitingForResponse() ### `<webview>.isWaitingForResponse()`
Returns whether guest page is waiting for a first-response for the main resource Returns a boolean whether the guest page is waiting for a first-response for the
of the page. main resource of the page.
### `<webview>`.stop() ### `<webview>.stop()`
Stops any pending navigation. Stops any pending navigation.
### `<webview>`.reload() ### `<webview>.reload()`
Reloads guest page. Reloads the guest page.
### `<webview>`.reloadIgnoringCache() ### `<webview>.reloadIgnoringCache()`
Reloads guest page and ignores cache. Reloads the guest page and ignores cache.
### `<webview>`.canGoBack() ### `<webview>.canGoBack()`
Returns whether guest page can go back. Returns a boolean whether the guest page can go back.
### `<webview>`.canGoForward() ### `<webview>.canGoForward()`
Returns whether guest page can go forward. Returns a boolean whether the guest page can go forward.
### `<webview>`.canGoToOffset(offset) ### `<webview>.canGoToOffset(offset)`
* `offset` Integer * `offset` Integer
Returns whether guest page can go to `offset`. Returns a boolean whether the guest page can go to `offset`.
### `<webview>`.clearHistory() ### `<webview>.clearHistory()`
Clears the navigation history. Clears the navigation history.
### `<webview>`.goBack() ### `<webview>.goBack()`
Makes guest page go back. Makes the guest page go back.
### `<webview>`.goForward() ### `<webview>.goForward()`
Makes guest page go forward. Makes the guest page go forward.
### `<webview>`.goToIndex(index) ### `<webview>.goToIndex(index)`
* `index` Integer * `index` Integer
Navigates to the specified absolute index. Navigates to the specified absolute index.
### `<webview>`.goToOffset(offset) ### `<webview>.goToOffset(offset)`
* `offset` Integer * `offset` Integer
Navigates to the specified offset from the "current entry". Navigates to the specified offset from the "current entry".
### `<webview>`.isCrashed() ### `<webview>.isCrashed()`
Whether the renderer process has crashed. Whether the renderer process has crashed.
### `<webview>`.setUserAgent(userAgent) ### `<webview>.setUserAgent(userAgent)`
* `userAgent` String * `userAgent` String
Overrides the user agent for guest page. Overrides the user agent for the guest page.
### `<webview>`.getUserAgent() ### `<webview>.getUserAgent()`
Returns a `String` represents the user agent for guest page. Returns a `String` representing the user agent for guest page.
### `<webview>`.insertCSS(css) ### `<webview>.insertCSS(css)`
* `css` String * `css` String
Injects CSS into guest page. Injects CSS into the guest page.
### `<webview>`.executeJavaScript(code, userGesture) ### `<webview>.executeJavaScript(code, userGesture)`
* `code` String * `code` String
* `userGesture` Boolean - Default false * `userGesture` Boolean - Default `false`.
Evaluates `code` in page. If `userGesture` is set will create user gesture context, Evaluates `code` in page. If `userGesture` is set, it will the create user
HTML api like `requestFullScreen` which require user action can take advantage gesture context in the page. HTML APIs like `requestFullScreen`, which require
of this option for automation. user action, can take advantage of this option for automation.
### `<webview>`.openDevTools() ### `<webview>.openDevTools()`
Opens a devtools window for guest page. Opens a devtools window for guest page.
### `<webview>`.closeDevTools() ### `<webview>.closeDevTools()`
Closes the devtools window of guest page. Closes the devtools window of guest page.
### `<webview>`.isDevToolsOpened() ### `<webview>.isDevToolsOpened()`
Returns whether guest page has a devtools window attached. Returns a boolean whether guest page has a devtools window attached.
### `<webview>`.inspectElement(x, y) ### `<webview>.inspectElement(x, y)`
* `x` Integer * `x` Integer
* `y` Integer * `y` Integer
Starts inspecting element at position (`x`, `y`) of guest page. Starts inspecting element at position (`x`, `y`) of guest page.
### `<webview>`.inspectServiceWorker() ### `<webview>.inspectServiceWorker()`
Opens the devtools for the service worker context present in the guest page. Opens the devtools for the service worker context present in the guest page.
### `<webview>`.setAudioMuted(muted) ### `<webview>.setAudioMuted(muted)`
+ `muted` Boolean * `muted` Boolean
Set guest page muted. Set guest page muted.
### `<webview>`.isAudioMuted() ### `<webview>.isAudioMuted()`
Returns whether guest page has been muted. Returns whether guest page has been muted.
### `<webview>`.undo() ### `<webview>.undo()`
Executes editing command `undo` in page. Executes editing command `undo` in page.
### `<webview>`.redo() ### `<webview>.redo()`
Executes editing command `redo` in page. Executes editing command `redo` in page.
### `<webview>`.cut() ### `<webview>.cut()`
Executes editing command `cut` in page. Executes editing command `cut` in page.
### `<webview>`.copy() ### `<webview>.copy()`
Executes editing command `copy` in page. Executes editing command `copy` in page.
### `<webview>`.paste() ### `<webview>.paste()`
Executes editing command `paste` in page. Executes editing command `paste` in page.
### `<webview>`.pasteAndMatchStyle() ### `<webview>.pasteAndMatchStyle()`
Executes editing command `pasteAndMatchStyle` in page. Executes editing command `pasteAndMatchStyle` in page.
### `<webview>`.delete() ### `<webview>.delete()`
Executes editing command `delete` in page. Executes editing command `delete` in page.
### `<webview>`.selectAll() ### `<webview>.selectAll()`
Executes editing command `selectAll` in page. Executes editing command `selectAll` in page.
### `<webview>`.unselect() ### `<webview>.unselect()`
Executes editing command `unselect` in page. Executes editing command `unselect` in page.
### `<webview>`.replace(text) ### `<webview.replace(text)`
* `text` String * `text` String
Executes editing command `replace` in page. Executes editing command `replace` in page.
### `<webview>`.replaceMisspelling(text) ### `<webview>.replaceMisspelling(text)`
* `text` String * `text` String
Executes editing command `replaceMisspelling` in page. Executes editing command `replaceMisspelling` in page.
### `<webview>`.print([options]) ### `<webview>.print([options])`
Prints webview's web page. Same with `webContents.print([options])`. Prints `webview`'s web page. Same with `webContents.print([options])`.
### `<webview>`.printToPDF(options, callback) ### `<webview>.printToPDF(options, callback)`
Prints webview's web page as PDF, Same with `webContents.printToPDF(options, callback)` Prints webview's web page as PDF, Same with `webContents.printToPDF(options, callback)`
### `<webview>`.send(channel[, args...]) ### `<webview>.send(channel[, args...])`
* `channel` String * `channel` String
* `arg` (optional)
Send `args..` to guest page via `channel` in asynchronous message, the guest 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. page can handle it by listening to the `channel` event of `ipc` module.
@ -335,7 +342,11 @@ examples.
## DOM events ## DOM events
### load-commit The following DOM events are available to the `webview` tag:
### Event: 'load-commit'
Returns:
* `url` String * `url` String
* `isMainFrame` Boolean * `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 document as well as subframe document-level loads, but does not include
asynchronous resource loads. 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 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 * `errorCode` Integer
* `errorDescription` String * `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 This event is like `did-finish-load`, but fired when the load failed or was
cancelled, e.g. `window.stop()` is invoked. cancelled, e.g. `window.stop()` is invoked.
### did-frame-finish-load ### Event: 'did-frame-finish-load'
Returns:
* `isMainFrame` Boolean * `isMainFrame` Boolean
Fired when a frame has done navigation. 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. 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. 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 * `status` Boolean
* `newUrl` String * `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. Fired when details regarding a requested resource is available.
`status` indicates socket connection to download the resource. `status` indicates socket connection to download the resource.
### did-get-redirect-request ### Event: 'did-get-redirect-request'
Returns:
* `oldUrl` String * `oldUrl` String
* `newUrl` 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. Fired when a redirect was received while requesting a resource.
### dom-ready ### Event: 'dom-ready'
Fired when document in the given frame is loaded. Fired when document in the given frame is loaded.
### page-title-set ### Event: 'page-title-set'
Returns:
* `title` String * `title` String
* `explicitSet` Boolean * `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 Fired when page title is set during navigation. `explicitSet` is false when title is synthesised from file
url. 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. 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 * `level` Integer
* `message` String * `message` String
@ -436,7 +461,9 @@ webview.addEventListener('console-message', function(e) {
}); });
``` ```
### new-window ### Event: 'new-window'
Returns:
* `url` String * `url` String
* `frameName` 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. 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 * `channel` String
* `args` Array * `args` Array
@ -493,21 +522,23 @@ ipc.on('ping', function() {
}); });
``` ```
### crashed ### Event: 'crashed'
Fired when the renderer process is crashed. Fired when the renderer process is crashed.
### gpu-crashed ### Event: 'gpu-crashed'
Fired when the gpu process is crashed. Fired when the gpu process is crashed.
### plugin-crashed ### Event: 'plugin-crashed'
Returns:
* `name` String * `name` String
* `version` String * `version` String
Fired when a plugin process is crashed. Fired when a plugin process is crashed.
### destroyed ### Event: 'destroyed'
Fired when the WebContents is destroyed. Fired when the WebContents is destroyed.

35
docs/api/window-open.md
View file

@ -1,22 +1,22 @@
# `window.open` function # The `window.open` function
When `window.open` is called to create a new window in web page, a new instance When `window.open` is called to create a new window in a web page, a new instance
of `BrowserWindow` will be created for the `url`, and a proxy will be returned of `BrowserWindow` will be created for the `url` and a proxy will be returned
to `window.open` to let the page have limited control over it. to `window.open` to let the page have limited control over it.
The proxy only has some limited standard functionality implemented to be The proxy has limited standard functionality implemented to be
compatible with traditional web pages, for full control of the created window compatible with traditional web pages. For full control of the new window
you should create a `BrowserWindow` directly. you should create a `BrowserWindow` directly.
## window.open(url, [frameName[, features]]) ### `window.open(url[, frameName][, features])`
* `url` String * `url` String
* `frameName` String * `frameName` String (optional)
* `features` String * `features` String (optional)
Creates a new window and returns an instance of `BrowserWindowProxy` class. Creates a new window and returns an instance of `BrowserWindowProxy` class.
## window.opener.postMessage(message, targetOrigin) ### `window.opener.postMessage(message, targetOrigin)`
* `message` String * `message` String
* `targetOrigin` String * `targetOrigin` String
@ -26,29 +26,32 @@ origin preference.
## Class: BrowserWindowProxy ## Class: BrowserWindowProxy
### BrowserWindowProxy.blur() The `BrowserWindowProxy` object is returned from `window.open` and provides
limited functionality with the child window.
### `BrowserWindowProxy.blur()`
Removes focus from the child window. Removes focus from the child window.
### BrowserWindowProxy.close() ### `BrowserWindowProxy.close()`
Forcefully closes the child window without calling its unload event. Forcefully closes the child window without calling its unload event.
### BrowserWindowProxy.closed ### `BrowserWindowProxy.closed`
Set to true after the child window gets closed. Set to true after the child window gets closed.
### BrowserWindowProxy.eval(code) ### `BrowserWindowProxy.eval(code)`
* `code` String * `code` String
Evaluates the code in the child window. Evaluates the code in the child window.
### BrowserWindowProxy.focus() ### `BrowserWindowProxy.focus()`
Focuses the child window (brings the window to front). Focuses the child window (brings the window to front).
### BrowserWindowProxy.postMessage(message, targetOrigin) ### `BrowserWindowProxy.postMessage(message, targetOrigin)`
* `message` String * `message` String
* `targetOrigin` String * `targetOrigin` String
@ -57,4 +60,4 @@ Sends a message to the child window with the specified origin or `*` for no
origin preference. origin preference.
In addition to these methods, the child window implements `window.opener` object In addition to these methods, the child window implements `window.opener` object
with no properties and a single method: with no properties and a single method.