From aac2db29b56f599f6f380adf390bf62f9c2c3e22 Mon Sep 17 00:00:00 2001 From: Andrew Grieve Date: Wed, 18 Dec 2013 15:31:18 -0500 Subject: [PATCH] CB-5658 Add doc.index.md for InAppBrowser plugin --- README.md | 25 ++++- doc/index.md | 280 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 301 insertions(+), 4 deletions(-) create mode 100644 doc/index.md diff --git a/README.md b/README.md index 74c7dfa..2f47707 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,22 @@ -cordova-plugin-inappbrowser ------------------------------ -To install this plugin, follow the [Command-line Interface Guide](http://cordova.apache.org/docs/en/edge/guide_cli_index.md.html#The%20Command-line%20Interface). + + +# org.apache.cordova.inappbrowser + +Plugin documentation: [doc/index.md](doc/index.md) diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000..db8efd1 --- /dev/null +++ b/doc/index.md @@ -0,0 +1,280 @@ + + +# org.apache.cordova.inappbrowser + +This plugin provides a web browser view that displays when calling `window.open()`, or when opening a link formed as ``. + + var ref = window.open('http://apache.org', '_blank', 'location=yes'); + +__NOTE__: The InAppBrowser window behaves like a standard web browser, +and can't access Cordova APIs. + +## Installation + + cordova plugin add org.apache.cordova.inappbrowser + +## window.open + +Opens a URL in a new `InAppBrowser` instance, the current browser +instance, or the system browser. + + var ref = window.open(url, target, options); + +- __ref__: Reference to the `InAppBrowser` window. _(InAppBrowser)_ + +- __url__: The URL to load _(String)_. Call `encodeURI()` on this if the URL contains Unicode characters. + +- __target__: The target in which to load the URL, an optional parameter that defaults to `_self`. _(String)_ + + - `_self`: Opens in the Cordova WebView if the URL is in the white list, otherwise it opens in the `InAppBrowser`. + - `_blank`: Opens in the `InAppBrowser`. + - `_system`: Opens in the system's web browser. + +- __options__: Options for the `InAppBrowser`. Optional, defaulting to: `location=yes`. _(String)_ + + The `options` string must not contain any blank space, and each feature's name/value pairs must be separated by a comma. Feature names are case insensitive. All platforms support the value below: + + - __location__: Set to `yes` or `no` to turn the `InAppBrowser`'s location bar on or off. + + Android only: + + - __closebuttoncaption__: set to a string to use as the __Done__ button's caption. + - __hidden__: set to `yes` to create the browser and load the page, but not show it. The load event fires when loading is complete. Omit or set to `no` (default) to have the browser open and load normally. + - __clearcache__: set to `yes` to have the browser's cookie cache cleared before the new window is opened + - __clearsessioncache__: set to `yes` to have the session cookie cache cleared before the new window is opened + + iOS only: + + - __closebuttoncaption__: set to a string to use as the __Done__ button's caption. Note that you need to localize this value yourself. + - __disallowoverscroll__: Set to `yes` or `no` (default is `no`). Turns on/off the UIWebViewBounce property. + - __hidden__: set to `yes` to create the browser and load the page, but not show it. The load event fires when loading is complete. Omit or set to `no` (default) to have the browser open and load normally. + - __toolbar__: set to `yes` or `no` to turn the toolbar on or off for the InAppBrowser (defaults to `yes`) + - __enableViewportScale__: Set to `yes` or `no` to prevent viewport scaling through a meta tag (defaults to `no`). + - __mediaPlaybackRequiresUserAction__: Set to `yes` or `no` to prevent HTML5 audio or video from autoplaying (defaults to `no`). + - __allowInlineMediaPlayback__: Set to `yes` or `no` to allow in-line HTML5 media playback, displaying within the browser window rather than a device-specific playback interface. The HTML's `video` element must also include the `webkit-playsinline` attribute (defaults to `no`) + - __keyboardDisplayRequiresUserAction__: Set to `yes` or `no` to open the keyboard when form elements receive focus via JavaScript's `focus()` call (defaults to `yes`). + - __suppressesIncrementalRendering__: Set to `yes` or `no` to wait until all new view content is received before being rendered (defaults to `no`). + - __presentationstyle__: Set to `pagesheet`, `formsheet` or `fullscreen` to set the [presentation style](http://developer.apple.com/library/ios/documentation/UIKit/Reference/UIViewController_Class/Reference/Reference.html#//apple_ref/occ/instp/UIViewController/modalPresentationStyle) (defaults to `fullscreen`). + - __transitionstyle__: Set to `fliphorizontal`, `crossdissolve` or `coververtical` to set the [transition style](http://developer.apple.com/library/ios/#documentation/UIKit/Reference/UIViewController_Class/Reference/Reference.html#//apple_ref/occ/instp/UIViewController/modalTransitionStyle) (defaults to `coververtical`). + - __toolbarposition__: Set to `top` or `bottom` (default is `bottom`). Causes the toolbar to be at the top or bottom of the window. + +### Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- iOS +- Windows Phone 7 and 8 + +### Example + + var ref = window.open('http://apache.org', '_blank', 'location=yes'); + var ref2 = window.open(encodeURI('http://ja.m.wikipedia.org/wiki/ハングル'), '_blank', 'location=yes'); + +## InAppBrowser + +The object returned from a call to `window.open`. + +### Methods + +- addEventListener +- removeEventListener +- close +- show +- executeScript +- insertCSS + +## addEventListener + +> Adds a listener for an event from the `InAppBrowser`. + + ref.addEventListener(eventname, callback); + +- __ref__: reference to the `InAppBrowser` window _(InAppBrowser)_ + +- __eventname__: the event to listen for _(String)_ + + - __loadstart__: event fires when the `InAppBrowser` starts to load a URL. + - __loadstop__: event fires when the `InAppBrowser` finishes loading a URL. + - __loaderror__: event fires when the `InAppBrowser` encounters an error when loading a URL. + - __exit__: event fires when the `InAppBrowser` window is closed. + +- __callback__: the function that executes when the event fires. The function is passed an `InAppBrowserEvent` object as a parameter. + +### InAppBrowserEvent Properties + +- __type__: the eventname, either `loadstart`, `loadstop`, `loaderror`, or `exit`. _(String)_ + +- __url__: the URL that was loaded. _(String)_ + +- __code__: the error code, only in the case of `loaderror`. _(Number)_ + +- __message__: the error message, only in the case of `loaderror`. _(String)_ + + +### Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- iOS +- Windows Phone 7 and 8 + +### Quick Example + + var ref = window.open('http://apache.org', '_blank', 'location=yes'); + ref.addEventListener('loadstart', function() { alert(event.url); }); + +## removeEventListener + +> Removes a listener for an event from the `InAppBrowser`. + + ref.removeEventListener(eventname, callback); + +- __ref__: reference to the `InAppBrowser` window. _(InAppBrowser)_ + +- __eventname__: the event to stop listening for. _(String)_ + + - __loadstart__: event fires when the `InAppBrowser` starts to load a URL. + - __loadstop__: event fires when the `InAppBrowser` finishes loading a URL. + - __loaderror__: event fires when the `InAppBrowser` encounters an error loading a URL. + - __exit__: event fires when the `InAppBrowser` window is closed. + +- __callback__: the function to execute when the event fires. +The function is passed an `InAppBrowserEvent` object. + +### Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- iOS +- Windows Phone 7 and 8 + +### Quick Example + + var ref = window.open('http://apache.org', '_blank', 'location=yes'); + var myCallback = function() { alert(event.url); } + ref.addEventListener('loadstart', myCallback); + ref.removeEventListener('loadstart', myCallback); + +## close + +> Closes the `InAppBrowser` window. + + ref.close(); + +- __ref__: reference to the `InAppBrowser` window _(InAppBrowser)_ + +### Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- iOS +- Windows Phone 7 and 8 + +### Quick Example + + var ref = window.open('http://apache.org', '_blank', 'location=yes'); + ref.close(); + +## show + +> Displays an InAppBrowser window that was opened hidden. Calling this has no effect if the InAppBrowser was already visible. + + ref.show(); + +- __ref__: reference to the InAppBrowser window (`InAppBrowser`) + +### Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- iOS + +### Quick Example + + var ref = window.open('http://apache.org', '_blank', 'hidden=yes'); + // some time later... + ref.show(); + +## executeScript + +> Injects JavaScript code into the `InAppBrowser` window + + ref.executeScript(details, callback); + +- __ref__: reference to the `InAppBrowser` window. _(InAppBrowser)_ + +- __injectDetails__: details of the script to run, specifying either a `file` or `code` key. _(Object)_ + - __file__: URL of the script to inject. + - __code__: Text of the script to inject. + +- __callback__: the function that executes after the JavaScript code is injected. + - If the injected script is of type `code`, the callback executes + with a single parameter, which is the return value of the + script, wrapped in an `Array`. For multi-line scripts, this is + the return value of the last statement, or the last expression + evaluated. + +### Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- iOS + +### Quick Example + + var ref = window.open('http://apache.org', '_blank', 'location=yes'); + ref.addEventListener('loadstop', function() { + ref.executeScript({file: "myscript.js"}); + }); + +## insertCSS + +> Injects CSS into the `InAppBrowser` window. + + ref.insertCSS(details, callback); + +- __ref__: reference to the `InAppBrowser` window _(InAppBrowser)_ + +- __injectDetails__: details of the script to run, specifying either a `file` or `code` key. _(Object)_ + - __file__: URL of the stylesheet to inject. + - __code__: Text of the stylesheet to inject. + +- __callback__: the function that executes after the CSS is injected. + +### Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- iOS + +### Quick Example + + var ref = window.open('http://apache.org', '_blank', 'location=yes'); + ref.addEventListener('loadstop', function() { + ref.insertCSS({file: "mystyles.css"}); + }); +