This repository has been archived by the owner on Jan 31, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 246
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #169 from phonegap/browser-docs
Merging browser platform support docs into master.
- Loading branch information
Showing
31 changed files
with
332 additions
and
24 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 1,33 @@ | ||
| --- | ||
| title: PhoneGap Desktop Browser Support | ||
| url: references/browser-support | ||
| layout: subpage | ||
| expand: browser-support | ||
| --- | ||
|
|
||
| PhoneGap apps are built with web technologies providing the benefit of allowing you to use your desktop browser | ||
| to rapidly iterate through your development phases while taking advantage of the built-in developer tooling you already | ||
| know and love. | ||
|
|
||
| You can even design your app layout and test it across a variety of screen resolutions without moving to a physical device using tools like | ||
| the [Chrome mobile device emulators](https://developers.google.com/web/tools/chrome-devtools/iterate/device-mode/) and [Safari Responsive | ||
| Design Mode](https://developer.apple.com/safari/tools/). | ||
|
|
||
| ##### Chrome Developer Tools | ||
|  | ||
|
|
||
| ##### Safari Responsive Design Mode | ||
|  | ||
|
|
||
| ## Overview | ||
| The specific browser support referred to in this guide is different than just opening up your `index.html` from your `www` folder in | ||
| your browser as you may have done in the past. This includes support for the Apache Cordova core plugins and the Cordova `deviceready` event to aid | ||
| in your testing and debugging. | ||
|
|
||
| The browser as an initial platform target helps greatly reduce the challenges faced by mobile developers due | ||
| to platform fragmentation. It also provides the ability for a developer to build an app for both the | ||
| desktop web browser and mobile device where the additional native functionality is used only when running on the device by leveraging plugins. | ||
|
|
||
| The browser platform is not without its limitations, however, and developers should understand those limitations specifically | ||
| to get the most value from this new platform target during their development phase. Check out the | ||
| [Caution/Next Steps](/references/browser-support/caution-next-steps) section for more details. |
28 changes: 28 additions & 0 deletions
28
docs/3-references/browser-support/2-plugin-support.html.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 1,28 @@ | ||
| --- | ||
| title: Plugin Support | ||
| url: references/browser-support/plugin-support | ||
| github_url: https://github.com/phonegap/phonegap-docs/blob/master/docs/references/browser-support/2-plugin-support.html.md | ||
| layout: subpage | ||
| expand: browser-support | ||
| --- | ||
|
|
||
| The browser platform includes the ability to use any of the [Apache Cordova core plugins](/plugin-apis/) in your apps without disrupting your development. The level of support for them will vary depending on the type of functionality the plugin exposes. In some cases the browser version of the plugin may return mock data, and in other cases | ||
| it may simply fail silently. You can take a look in the `src/browser` folder of any of the core plugins to determine exactly what to expect. | ||
|
|
||
|  | ||
|
|
||
| For instance, take a look at the simple [DeviceProxy class](https://github.com/apache/cordova-plugin-device/tree/master/src/browser) | ||
| for the device plugin and you'll see how it uses the User Agent to determine the specific browser being used. | ||
| The [cordova-plugin-device-motion](https://github.com/apache/cordova-plugin-device-motion/blob/master/src/browser/AccelerometerProxy.js) | ||
| is one you can check out to see how it simply returns mock data. The idea is that you're able to debug your apps with some level of | ||
| support for the core plugins so you're not hung up on errors as a result of not running natively. | ||
|
|
||
| <div class="alert--info">**Note:** Check the plugin documentation for specific notes on the browser platform support for that particular plugin.</div> | ||
|
|
||
| Some of the core plugins use JavaScript API's that are actually supported in the Desktop browser natively, and in those cases the plugin will defer to use | ||
| them. For instance, `cordova-plugin-geolocation` uses an API that is already supported in Chrome, Safari and Firefox. | ||
|
|
||
| <div class="alert--tip">**TIP:** Check the [Can I Use](http://caniuse.com) site to see which JavaScript APIs are currently supported by a | ||
| given browser.</div> | ||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 1,14 @@ | ||
| --- | ||
| title: Multi-Device Testing | ||
| url: references/browser-support/multi-device | ||
| github_url: https://github.com/phonegap/phonegap-docs/blob/master/docs/references/browser-support/3-multi-device.html.md | ||
| layout: subpage | ||
| expand: browser-support | ||
| --- | ||
|
|
||
| ### Multiple Platform Support | ||
| The addition of the browser platform does not affect the multi-device functionality that was already present when serving apps. | ||
| You can now serve your apps and test them in the browser as well as on any Android, iOS or Windows device or simulator all at the | ||
| same time with live reloading, providing an efficient workflow for concurrent development and testing. | ||
|
|
||
|  |
40 changes: 40 additions & 0 deletions
40
docs/3-references/browser-support/4-custom-plugins.html.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 1,40 @@ | ||
| --- | ||
| title: Custom Plugins | ||
| url: references/browser-support/custom-plugins | ||
| github_url: https://github.com/phonegap/phonegap-docs/blob/master/docs/references/browser-support/4-custom-plugins.html.md | ||
| layout: subpage | ||
| expand: browser-support | ||
| --- | ||
|
|
||
| With the browser platform target support in PhoneGap, you also have the ability to write code handling for it specifically | ||
| when developing your own custom plugins. Some plugins will be easier to support it than others depending on what native feature they're exposing by allowing you to specify | ||
| mock data or simply returning a console message. It's up to the plugin author to determine what's most desired in that case. | ||
|
|
||
| To support the browser in your own plugins, follow the [Cordova Plugin Development docs](https://cordova.apache.org/docs/en/latest/plugin_ref/spec.html) on the Official Apache Cordova site | ||
| and ensure you've defined the `browser` platform handling in your `plugin.xml` mapping. You will define your JavaScript files | ||
| to implement your specific `browser` platform handling code in the `src/browser` | ||
| path in your plugin root. For instance: | ||
|
|
||
| <img class="mobile-image" src="/images/browser-support/custom-plugin.png"/> | ||
|
|
||
| You'll need to ensure you name these browser platform-specific JS files with different names then the client-side implementation included in the `www` by default. Most of the Apache Cordova plugins add the word `Proxy` to the | ||
| class. You can take a look at any of the [Apache Cordova core plugins](/plugin-apis/) for specific examples. | ||
|
|
||
| For instance, by taking a look at the Apache Cordova Camera [plugin.xml](https://github.com/apache/cordova-plugin-camera/blob/master/plugin.xml), | ||
| you will see how the `CameraProxy.js` class is defined with the following: | ||
|
|
||
| <!-- browser --> | ||
| <platform name="browser"> | ||
| <config-file target="config.xml" parent="/*"> | ||
| <feature name="Camera"> | ||
| <param name="browser-package" value="Camera" /> | ||
| </feature> | ||
| </config-file> | ||
|
|
||
| <js-module src="src/browser/CameraProxy.js" name="CameraProxy"> | ||
| <runs /> | ||
| </js-module> | ||
| </platform> | ||
| <div class="alert--tip">**Tip:** The `<runs/>` element is required to tell Cordova to initialize the module.</div> | ||
44 changes: 44 additions & 0 deletions
44
docs/3-references/browser-support/5-caution-next-steps.html.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 1,44 @@ | ||
| --- | ||
| title: Caution / Next Steps | ||
| url: references/browser-support/caution-next-steps | ||
| github_url: https://github.com/phonegap/phonegap-docs/blob/master/docs/references/browser-support/5-caution-next-steps.html.md | ||
| layout: subpage | ||
| expand: browser-support | ||
| --- | ||
|
|
||
| When you are developing an app to be consumed on a mobile device, it should go without saying that the best environment for testing | ||
| is going to be that target device itself. Some things to specifically note and keep in mind while testing with the browser platform | ||
| are listed below: | ||
|
|
||
| - The desktop browsers often differ in the support for certain features and APIs versus the mobile browsers, | ||
| and between platforms. You should refer to the [Can I Use](http://caniuse.com) site for specific details of which features your | ||
| apps use and what is supported. | ||
|
|
||
|  | ||
| - The browser does not have a soft keyboard to test with so you cannot test the effect it might have on the UI/screen layout when | ||
| using form controls/input fields. | ||
| - Certain devices may support hardware features that cannot be tested in a desktop browser. | ||
| - Apache Cordova Plugins expose native features that can't always be mocked properly since they are native to a platform. | ||
| - The application is being served from an IP address rather than a filesystem affecting the way security is handled. | ||
| - Performance testing for things like low battery, poor network coverage, low available memory and interrupt testing for | ||
| situations like incoming/outgoing calls, texts, notifications etc cannot be properly tested in the browser. | ||
|
|
||
|
|
||
| ### Development/Testing Options: | ||
| 1. Use the browser to develop as much of your app as possible with the tooling you already know and use daily while being aware of the limitations | ||
| noted above. | ||
|
|
||
| 2. Use the [PhoneGap Developer App](/references/developer-app/) on a physical device to pair and test your app being served from either | ||
| the PhoneGap CLI or the PhoneGap Desktop App in addition to the browser platform. See the [Getting Started Guides](/getting-started/2-install-mobile-app/) for more details. | ||
|
|
||
| 2. Get a compiled version of your app using the PhoneGap/Cordova CLI or [PhoneGap Build](http://build.phonegap.com) (to avoid having to set up platform SDK's) and test | ||
| on the platforms you're targeting with a physical device or simulator. Apple provides the [iOS simulator](https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/iOS_Simulator_Guide/Introduction/Introduction.html) | ||
| as part of Xcode, and Google offers the [Android Emulator](http://developer.android.com/tools/help/emulator.html) as part of the Android developer | ||
| tools. There's also the [Genymotion](http://genymotion.com/) emulator which can be used to test your Android apps and often runs faster than the emulator packaged in the Android tooling. | ||
|
|
||
| 2. Leverage mobile testing and automation services ([Sauce Labs](https://saucelabs.com), [Testmunk](https://testmunk.com/), | ||
| [Appium](http://appium) etc) and mobile app intelligence services ([Apteligent](https://www.apteligent.com/), [Crashlytics](https://try.crashlytics.com/)) to | ||
| provide crash test reporting and other analytics to ensure your app is providing the best user experience once delivered. | ||
|
|
||
| <div class="alert--info">**Note:** Make a point to check out this [Next Steps Guide](https://cordova.apache.org/docs/en/latest/guide/next/index.html) | ||
| in the Apache Cordova docs for more information on testing, remote debugging and more.</div> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 1,42 @@ | ||
| --- | ||
| title: Usage | ||
| url: references/browser-support/usage/desktop | ||
| github_url: https://github.com/phonegap/phonegap-docs/blob/master/docs/references/browser-support/usage/1-desktop.html.md | ||
| layout: subpage | ||
| tabs: | ||
| - label: Desktop App | ||
| url: references/browser-support/usage/desktop | ||
| - label: CLI | ||
| url: references/browser-support/usage/cli | ||
| expand: browser-support | ||
| --- | ||
|
|
||
| <div class="alert--warning">You should ensure you have the [latest version](/getting-started/1-install-phonegap/desktop) of PhoneGap Desktop | ||
| before getting started.</div> | ||
|
|
||
| PhoneGap makes it easy to take advantage of the browser target by automatically adding it as an additional platform when your apps are | ||
| *served* (run on a local web server). | ||
|
|
||
| In the image below, when the arrow (>) is green it implies that PhoneGap project is being served on the IP Address shown in the green bar at the bottom. | ||
|
|
||
|  | ||
|
|
||
| You can then open that IP Address directly in your browser (or via `http://localhost:<portNumber>`) | ||
| and start debugging. You can also start making edits to your source code and see the changes immediately in the browser without having to | ||
| restart due to the built-in live reload feature. | ||
|
|
||
|  | ||
|
|
||
| <div class="alert--tip">**TIP:** You can change the port number used for serving your projects via the [PhoneGap Desktop settings](/references/desktop-app/edit-settings).</div> | ||
|
|
||
| <div class="alert--info">**Note:** If you're new to PhoneGap Desktop, check out the [Getting Started guide](/getting-started/1-install-phonegap/desktop).</div> | ||
|
|
||
| The browser platform support ensures the `deviceready` event is fired in the browser and allows you to use all of the core plugins without | ||
| disrupting your development. | ||
|
|
||
|  | ||
|
|
||
| <div class="alert--info">**Note:** Check out the [plugin support section](/references/browser-support/plugin-support) for more details on how | ||
| plugins can be used in the browser.</div> | ||
|
|
||
|
|
Oops, something went wrong.