|
1 | | -# NativeScript Webview Plugins |
| 1 | +<!-- ⚠️ This README has been generated from the file(s) "blueprint.md" ⚠️-->This monorepo contains multiple packages:<br><br><details> |
| 2 | +<summary><b>ui-webview</b></summary> |
| 3 | +{{ load:packages/ui-webview/README.md }} |
| 4 | +</details><details> |
| 5 | +<summary><b>webview</b></summary> |
| 6 | +# @nativescript-community/ui-webview |
2 | 7 |
|
3 | | -This is the home of the mono repo for WebView plugins |
4 | | ---- |
5 | | -## Plugins |
6 | | -1. [@nativescript-community/ui-webview](./packages/webview/README.md) |
7 | | -2. [@nativescript-community/ui-webview-rtc](./packages/webview-rtc/README.md) |
| 8 | +Extended WebView for NativeScript which adds many options. |
| 9 | +The code is originally based on [nativescript-webview-ext](https://github.com/m-abs/nativescript-webview-ext) |
| 10 | + |
| 11 | + |
| 12 | +[](#features) |
| 13 | + |
| 14 | +## Features |
| 15 | +* Adds a custom-scheme handler for x-local:// to the webview for loading of resources inside the webview. |
| 16 | + * Note: For iOS 11+ WKWebView is used, but for iOS <11 UIWebView is used |
| 17 | +* Adds support for capturing URLs. |
| 18 | + * This allows the app to open external links in an external browser and handle tel-links |
| 19 | +* Added functions like: |
| 20 | + - `executeJavaScript(code: string)` for executing JavaScript-code and getting result. |
| 21 | + - `executePromise(code: string)` for calling promises and getting the result. |
| 22 | + - `getTitle()` returns document.title. |
| 23 | +* Adds functions to inject `css`- and `javascript`-files. |
| 24 | + * Into the current page. |
| 25 | + * Auto-injected on page load. |
| 26 | + |
| 27 | +* Supports: |
| 28 | + * Android 19+ |
| 29 | + * iOS 9+ |
| 30 | + |
| 31 | + |
| 32 | +[](#installation) |
| 33 | + |
| 34 | +## Installation |
| 35 | + |
| 36 | +Describe your plugin installation steps. Ideally it would be something like: |
| 37 | + |
| 38 | +```bash |
| 39 | +tns plugin add @nativescript-community/ui-webview |
| 40 | +``` |
| 41 | + |
| 42 | +### Angular support |
| 43 | + |
| 44 | +Import `AWebViewModule` from `@nativescript-community/ui-webview/angular` and add it to your `NgModule`. |
| 45 | + |
| 46 | +This registers the element `AWebView`. Replace the <WebView> tag with <AWebView> |
| 47 | + |
| 48 | +### Vue support |
| 49 | + |
| 50 | +```js |
| 51 | +import Vue from 'nativescript-vue'; |
| 52 | +import WebViewPlugin from '@nativescript-community/ui-webview/vue'; |
| 53 | + |
| 54 | +Vue.use(WebViewPlugin); |
| 55 | +``` |
| 56 | +This registers the element `AWebView`. Replace the <WebView> tag with <AWebView> |
| 57 | + |
| 58 | + |
| 59 | + |
| 60 | +[](#usage) |
| 61 | + |
| 62 | +## Usage |
| 63 | + |
| 64 | + |
| 65 | +[](#limitations) |
| 66 | + |
| 67 | +## Limitations |
| 68 | + |
| 69 | +In order to intercept requests for the custom scheme, we use `UIWebView` for iOS 9 and 10 and `WKWebView` for iOS 11+. |
| 70 | + |
| 71 | +iOS 11 added support for setting a `WKURLSchemeHandler` on the `WKWebView`. |
| 72 | +Prior to iOS 11 there isn't support for intercepting the URL with `WKWebView`, so we use a custom `NSURLProtocol` + `UIWebView`. |
| 73 | + |
| 74 | +### Important: |
| 75 | +The custom `NSURLProtocol` used with UIWebView is shared with all instances of the AWebView, so mapping `x-local://local-filename.js` => `file://app/full/path/local-filename.js` is shared between them. |
| 76 | + |
| 77 | + |
| 78 | +[](#api) |
| 79 | + |
| 80 | +## API |
| 81 | + |
| 82 | +### NativeScript View |
| 83 | + |
| 84 | +| Property | Value | Description | |
| 85 | +| --- | --- | --- | |
| 86 | +| readonly isUIWebView | true / false | Is the native webview an UIWebView? True if `iOS <11` | |
| 87 | +| readonly isWkWebView | true / false | Is the native webview an WKWebView? True if `iOS >=11` | |
| 88 | +| src | | Load src | |
| 89 | +| autoInjectJSBridge | true / false | Should the window.nsWebViewBridge be injected on `loadFinishedEvent`? Defaults to true | |
| 90 | +| builtInZoomControls | true / false | Android: Is the built-in zoom mechanisms being used | |
| 91 | +| cacheMode | default / no_cache / cache_first / cache_only | Android: Set caching mode. | |
| 92 | +| databaseStorage | true / false | Android: Enable/Disabled database storage API. Note: It affects all webviews in the process. | |
| 93 | +| debugMode | true / false | Android: Enable chrome debugger for webview on Android. Note: Applies to all webviews in App | |
| 94 | +| displayZoomControls | true / false | Android: displays on-screen zoom controls when using the built-in zoom mechanisms | |
| 95 | +| domStorage | true / false | Android: Enable/Disabled DOM Storage API. E.g localStorage | |
| 96 | +| scalesPageToFit | UIWebView: Should webpage scale to fit the view? Defaults to false | |
| 97 | +| scrollBounce | true / false | iOS: Should the scrollView bounce? Defaults to true. | |
| 98 | +| supportZoom | true / false | Android: should the webview support zoom | |
| 99 | +| viewPortSize | false / view-port string / ViewPortProperties | Set the viewport metadata on load finished. **Note:** WkWebView sets initial-scale=1.0 by default. | |
| 100 | +| limitsNavigationsToAppBoundDomains | false | iOS: allows to enable Service Workers **Note:** If set to true, WKAppBoundDomains also should be set in info.plist. | |
| 101 | +| scrollBarIndicatorVisible | false | Allow to hide scrollbars. | |
| 102 | + |
| 103 | +| Function | Description | |
| 104 | +| --- | --- | |
| 105 | +| loadUrl(src: string): Promise<LoadFinishedEventData> | Open a URL and resolves a promise once it has finished loading. | |
| 106 | +| registerLocalResource(resourceName: string, path: string): void; | Map the "x-local://{resourceName}" => "{path}". | |
| 107 | +| unregisterLocalResource(resourceName: string): void; | Removes the mapping from "x-local://{resourceName}" => "{path}" | |
| 108 | +| getRegisteredLocalResource(resourceName: string): void; | Get the mapping from "x-local://{resourceName}" => "{path}" | |
| 109 | +| loadJavaScriptFile(scriptName: string, filepath: string) | Inject a javascript-file into the webview. Should be called after the `loadFinishedEvent` | |
| 110 | +| loadStyleSheetFile(stylesheetName: string, filepath: string, insertBefore: boolean) | Loads a CSS-file into document.head. If before is true, it will be added to the top of document.head otherwise as the last element | |
| 111 | +| loadJavaScriptFiles(files: {resourceName: string, filepath: string}[]) | Inject multiple javascript-files into the webview. Should be called after the `loadFinishedEvent` | |
| 112 | +| loadStyleSheetFiles(files: {resourceName: string, filepath: string, insertBefore: boolean}[]) | Loads multiple CSS-files into the document.head. If before is true, it will be added to the top of document.head otherwise as the last element | |
| 113 | +| autoLoadJavaScriptFile(resourceName: string, filepath: string) | Register a JavaScript-file to be injected on `loadFinishedEvent`. If a page is already loaded, the script will be injected into the current page. | |
| 114 | +| autoLoadStyleSheetFile(resourceName: string, filepath: string, insertBefore?: boolean) | Register a CSS-file to be injected on `loadFinishedEvent`. If a page is already loaded, the CSS-file will be injected into the current page. | |
| 115 | +| autoExecuteJavaScript(scriptCode: string, name: string) | Execute a script on `loadFinishedEvent`. The script can be a promise | |
| 116 | +| executeJavaScript(scriptCode: string) | Execute JavaScript in the webpage. *Note:* scriptCode should be ES5 compatible, or it might not work on 'iOS < 11' | |
| 117 | +| executePromise(scriptCode: string, timeout: number = 500) | Run a promise inside the webview. *Note:* Executing scriptCode must return a promise. | |
| 118 | +| emitToWebView(eventName: string, data: any) | Emit an event to the webview. Note: data must be stringify'able with JSON.stringify or this throws an exception. | |
| 119 | +| getTitle() | Returns a promise with the current document title. | |
| 120 | + |
| 121 | + |
| 122 | +[](#events) |
| 123 | + |
| 124 | +## Events |
| 125 | +| Event | Description | |
| 126 | +| --- | --- | |
| 127 | +| loadFinished | Raised when a loadFinished event occurs. args is a `LoadFinishedEventData` | |
| 128 | +| loadProgress | Android only: Raised during page load to indicate the progress. args is a `LoadProgressEventData` | |
| 129 | +| loadStarted | Raised when a loadStarted event occurs. args is a `LoadStartedEventData` | |
| 130 | +| shouldOverrideUrlLoading | Raised before the webview requests an URL. Can cancelled by setting args.cancel = true in the `ShouldOverrideUrlLoadEventData` | |
| 131 | +| titleChanged | Document title changed | |
| 132 | +| webAlert | Raised when `window.alert` is triggered inside the webview, needed to use customs dialogs for web alerts. args in a `WebAlertEventData`. `args.callback()` must be called to indicate alert is closed. **NOTE:** Not supported by UIWebView | |
| 133 | +| webConfirm | Raised when `window.confirm` is triggered inside the webview, needed to use customs dialogs for web confirm boxes. args in a `webConfirmEvent`. `args.callback(boolean)` must be called to indicate confirm box is closed. **NOTE:** Not supported by UIWebView | |
| 134 | +| webConsole | Android only: Raised when a line is added to the web console. args is a `WebConsoleEventData`. | |
| 135 | +| webPrompt | Raised when `window.prompt` is triggered inside the webview, needed to use customs dialogs for web prompt boxes. args in a `webConfirmEvent`. `args.callback(string | null)` must be called to indicate prompt box is closed. **NOTE:** Not supported by UIWebView | |
| 136 | +| Events emitted from the webview | Raised when nsWebViewBridge.emit(...) is called inside the webview. args in an `WebViewEventData` | |
| 137 | + |
| 138 | +### WebView |
| 139 | + |
| 140 | +Inside the WebView we have the `nsWebViewBridge` for sending events between the `NativeScript`-layer and the `WebView`. |
| 141 | +**Note:** The bridge will only be available `DOMContentLoaded` or `onload` inside the WebView. |
| 142 | + |
| 143 | +| Function | Description | |
| 144 | +| --- | --- | |
| 145 | +| window.nsWebViewBridge.on(eventName: string, cb: (data: any) => void) | Registers handlers for events from the native layer. | |
| 146 | +| window.nsWebViewBridge.off(eventName: string, cb?: (data: any) => void) | Unregister handlers for events from the native layer. | |
| 147 | +| window.nsWebViewBridge.emit(eventName: string, data: any) | Emits event to NativeScript layer. Will be emitted on the AWebView as any other event, data will be a part of the WebViewEventData-object | |
| 148 | + |
| 149 | + |
| 150 | +[](#possible-features-to-come) |
| 151 | + |
| 152 | +## Possible features to come: |
| 153 | + |
| 154 | +* Cookie helpers? |
| 155 | +* Setting view-port metadata? |
| 156 | +* Share cache with native-layer? |
| 157 | + |
| 158 | +### Android |
| 159 | +* Settings |
| 160 | + * AppCache? |
| 161 | + * User agent? |
| 162 | + |
| 163 | +#### iOS |
| 164 | +* Settings? |
| 165 | + |
| 166 | + |
| 167 | +[](#demo-and-unit-tests) |
| 168 | + |
| 169 | +## Demo and unit tests |
| 170 | + |
| 171 | +### Running the demo |
| 172 | + |
| 173 | +To run the demo-project, the plugin must be build locally and a http-server must be running. |
| 174 | + |
| 175 | +The easiest way to run the demo is to follow these steps: |
| 176 | +- Clone the git repository from https://github.com/nativescript-community/ui-webview.git |
| 177 | +- Go into the `src`-folder |
| 178 | +- Use the npm-scripts: |
| 179 | + - npm run demo.ios |
| 180 | + - npm run demo.android |
| 181 | + |
| 182 | +### Running the unit-tests |
| 183 | + |
| 184 | +- Clone the git repository from https://github.com/nativescript-community/ui-webview.git |
| 185 | +- Go into the `src`-folder |
| 186 | +- Use the npm-scripts: |
| 187 | + - npm run test.ios |
| 188 | + - npm run test.android |
| 189 | + |
| 190 | + |
| 191 | +[](#license) |
| 192 | + |
| 193 | +## License |
| 194 | + |
| 195 | +Apache License Version 2.0, January 2004 |
| 196 | + |
| 197 | + |
| 198 | +[](#about-nota) |
| 199 | + |
| 200 | +## About Nota |
| 201 | + |
| 202 | +Nota is the Danish Library and Expertise Center for people with print disabilities. |
| 203 | +To become a member of Nota you must be able to document that you cannot read ordinary printed text. Members of Nota are visually impaired, dyslexic or otherwise impaired. |
| 204 | +Our purpose is to ensure equal access to knowledge, community participation and experiences for people who're unable to read ordinary printed text. |
| 205 | + |
| 206 | +</details><details> |
| 207 | +<summary><b>webview-rtc</b></summary> |
| 208 | + |
| 209 | +[](#nativescript-webview-rtc) |
| 210 | + |
| 211 | +# NativeScript WebView RTC |
| 212 | +[](https://www.npmjs.com/package/@nativescript-community/ui-webview-rtc) |
| 213 | +[](https://www.npmjs.com/package/@nativescript-community/ui-webview-rtc) |
| 214 | +[](https://www.npmjs.com/package/@nativescript-community/ui-webview-rtc) |
| 215 | + |
| 216 | +A NativeScript Plugin to add webRTC support to `@nativescript-community/ui-webview` |
| 217 | + |
| 218 | + |
| 219 | +[](#installation) |
| 220 | + |
| 221 | +## Installation |
| 222 | +Run the following command from the root of your project: |
| 223 | + |
| 224 | +`tns plugin add @nativescript-community/ui-webview-rtc` |
| 225 | + |
| 226 | +This command automatically installs the necessary files, as well as stores @nativescript-community/ui-webview-rtc as a dependency in your project's package.json file. |
| 227 | + |
| 228 | + |
| 229 | +[](#configuration) |
| 230 | + |
| 231 | +## Configuration |
| 232 | + |
| 233 | +To install the plugin run |
| 234 | +```typescript |
| 235 | +import install from '@nativescript-community/ui-webview-rtc'; |
| 236 | +install(); |
| 237 | +``` |
| 238 | + |
| 239 | +then simply use the `webRTC="true"` as a webview property |
| 240 | + |
| 241 | +</details> |
0 commit comments