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

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

View file

@ -1,46 +1,51 @@
# 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.
An example of zooming current page to 200%.
```javascript
var webFrame = require('web-frame');
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
zoom percent / 100, so 300% = 3.0.
### `webFrame.setZoomFactor(factor)`
## 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.
## webFrame.setZoomLevel(level)
### `webFrame.setZoomLevel(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
limits of 300% and 50% of original size, respectively.
## webFrame.getZoomLevel()
### `webFrame.getZoomLevel()`
Returns the current zoom level.
## webFrame.setZoomLevelLimits(minimumLevel, maximumLevel)
### `webFrame.setZoomLevelLimits(minimumLevel, maximumLevel)`
* `minimumLevel` Number
* `maximumLevel` Number
Sets the maximum and minimum zoom level.
## webFrame.setSpellCheckProvider(language, autoCorrectWord, provider)
### `webFrame.setSpellCheckProvider(language, autoCorrectWord, provider)`
* `language` String
* `autoCorrectWord` Boolean
@ -61,7 +66,7 @@ require('web-frame').setSpellCheckProvider("en-US", true, {
});
```
## webFrame.registerUrlSchemeAsSecure(scheme)
### `webFrame.registerUrlSchemeAsSecure(scheme)`
* `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
attackers.
## webFrame.registerUrlSchemeAsBypassingCsp(scheme)
### `webFrame.registerUrlSchemeAsBypassingCsp(scheme)`
* `scheme` String
Resources will be loaded from this `scheme` regardless of
page's Content Security Policy.
Resources will be loaded from this `scheme` regardless of the current page's
Content Security Policy.
[spellchecker]: https://github.com/atom/node-spellchecker

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
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 embedded 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
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
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:
</script>
```
## Tag attributes
## Tag Attributes
### src
The `webview` tag has the following attributes:
### `src`
```html
<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
`data:text/plain,Hello, world!`.
### autosize
### `autosize`
```html
<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
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
<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
APIs like `require` and `process` to access low level system resources.
### plugins
### `plugins`
```html
<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.
### preload
### `preload`
```html
<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
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
<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.
### useragent
### `useragent`
```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>
```
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
<webview src="https://www.github.com/" disablewebsecurity></webview>
@ -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() {
});
```
### `<webview>`.getUrl()
### `<webview>.getUrl()`
Returns URL of guest page.
### `<webview>`.getTitle()
### `<webview>.getTitle()`
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
of the page.
Returns a boolean whether the guest page is waiting for a first-response for the
main resource of the page.
### `<webview>`.stop()
### `<webview>.stop()`
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
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.
### `<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
Navigates to the specified absolute index.
### `<webview>`.goToOffset(offset)
### `<webview>.goToOffset(offset)`
* `offset` Integer
Navigates to the specified offset from the "current entry".
### `<webview>`.isCrashed()
### `<webview>.isCrashed()`
Whether the renderer process has crashed.
### `<webview>`.setUserAgent(userAgent)
### `<webview>.setUserAgent(userAgent)`
* `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
Injects CSS into guest page.
Injects CSS into the guest page.
### `<webview>`.executeJavaScript(code, userGesture)
### `<webview>.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 the create user
gesture context in the page. HTML APIs like `requestFullScreen`, which require
user action, can take advantage of this option for automation.
### `<webview>`.openDevTools()
### `<webview>.openDevTools()`
Opens a devtools window for guest page.
### `<webview>`.closeDevTools()
### `<webview>.closeDevTools()`
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
* `y` Integer
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.
### `<webview>`.setAudioMuted(muted)
### `<webview>.setAudioMuted(muted)`
+ `muted` Boolean
* `muted` Boolean
Set guest page muted.
### `<webview>`.isAudioMuted()
### `<webview>.isAudioMuted()`
Returns whether guest page has been muted.
### `<webview>`.undo()
### `<webview>.undo()`
Executes editing command `undo` in page.
### `<webview>`.redo()
### `<webview>.redo()`
Executes editing command `redo` in page.
### `<webview>`.cut()
### `<webview>.cut()`
Executes editing command `cut` in page.
### `<webview>`.copy()
### `<webview>.copy()`
Executes editing command `copy` in page.
### `<webview>`.paste()
### `<webview>.paste()`
Executes editing command `paste` in page.
### `<webview>`.pasteAndMatchStyle()
### `<webview>.pasteAndMatchStyle()`
Executes editing command `pasteAndMatchStyle` in page.
### `<webview>`.delete()
### `<webview>.delete()`
Executes editing command `delete` in page.
### `<webview>`.selectAll()
### `<webview>.selectAll()`
Executes editing command `selectAll` in page.
### `<webview>`.unselect()
### `<webview>.unselect()`
Executes editing command `unselect` in page.
### `<webview>`.replace(text)
### `<webview.replace(text)`
* `text` String
Executes editing command `replace` in page.
### `<webview>`.replaceMisspelling(text)
### `<webview>.replaceMisspelling(text)`
* `text` String
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)`
### `<webview>`.send(channel[, args...])
### `<webview>.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.

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
of `BrowserWindow` will be created for the `url`, and a proxy will be returned
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
to `window.open` to let the page have limited control over it.
The proxy only has some limited standard functionality implemented to be
compatible with traditional web pages, for full control of the created window
The proxy has limited standard functionality implemented to be
compatible with traditional web pages. For full control of the new window
you should create a `BrowserWindow` directly.
## window.open(url, [frameName[, features]])
### `window.open(url[, frameName][, features])`
* `url` String
* `frameName` String
* `features` String
* `frameName` String (optional)
* `features` String (optional)
Creates a new window and returns an instance of `BrowserWindowProxy` class.
## window.opener.postMessage(message, targetOrigin)
### `window.opener.postMessage(message, targetOrigin)`
* `message` String
* `targetOrigin` String
@ -26,29 +26,32 @@ origin preference.
## 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.
### BrowserWindowProxy.close()
### `BrowserWindowProxy.close()`
Forcefully closes the child window without calling its unload event.
### BrowserWindowProxy.closed
### `BrowserWindowProxy.closed`
Set to true after the child window gets closed.
### BrowserWindowProxy.eval(code)
### `BrowserWindowProxy.eval(code)`
* `code` String
Evaluates the code in the child window.
### BrowserWindowProxy.focus()
### `BrowserWindowProxy.focus()`
Focuses the child window (brings the window to front).
### BrowserWindowProxy.postMessage(message, targetOrigin)
### `BrowserWindowProxy.postMessage(message, targetOrigin)`
* `message` String
* `targetOrigin` String
@ -57,4 +60,4 @@ Sends a message to the child window with the specified origin or `*` for no
origin preference.
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.