http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/edge/guide/cli/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/edge/guide/cli/index.md b/www/docs/en/edge/guide/cli/index.md deleted file mode 100644 index 87334e0..0000000 --- a/www/docs/en/edge/guide/cli/index.md +++ /dev/null @@ -1,562 +0,0 @@ ---- -license: > - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - -title: The Command-Line Interface ---- - -# The Command-Line Interface - -This guide shows you how to create applications and deploy them to -various native mobile platforms using the `cordova` command-line -interface (CLI). This tool allows you to create new projects, build -them on different platforms, and run on real devices or within -emulators. The CLI is the main tool to use for the cross-platform -workflow described in the [Overview](../overview/index.html). Otherwise you can also use the -CLI to initialize project code, then switch to various platforms' SDKs -and shell tools for continued development. - -## Prerequisites - -Before running any command-line tools, you need to install SDKs for -each platform you wish to target. -(See the [Platform Guides](../platforms/index.html) for more details.) - -To add support or rebuild a project for any platform, you need to run -the command-line interface from the same machine that supports the -platform's SDK. The CLI supports the following combinations: - -* iOS (Mac) -* Amazon Fire OS (Mac, Linux, Windows) -* Android (Mac, Linux, Windows) -* BlackBerry 10 (Mac, Linux, Windows) -* Windows Phone 8 (Windows) -* Windows (Windows) -* Firefox OS (Mac, Linux, Windows) - -On the Mac, the command-line is available via the _Terminal_ -application. On the PC, it's available as _Command Prompt_ under -_Accessories_. - -__NOTE__: For Windows-only platforms, you can still do your -development on Mac hardware by running Windows in a virtual machine -environment or in dual-boot mode. For available options, see the -[Windows Phone 8 Platform Guide](../platforms/wp8/index.html) or the [Windows Platform Guide](../platforms/win8/index.html). - -The more likely it is that you run the CLI from different machines, -the more it makes sense to maintain a remote source code repository, -whose assets you pull down to local working directories. - -## Installing the Cordova CLI - -The Cordova command-line tool is distributed as an npm package in a -ready-to-use format. It is not necessary to compile it from source. - -To install the `cordova` command-line tool, follow these steps: - -1. Download and install [Node.js](http://nodejs.org/). Following - installation, you should be able to invoke `node` and `npm` on your - command line. If desired, you may optionally use a tool such as `nvm` - or `nave` to manage your Node.js installation. - -1. Download and install a [git client](http://git-scm.com/), if you don't - already have one. Following installation, you should be able to invoke `git` - on your command line. Even though you won't be using `git` manually, - the CLI does use it behind-the-scenes to download some assets when - creating a new project. - -1. Install the `cordova` module using `npm` utility of Node.js. The `cordova` - module will automatically be downloaded by the `npm` utility. - - * on OS X and Linux: - - $ sudo npm install -g cordova - - On OS X and Linux, prefixing the `npm` command with - `sudo` may be necessary to install this development utility in - otherwise restricted directories such as - `/usr/local/share`. If you are using the optional - nvm/nave tool or have write access to the install directory, - you may be able to omit the `sudo` prefix. There are - [more tips](http://justjs.com/posts/npm-link-developing-your-own-npm-modules-without-tears) - available on using `npm` without `sudo`, if you desire to do that. - - * on Windows: - - C:\>npm install -g cordova - - The `-g` flag above tells `npm` to install `cordova` globally. Otherwise - it will be installed in the `node_modules` subdirectory of the current - working directory. - - You may need to add the `npm` directory to your `PATH` in order to invoke - globally installed `npm` modules. On Windows, `npm` can usually be found at - `C:\Users\username\AppData\Roaming\npm`. On OS X and Linux it can usually - be found at `/usr/local/share/npm`. - - The installation log may produce errors for any uninstalled - platform SDKs. - - Following installation, you should be able to run - `cordova` on the command line with no arguments and it should - print help text. - -## Create the App - -Go to the directory where you maintain your source code, and run a -command such as the following: - - $ cordova create hello com.example.hello HelloWorld - -It may take some time for the command to complete, so be patient. Running -the command with the ` -d` option displays information about its progress. - -The first argument _hello_ specifies a directory to be generated -for your project. This directory should not already exist, Cordova will -create it for you. Its `www` subdirectory houses your application's -home page, along with various resources under `css`, `js`, and `img`, -which follow common web development file-naming conventions. These assets -will be stored on the device's local filesystem, not served remotely. The -`config.xml` file contains important metadata needed to generate and -distribute the application. - -The second argument `com.example.hello` -provides your project with a reverse domain-style identifier. This argument -is optional, but only if you also omit the third argument, since the arguments -are positional. You can edit -this value later in the `config.xml` file, but do be aware that there may -be code generated outside of `config.xml` using this value, such as Java -package names. The default value is `io.cordova.hellocordova`, but it is -recommended that you select an appropriate value. - -The third argument `HelloWorld` provides the application's display title. -This argument is optional. You can edit this value later in the `config.xml` -file, but do be aware that there may be code generated outside of `config.xml` -using this value, such as Java class names. The default value is `HelloCordova`, -but it is recommended that you select an appropriate value. - -## Add Platforms - -All subsequent commands need to be run within the project's directory, -or any subdirectories within its scope: - - $ cd hello - -Before you can build the project, you need to specify a set of target -platforms. Your ability to run these commands depends on whether your -machine supports each SDK, and whether you have already installed each -SDK. Run any of these from a Mac: - - $ cordova platform add ios - $ cordova platform add amazon-fireos - $ cordova platform add android - $ cordova platform add blackberry10 - $ cordova platform add firefoxos - -Run any of these from a Windows machine, where _wp_ refers to -different versions of the Windows Phone operating system: - - $ cordova platform add wp8 - $ cordova platform add windows - $ cordova platform add amazon-fireos - $ cordova platform add android - $ cordova platform add blackberry10 - $ cordova platform add firefoxos - -Run this to check your current set of platforms: - - $ cordova platforms ls - -(Note the `platform` and `platforms` commands are synonymous.) - -Run either of the following synonymous commands to remove a platform: - - $ cordova platform remove blackberry10 - $ cordova platform rm amazon-fireos - $ cordova platform rm android - -Running commands to add or remove platforms affects the contents of -the project's _platforms_ directory, where each specified platform -appears as a subdirectory. The _www_ source directory is reproduced -within each platform's subdirectory, appearing for example in -`platforms/ios/www` or `platforms/android/assets/www`. Because the CLI -constantly copies over files from the source _www_ folder, you should only -edit these files and not the ones located under the _platforms_ subdirectories. -If you use version control software, you should add this source _www_ folder, -along with the _merges_ folder, to your version control system. (More information -about the _merges_ folder can be found in the Customize Each Platform section below.) - - -__WARNING__: When using the CLI to build your application, you should -_not_ edit any files in the `/platforms/` directory unless you know -what you are doing, or if documentation specifies otherwise. The files -in this directory are routinely overwritten when preparing -applications for building, or when plugins are reinstalled. - - -If you wish at this point, you can use an SDK such as Eclipse or Xcode -to open the project you created. You will need to open the derivative set of assets -from the `/platforms/` directory to develop with an SDK. This is because -the SDK specific metadata files are stored within the appropriate `/platform/` subdirectory. -(See the [Platform Guides](../platforms/index.html) for information on how to develop applications within each IDE.) -Use this approach if you simply want to initialize a project using the CLI and -then switch to an SDK for native work. - -Read on if you wish to use the cross-platform workflow approach (the CLI) for the entire -development cycle. - -## Build the App - -By default, the `cordova create` script generates a skeletal web-based -application whose home page is the project's `www/index.html` file. -Edit this application however you want, but any initialization should -be specified as part of the `[deviceready](../../cordova/events/events.deviceready.html)` event handler, referenced by -default from `www/js/index.js`. - -Run the following command to iteratively build the project: - - $ cordova build - -This generates platform-specific code within the project's `platforms` -subdirectory. You can optionally limit the scope of each build to -specific platforms: - - $ cordova build ios - -The `cordova build` command is a shorthand for the following, which in -this example is also targeted to a single platform: - - $ cordova prepare ios - $ cordova compile ios - -In this case, once you run `prepare`, you can use Apple's Xcode SDK as -an alternative to modify and compile the platform-specific code that -Cordova generates within `platforms/ios`. You can use the same -approach with other platforms' SDKs. - -## Test the App on an Emulator or Device - -SDKs for mobile platforms often come bundled with emulators that -execute a device image, so that you can launch the app from the home -screen and see how it interacts with many platform features. Run a -command such as the following to rebuild the app and view it within a -specific platform's emulator: - - $ cordova emulate android - -Some mobile platforms emulate a particular device by default, such as -the iPhone for iOS projects. For other platforms, you may need to -first associate a device with an emulator. - -__NOTE__: Emulator support is currently not available for Amazon Fire OS. - -(See the [Platform Guides](../platforms/index.html) for details.) -For example, you may first run the `android` command to launch the -Android SDK, then run a particular device image, which launches it -according to its default behavior: - - - -Following up with the `cordova emulate` command refreshes the emulator -image to display the latest application, which is now available for -launch from the home screen: - - - -Alternately, you can plug the handset into your computer and test the -app directly: - - $ cordova run android - -Before running this command, you need to set up the device for -testing, following procedures that vary for each platform. In -Android and Amazon Fire OS devices, you would have to enable a __USB debugging__ option on -the device, and perhaps add a USB driver depending on your development -environmnent. -See [Platform Guides](../platforms/index.html) for details on each platform's requirements. - -## Add Plugin Features - -When you build and view a new project, the default application that -appears doesn't do very much. You can modify the app in many ways to -take advantage of standard web technologies, but for the app to -communicate closely with various device-level features, you need to -add plugins that provide access to core Cordova APIs. - -A _plugin_ is a bit of add-on code that provides an interface to -native components. You can design your own plugin interface, for -example when designing a hybrid app that mixes a Cordova WebView with -native components. (See [Embedding WebViews](../hybrid/webviews/index.html) and [Plugin Development -Guide](guide_hybrid_plugins_index.md.html#Plugin%20Development%20Guide) for details.) More commonly, you would add a plugin to enable -one of Cordova's basic device-level features -detailed in the API Reference. - -As of version 3.0, when you create a Cordova project it does not have any -plugins present. This is the new default behavior. Any plugins you desire, -even the core plugins, must be explicitly added. - -A list of these plugins, including -additional third-party plugins provided by the community, can be found -in the registry at -[plugins.cordova.io](http://plugins.cordova.io/). You can use -the CLI to search for plugins from this registry. For example, -searching for `bar` and `code` produces a single result that matches -both terms as case-insensitive substrings: - - $ cordova plugin search bar code - - com.phonegap.plugins.barcodescanner - Scans Barcodes - -Searching for only the `bar` term yields and additional result: - - cordova-plugin-statusbar - Cordova StatusBar Plugin - -The `cordova plugin add` command requires you to specify the -repository for the plugin code. Here are examples of how you might -use the CLI to add features to the app: - -* Basic device information (Device API): - - $ cordova plugin add cordova-plugin-device - -* Network Connection and Battery [Events](../../cordova/events/events.html): - - $ cordova plugin add cordova-plugin-network-information - $ cordova plugin add cordova-plugin-battery-status - -* Accelerometer, Compass, and Geolocation: - - $ cordova plugin add cordova-plugin-device-motion - $ cordova plugin add cordova-plugin-device-orientation - $ cordova plugin add cordova-plugin-geolocation - -* Camera, Media playback and Capture: - - $ cordova plugin add cordova-plugin-camera - $ cordova plugin add cordova-plugin-media-capture - $ cordova plugin add cordova-plugin-media - -* Access files on device or network (File API): - - $ cordova plugin add cordova-plugin-file - $ cordova plugin add cordova-plugin-file-transfer - -* Notification via dialog box or vibration: - - $ cordova plugin add cordova-plugin-dialogs - $ cordova plugin add cordova-plugin-vibration - -* Contacts: - - $ cordova plugin add cordova-plugin-contacts - -* Globalization: - - $ cordova plugin add cordova-plugin-globalization - -* Splashscreen: - - $ cordova plugin add cordova-plugin-splashscreen - -* Open new browser windows (InAppBrowser): - - $ cordova plugin add cordova-plugin-inappbrowser - -* Debug console: - - $ cordova plugin add cordova-plugin-console - -__NOTE__: The CLI adds plugin code as appropriate for each platform. -If you want to develop with lower-level shell tools or platform SDKs -as discussed in the [Overview](../overview/index.html), you need to run the Plugman utility to -add plugins separately for each platform. (For more information, see -[Using Plugman to Manage Plugins](../../plugin_ref/plugman.html).) - -Use `plugin ls` (or `plugin list`, or `plugin` by itself) to view -currently installed plugins. Each displays by its identifier: - - $ cordova plugin ls # or 'plugin list' - [ 'cordova-plugin-console' ] - -To remove a plugin, refer to it by the same identifier that appears in -the listing. For example, here is how you would remove support for a -debug console from a release version: - - $ cordova plugin rm cordova-plugin-console - $ cordova plugin remove cordova-plugin-console # same - -You can batch-remove or add plugins by specifying more than one -argument for each command: - - $ cordova plugin add cordova-plugin-console cordova-plugin-device - -## Advanced Plugin Options - -When adding a plugin, several options allow you to specify from where -to fetch the plugin. The examples above use a well-known -`registry.cordova.io` registry, and the plugin is specified by the -`id`: - - $ cordova plugin add cordova-plugin-console - -The `id` may also include the plugin's version number, appended after -an `@` character. The `latest` version is an alias for the most recent -version. For example: - - $ cordova plugin add cordova-plugin-console@latest - $ cordova plugin add cordova-plugin-console@0.2.1 - -If the plugin is not registered at `registry.cordova.io` but is located in -another git repository, you can specify an alternate URL: - - $ cordova plugin add https://github.com/apache/cordova-plugin-console.git - -The git example above fetches the plugin from the end of the master -branch, but an alternate git-ref such as a tag or branch can be -appended after a `#` character: - -Install from a tag: - - $ cordova plugin add https://github.com/apache/cordova-plugin-console.git#r0.2.0 - -or a branch: - - $ cordova plugin add https://github.com/apache/cordova-plugin-console.git#CB-8438cordova-plugin-console - -or git-ref could also be a particular commit: - - $ cordova plugin add https://github.com/apache/cordova-plugin-console.git#f055daec45575bf08538f885e09c85a0eba363ff - -If the plugin (and its `plugin.xml` file) is in a subdirectory within -the git repo, you can specify it with a `:` character. Note that the -`#` character is still needed: - - $ cordova plugin add https://github.com/someone/aplugin.git#:/my/sub/dir - -You can also combine both the git-ref and the subdirectory: - - $ cordova plugin add https://github.com/someone/aplugin.git#r0.0.1:/my/sub/dir - -Alternately, specify a local path to the plugin directory that -contains the `plugin.xml` file: - - $ cordova plugin add ../my_plugin_dir - -## Using _merges_ to Customize Each Platform - -While Cordova allows you to easily deploy an app for many different -platforms, sometimes you need to add customizations. In that case, -you don't want to modify the source files in various `www` directories -within the top-level `platforms` directory, because they're regularly -replaced with the top-level `www` directory's cross-platform source. - -Instead, the top-level `merges` directory offers a place to specify -assets to deploy on specific platforms. Each platform-specific -subdirectory within `merges` mirrors the directory structure of the -`www` source tree, allowing you to override or add files as needed. -For example, here is how you might uses `merges` to boost the default -font size for Android and Amazon Fire OS devices: - -* Edit the `www/index.html` file, adding a link to an additional CSS - file, `overrides.css` in this case: - - <link rel="stylesheet" type="text/css" href="css/overrides.css" /> - -* Optionally create an empty `www/css/overrides.css` file, which would - apply for all non-Android builds, preventing a missing-file error. - -* Create a `css` subdirectory within `merges/android`, then add a - corresponding `overrides.css` file. Specify CSS that overrides the - 12-point default font size specified within `www/css/index.css`, for - example: - - body { font-size:14px; } - -When you rebuild the project, the Android version features the custom -font size, while others remain unchanged. - -You can also use `merges` to add files not present in the original -`www` directory. For example, an app can incorporate a _back button_ -graphic into the iOS interface, stored in -`merges/ios/img/back_button.png`, while the Android version can -instead capture `[backbutton](../../cordova/events/events.backbutton.html)` events from the corresponding hardware -button. - -## Help Commands - -Cordova features a couple of global commands, which may help you if -you get stuck or experience a problem. The `help` command displays -all available Cordova commands and their syntax: - - $ cordova help - $ cordova # same - -Additionally, you can get more detailed help on a specific command. -For example: - - $ cordova run --help - -The `info` command produces a listing of potentially useful details, -such as currently installed platforms and plugins, SDK versions for -each platform, and versions of the CLI and `node.js`: - - $ cordova info - -It both presents the information to screen and captures the output in -a local `info.txt` file. - -__NOTE__: Currently, only details on iOS and Android platforms are -available. - -## Updating Cordova and Your Project - -After installing the `cordova` utility, you can always update it to -the latest version by running the following command: - - $ sudo npm update -g cordova - -Use this syntax to install a specific version: - - $ sudo npm install -g cordova@3.1.0-0.2.0 - -Run `cordova -v` to see which version is currently running. Run the `npm -info` command for a longer listing that includes the current version -along with other available version numbers: - - $ npm info cordova - -Cordova 3.0 is the first version to support the command-line interface -described in this section. If you are updating from a version prior to -3.0, you need to create a new project as described above, then copy -the older application's assets into the top-level `www` directory. -Where applicable, further details about upgrading to 3.0 are available -in the [Platform Guides](../platforms/index.html). Once you upgrade to the `cordova` -command-line interface and use `npm update` to stay current, the more -time-consuming procedures described there are no longer relevant. - -Cordova 3.0+ may still require various changes to -project-level directory structures and other dependencies. After you -run the `npm` command above to update Cordova itself, you may need to -ensure your project's resources conform to the latest version's -requirements. Run a command such as the following for each platform -you're building: - - $ cordova platform update android - $ cordova platform update ios - ...etc. -
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/edge/guide/hybrid/plugins/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/edge/guide/hybrid/plugins/index.md b/www/docs/en/edge/guide/hybrid/plugins/index.md deleted file mode 100644 index 1a21d53..0000000 --- a/www/docs/en/edge/guide/hybrid/plugins/index.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -license: > - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - -title: Plugin Development Guide ---- - -# Plugin Development Guide - -A _plugin_ is a package of injected code that allows the Cordova webview within -which the app renders to communicate with the native platform on -which it runs. Plugins provide access to device and platform -functionality that is ordinarily unavailable to web-based apps. All -the main Cordova API features are implemented as plugins, and many -others are available that enable features such as bar code scanners, -NFC communication, or to tailor calendar interfaces. There is a -[registry](http://plugins.cordova.io) of available plugins. - -Plugins comprise a single JavaScript interface along with -corresponding native code libraries for each supported platform. In essence -this hides the various native code implementations behind a common -JavaScript interface. - -This section steps through a simple _echo_ plugin that passes a string from -JavaScript to the native platform and back, one that you can use as a -model to build far more complex features. This section discusses the -basic plugin structure and the outward-facing JavaScript interface. -For each corresponding native interface, see the list at the end of -this section. - -In addition to these instructions, when preparing to write a plugin it -is best to look over -[existing plugins](http://cordova.apache.org/#contribute) -for guidance. - -## Building a Plugin - -Application developers use the CLI's `plugin add` command (discussed -in The Command-Line Interface) to apply a plugin to a project. The -argument to that command is the URL for a _git_ repository containing -the plugin code. This example implements Cordova's Device API: - - $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git - -The plugin repository must feature a top-level `plugin.xml` manifest -file. There are many ways to configure this file, details for which -are available in the [Plugin Specification](../../../plugin_ref/spec.html). This abbreviated version of -the `Device` plugin provides a simple example to use as a model: - - <?xml version="1.0" encoding="UTF-8"?> - <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"; - id="cordova-plugin-device" version="0.2.3"> - <name>Device</name> - <description>Cordova Device Plugin</description> - <license>Apache 2.0</license> - <keywords>cordova,device</keywords> - <js-module src="www/device.js" name="device"> - <clobbers target="device" /> - </js-module> - <platform name="ios"> - <config-file target="config.xml" parent="/*"> - <feature name="Device"> - <param name="ios-package" value="CDVDevice"/> - </feature> - </config-file> - <header-file src="src/ios/CDVDevice.h" /> - <source-file src="src/ios/CDVDevice.m" /> - </platform> - </plugin> - -The top-level `plugin` tag's `id` attribute uses the same -reverse-domain format to identify the plugin package as the apps to -they're added. The `js-module` tag specifies the path to the common -JavaScript interface. The `platform` tag specifies a corresponding -set of native code, for the `ios` platform in this case. The -`config-file` tag encapsulates a `feature` tag that is injected into -the platform-specific `config.xml` file to make the platform aware of -the additional code library. The `header-file` and `source-file` tags -specify the path to the library's component files. - -## Validating a Plugin - -You can use the `plugman` utility to check whether the plugin installs -correctly for each platform. Install `plugman` with the following -[node](http://nodejs.org/) command: - - $ npm install -g plugman - -You need an valid app source directory, such as the top-level `www` -directory included in a default CLI-generated project as described in -[The Command-Line Interface](../../cli/index.html). Make sure the app's `index.html` home -page reference the name of the plugin's JavaScript interface, as if it -were in the same source directory: - - <script src="myplugin.js"></script> - -Then run a command such as the following to test whether iOS -dependencies load properly: - - $ plugman install --platform ios --project /path/to/my/project/www --plugin /path/to/my/plugin - -For details on `plugman` options, see [Using Plugman to Manage Plugins](../../../plugin_ref/plugman.html). -For information on how to actually _debug_ plugins, see each -platform's native interface listed at the bottom of this page. - -## The JavaScript Interface - -The JavaScript provides the front-facing interface, making it perhaps -the most important part of the plugin. You can structure your -plugin's JavaScript however you like, but you need to call -`cordova.exec` to communicate with the native platform, using the -following syntax: - - cordova.exec(function(winParam) {}, - function(error) {}, - "service", - "action", - ["firstArgument", "secondArgument", 42, false]); - -Here is how each parameter works: - -- `function(winParam) {}`: A success callback function. Assuming your - `exec` call completes successfully, this function executes along - with any parameters you pass to it. - -- `function(error) {}`: An error callback function. If the operation - does not complete successfully, this function executes with an - optional error parameter. - -- `"service"`: The service name to call on the native side. This - corresponds to a native class, for which more information is - available in the native guides listed below. - -- `"action"`: The action name to call on the native side. This - generally corresponds to the native class method. See the native - guides listed below. - -- `[/* arguments */]`: An array of arguments to pass into the native - environment. - -## Sample JavaScript - -This example shows one way to implement the plugin's JavaScript -interface: - - window.echo = function(str, callback) { - cordova.exec(callback, function(err) { - callback('Nothing to echo.'); - }, "Echo", "echo", [str]); - }; - -In this example, the plugin attaches itself to the `window` object as -the `echo` function, which plugin users would call as follows: - - window.echo("echome", function(echoValue) { - alert(echoValue == "echome"); // should alert true. - }); - -Look at the last three arguments to the `cordova.exec` function. The -first calls the `Echo` _service_, a class name. The second requests -the `echo` _action_, a method within that class. The third is an array -of arguments containing the echo string, which is the `window.echo` -function's the first parameter. - -The success callback passed into `exec` is simply a reference to the -callback function `window.echo` takes. If the native platform fires -the error callback, it simply calls the success callback and passes it -a default string. - -## Native Interfaces - -Once you define JavaScript for your plugin, you need to complement it -with at least one native implementation. Details for each platform are -listed below, and each builds on the simple Echo Plugin example above: - -- [Amazon Fire OS Plugins](../../platforms/amazonfireos/plugin.html) -- [Android Plugins](../../platforms/android/plugin.html) -- [iOS Plugins](../../platforms/ios/plugin.html) -- [BlackBerry 10 Plugins](../../platforms/blackberry10/plugin.html) -- [Windows Phone 8 Plugins](../../platforms/wp8/plugin.html) -- [Windows Plugins](../../platforms/win8/plugin.html) - -## Publishing Plugins - -Once you develop your plugin, you may want to publish and share it -with the community. You can publish your plugin to any `npmjs`-based -registry, but the recommended one is the [NPM registry](https://www.npmjs.com). -Please read our [publishing plugins to npm guide](http://plugins.cordova.io/npm/developers.html). - - -__NOTE__: [Cordova plugin registry](https://plugins.cordova.io) is -moving to a read-only state. `publish`/ -`unpublish` commands have been removed from `plugman`, so you'll need to -use corresponding `npm` commands. - -Other developers can install your plugin automatically using either `plugman` - or the Cordova CLI. (For details on each development path, see - [Using Plugman to Manage Plugins](../../../plugin_ref/plugman.html) and [The Command-Line Interface](../../cli/index.html).) - -To publish a plugin to NPM registry you need to follow steps below: - - * create `package.json` file for your plugin: - - $ plugman createpackagejson /path/to/your/plugin - - * publish it: - - $ npm adduser # that is if you don't have an account yet - $ npm publish /path/to/your/plugin - -That is it! - -Running `plugman --help` lists other available registry-based -commands. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/edge/guide/hybrid/webviews/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/edge/guide/hybrid/webviews/index.md b/www/docs/en/edge/guide/hybrid/webviews/index.md deleted file mode 100644 index 973950d..0000000 --- a/www/docs/en/edge/guide/hybrid/webviews/index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -license: > - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - -title: Embedding WebViews ---- - -# Embedding WebViews - -Cordova applications are ordinarily implemented as a browser-based -_WebView_ within the native mobile platform. This section shows how, -for supporting platforms, to create your own WebView components that -make full use of Cordova APIs. You can then deploy these Cordova -application components along with native components in a hybrid -application. - -To deploy a WebView, you need to be familiar with each native -programming environment. The following provides instructions for -supported platforms: - -- [Amazon Fire OS WebViews](../../platforms/amazonfireos/webview.html) -- [Android WebViews](../../platforms/android/webview.html) -- [iOS WebViews](../../platforms/ios/webview.html) -- [Windows Phone 8.0 WebViews](../../platforms/wp8/webview.html) \ No newline at end of file http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/edge/guide/next/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/edge/guide/next/index.md b/www/docs/en/edge/guide/next/index.md deleted file mode 100644 index 2bdf90d..0000000 --- a/www/docs/en/edge/guide/next/index.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -license: > - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - -title: Next Steps ---- - -# Next Steps - -For developers who have an understanding of how to use the Cordova CLI and make use of plugins, there are a few things you may want to consider researching next to build better, more performant Cordova applications. The following document offers advice on various topics relating to best practices, testing, upgrades, and other topics, but is not meant to be prescriptive. Consider this your launching point for your growth as a Cordova developer. Also, if you see something that can be improved, please [contribute](http://cordova.apache.org/#contribute)! - -This guide contains the following topics: - -* Best Practices -* Handling Upgrades -* Testing Cordova apps -* Debugging Cordova apps -* User Interface -* Special Considerations -* Keeping Up -* Getting Help - -# Best Practices Cordova app development - -## 1) SPA Is Your Friend - -First and foremost - your Cordova applications should adopt the SPA (Single Page Application) design. Loosely defined, a SPA is a client-side application that is run from one request of a web page. The user loads an initial set of resources (HTML, CSS, and JavaScript) and further updates (showing a new view, loading data) is done via AJAX. SPAs are commonly used for more complex client-side applications. GMail is a great example of this. After you load GMail, mail views, editing, and organization are all done by updating the DOM instead of actually leaving the current page to load a completely new one. - -Using a SPA can help you organize your application in a more efficient manner, but it also has specific benefits for Cordova applications. A Cordova application must wait for the [deviceready](../../cordova/events/events.deviceready.html) event to fire before any plugins may be used. If you do not use a SPA, and your user clicks to go from one page to another, you will have to wait for [deviceready](../../cordova/events/events.deviceready.html) to fire again before you make use of a plugin. This is easy to forget as your application gets larger. - -Even if you choose not to use Cordova, creating a mobile application without using a single page architecture will have serious performance implications. This is because navigating between pages will require scripts, assets, etc., to be reloaded. Even if these assets are cached, there will still be performance issues. - -Examples of SPA libraries you can use in your Cordova applications are: - -* [AngularJS](http://angularjs.org) -* [EmberJS](http://emberjs.com) -* [Backbone](http://backbonejs.org) -* [Kendo UI](http://www.telerik.com/kendo-ui) -* [Monaca](http://monaca.mobi/en/) -* [ReactJS](http://facebook.github.io/react/) -* [Sencha Touch](http://www.sencha.com/products/touch/) -* [jQuery Mobile](http://jquerymobile.com) - -And many, many, more. - -## 2) Performance Considerations - -One of the biggest mistakes a new Cordova developer can make is to assume that the performance they get on a desktop machine is the same they will get on a mobile device. While our mobile devices have gotten more powerful every year, they still lack the power and performance of a desktop. Mobile devices typically have much less RAM and a GPU that is a far cry from their desktop (or even laptop) brethren. A full list of tips here would be too much, but here are a few things to keep in mind (with a list of longer resources at the end for further research). - -**Click versus Touch** - The biggest and simplest mistake you can make is to use click events. While these "work" just fine on mobile, most devices impose a 300ms delay on them in order to distinguish between a touch and a touch "hold" event. Using `touchstart`, or `touchend`, will result in a dramatic improvement - 300ms doesn't sound like much, but it can result in jerky UI updates and behavior. You should also consider the fact that âtouchâ events are not supported on non-webkit browsers, see [CanIUse](http://caniuse.com/#search=touch). In order to deal with these limitations, you can checkout various libraries like HandJS and Fastouch. - -**CSS Transitions versus DOM Manipulation** - Using hardware accelerated CSS transitions will be dramatically better than using JavaScript to create animations. See the list of resources at the end of this section for examples. - -**Networks Suck** - Ok, networks don't always suck, but the latency of mobile networks, even good mobile networks, is far worse than you probably think. A desktop app that slurps down 500 rows of JSON data, every 30 seconds, will be both slower on a mobile device as well as a battery hog. Keep in mind that Cordova apps have multiple ways to persist data in the app (LocalStorage and the file system for example). Cache that data locally and be cognizant of the amount of data you are sending back and forth. This is an especially important consideration when your application is connected over a cellular network. - -**Additional Performance Articles and Resources** - -* ["You half assed it"](http://sintaxi.com/you-half-assed-it) -* ["Top Ten Performance Tips for PhoneGap and Hybrid Apps"](http://coenraets.org/blog/2013/10/top-10-performance-techniques-for-phonegap-and-hybrid-apps-slides-available/) -* ["Fast Apps and Sites with JavaScript"][1] - - [1]: https://channel9.msdn.com/Events/Build/2013/4-313 - -## 3) Recognize and Handle Offline Status - -See the previous tip about networks. Not only can you be on a slow network, it is entirely possible for your application to be completely offline. Your application should handle this in an intelligent manner. If your application does not, people will think your application is broken. Given how easy it is to handle (Cordova supports listening for both an offline and online event), there is absolutely no reason for your application to not respond well when run offline. Be sure to test (see the Testing section below) your application and be sure to test how your application handles when you start in one state and then switch to another. - -Note that the online and offline events, as well as the Network Connection API is not perfect. You may need to rely on using an XHR request to see if the device is truly offline or online. At the end of the day, be sure add some form of support for network issues - in fact, the Apple store (and probably other stores) will reject apps that donât properly handle offline/online states. For more discussion on this topic, see -["Is This Thing On?"](http://blogs.telerik.com/appbuilder/posts/13-04-23/is-this-thing-on-%28part-1%29) - -# Handling Upgrades - -## Upgrading Cordova Projects - -If your existing project was created using Cordova 3.x, you can upgrade the project by issuing the following: - - cordova platform update platform-name ios, android, etc. - -If your existing project was created under a version prior to Cordova 3.x, it would probably be best to create a new Cordova 3.x project, and then copy your existing projectâs code and assets to the new project. Typical steps: - -* Create a new Cordova 3.x project (cordova create ...) -* Copy the www folder from your old project to the new project -* Copy any configuration settings from the old project to the new project -* Add any plugins used in the old project to the new project -* Build your project -* Test, test, test! - -Regardless of the project's prior version, it is absolutely critical that you read up on what was changed in the updated version, as the update may break your code. The best place to find this information will be in the release notes published both in the repositories and on the Cordova blog. You will want to test your app thoroughly in order to verify that it is working correctly after you perform the update. - -Note: some plugins may not be compatible with the new version of Cordova. If a plugin is not compatible, you may be able to find a replacement plugin that does what you need, or you may need to delay upgrading your project. Alternatively, alter the plugin so that it does work under the new version and contribute back to the community. - -## Plugin Upgrades -As of Cordova 3.4, there is no mechanism for upgrading changed plugins using a single command. Instead, remove the plugin and add it back to your project, and the new version will be installed: - - cordova plugin rm com.some.plugin - cordova plugin add com.some.plugin - -Be sure to check the updated plugin's documentation, as you may need to adjust your code to work with the new version. Also, double check that the new version of the plugin works with your projectâs version of Cordova. - -Always test your apps to ensure that installing the new plugin has not broken something that you did not anticipate. - -If your project has a lot of plugins that you need updated, it might save time to create a shell or batch script that removes and adds the plugins with one command. - -# Testing Cordova apps - -Testing your applications is super important. The Cordova team uses Jasmine but any web friendly unit testing solution will do. - -## Testing on a simulator vs. on a real device - -Itâs not uncommon to use desktop browsers and device simulators/emulators when developing a Cordova application. However, it is incredibly important that you test your app on as many physical devices as you possibly can: - -* Simulators are just that: simulators. For example, your app may work in the iOS simulator without a problem, but it may fail on a real device (especially in certain circumstances, such as a low memory state). Or, your app may actually fail on the simulator while it works just fine on a real device. -* Emulators are just that: emulators. They do not represent how well your app will run on a physical device. For example, some emulators may render your app with a garbled display, while a real device has no problem. (If you do encounter this problem, disable the host GPU in the emulator.) -* Simulators are generally faster than your physical device. Emulators, on the other hand, are generally slower. Do not judge the performance of your app by how it performs in a simulator or an emulator. Do judge the performance of your app by how it runs on a spectrum of real devices. -* It's impossible to get a good feel for how your app responds to your touch by using a simulator or an emulator. Instead, running the app on a real device can point out problems with the sizes of user interface elements, responsiveness, etc. -* Although it would be nice to be able to test only on one device per platform, it is best to test on many devices sporting many different OS versions. For example, what works on your particular Android smartphone may fail on another Android device. What works on an iOS 7 device may fail on an iOS 6 device. - -It is, of course, impossible to test on every possible device on the market. For this reason, itâs wise to recruit many testers who have different devices. Although they wonât catch every problem, chances are good that they will discover quirks and issues that you would never find alone. - -Tip: It is possible on Android Nexus devices to easily flash different versions of Android onto the device. This simple process will allow you to easily test your application on different levels of Android with a single device, without voiding your warranty or requiring you to âjailbreakâ or ârootâ your device. The Google Android factory images and instructions are located at: https://developers.google.com/android/nexus/images#instructions - -# Debugging Cordova apps - -Debugging Cordova requires some setup. Unlike a desktop application, you can't simply open dev tools on your mobile device and start debugging, luckily there are some great alternatives. - -## iOS Debugging - -### Xcode -With Xcode you can debug the iOS native side of your Cordova application. Make sure the Debug Area is showing (View -> Debug Area). Once your app is running on the device (or simulator), you can view log output in the debug area. This is where any errors or warnings will print. You can also set breakpoints within the source files. This will allow you to step through the code one line at a time and view the state of the variables at that time. The state of the variables is shown in the debug area when a breakpoint is hit. Once your app is up and running on the device, you can bring up Safari's web inspector (as described below) to debug the webview and js side of your application. For more details and help, see the Xcode guide: [Xcode Debugging Guide](https://developer.apple.com/library/mac/documentation/ToolsLanguages/Conceptual/Xcode_Overview/DebugYourApp/DebugYourApp.html#//apple_ref/doc/uid/TP40010215-CH18-SW1) - -### Safari Remote Debugging with Web Inspector -With Safari's web inspector you can debug the webview and js code in your Cordova application. This works only on OSX and only with iOS 6 (and higher). It uses Safari to connect to your device (or the simulator) and will connect the browser's dev tools to the Cordova application. You get what you expect from dev tools - DOM inspection/manipulation, a JavaScript debugger, network inspection, the console, and more. Like Xcode, with Safari's web inspector you can set breakpoints in the JavaScript code and view the state of the variables at that time. You can view any errors, warnings or messages that are printed to the console. You can also run JavaScript commands directly from the console as your app is running. For more details on how to set it up and what you can do, see this excellent blog post: [http://moduscreate.com/enable-remote-web-inspector-in-ios-6/](http://moduscreate.com/enable-remote-web-inspector-in-ios-6/) and this guide: [Safari Web Inspector Guide](https://developer.a pple.com/library/safari/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/Introduction/Introduction.html) - -## Chrome Remote Debugging -Virtually the same as the Safari version, this works with Android only but can be used from any desktop operating system. It requires a minimum of Android 4.4 (KitKat), minimum API level of 19, and Chrome 30+ (on the desktop). Once connected, you get the same Chrome Dev Tools experience for your mobile applications as you do with your desktop applications. Even better, the Chrome Dev Tools have a mirror option that shows your app running on the mobile device. This is more than just a view - you can scroll and click from dev tools and it updates on the mobile device. More details on Chrome Remote Debugging may be found here: [https://developers.google.com/chrome/mobile/docs/debugging](https://developers.google.com/chrome/mobile/docs/debugging) - -It is possible to use Chrome Dev Tools to inspect iOS apps, through a WebKit proxy: [https://github.com/google/ios-webkit-debug-proxy/](https://github.com/google/ios-webkit-debug-proxy/) - -## Ripple -Ripple is a desktop based emulator for Cordova projects. Essentially it lets you run a Cordova application in your desktop application and fake various Cordova features. For example, it lets you simulate the accelerometer to test shake events. It fakes the camera API by letting you select a picture from your hard drive. Ripple lets you focus more on your custom code rather than worrying about Cordova plugins. You can find out more about Ripple here: [http://ripple.incubator.apache.org/](http://ripple.incubator.apache.org/) - -## Weinre -Weinre creates a local server that can host a remote debug client for your Cordova applications. After you've installed and started it up, you copy a line of code into your Cordova application and then restart it. You can then open a dev tool panel on your desktop to work with the application. Weinre is not quite as fancy as Chrome and Safari Remote debugging but has the benefit of working with a much greater range of operating systems and platforms. More information may be found here: [http://people.apache.org/~pmuellr/weinre/docs/latest/](http://people.apache.org/~pmuellr/weinre/docs/latest/) - -## Other Options - -* BlackBerry 10 supports debugging as well: [Documentation]( https://developer.blackberry.com/html5/documentation/v2_0/debugging_using_web_inspector.html) -* You can debug using Firefox App Manager as well, see [this blog post](https://hacks.mozilla.org/2014/02/building-cordova-apps-for-firefox-os/) and this -[MDN article](https://developer.mozilla.org/en-US/Apps/Tools_and_frameworks/Cordova_support_for_Firefox_OS#Testing_and_debugging). -* For more examples and explanation of the above debugging tips, see: [http://developer.telerik.com/featured/a-concise-guide-to-remote-debugging-on-ios-android-and-windows-phone/](http://developer.telerik.com/featured/a-concise-guide-to-remote-debugging-on-ios-android-and-windows-phone/) - -# User Interface - -Building a Cordova application that looks nice on mobile can be a challenge, especially for developers. Many people chose to use a UI framework to make this easier. Here is a short list of options you may want to consider. - -* [jQuery Mobile](http://jquerymobile.com) - jQuery Mobile automatically enhances your layout for mobile optimization. It also handles creating a SPA for you automatically. -* [ionic](http://ionicframework.com/) - This powerful UI framework actually has its own CLI to handle project creation. -* [Ratchet](http://goratchet.com/) - Brought to you by the people who created Bootstrap. -* [Kendo UI](http://www.telerik.com/kendo-ui) - Open source UI and application framework from Telerik. -* [Topcoat](http://topcoat.io) -* [ReactJS](http://facebook.github.io/react/) - -When building your user interface, it is important to think about all platforms that you are targeting and the differences between the userâs expectations. For example, an Android application that has an iOS-style UI will probably not go over well with users. This sometimes is even enforced by the various application stores. Because of this, it is important that you respect the conventions of each platform and therefore are familiar with the various Human Interface Guidelines: - -* [iOS](https://developer.apple.com/library/ios/documentation/userexperience/conceptual/MobileHIG/index.html) -* [Android](https://developer.android.com/designWP8) -* [Windows Phone](http://dev.windowsphone.com/en-us/design/library) - -## Additional UI Articles and Resources - -Although browser engines become more and more standards complaint, we still live in a prefixed world (-webkit and -ms.) The following article is valuable when developing UIâs in for cross browser apps: [http://blogs.windows.com/windows_phone/b/wpdev/archive/2012/11/15/adapting-your-webkit-optimized-site-for-internet-explorer-10.aspx](http://blogs.windows.com/windows_phone/b/wpdev/archive/2012/11/15/adapting-your-webkit-optimized-site-for-internet-explorer-10.aspx) - -# Special Considerations - -Although Cordova makes cross-platform development easier, it's just not possible to provide 100% isolation from the underlying native platform. So do be aware of restrictions. - -## Platform Quirks - -While reading the documentation, look for sections which outline different behaviors or requirements on multiple platforms. If present, these would be in a section titled "Android Quirks", "iOS Quirks", etc. Read through these quirks and be aware of them as you work with Cordova. - -## Loading Remote Content - -Invoking Cordova JavaScript functions from a remotely-loaded HTML page (an HTML page not stored locally on the device) is an unsupported configuration. This is because Cordova was not designed for this, and the Apache Cordova community does no testing of this configuration. While it can work in some circumstances, it is not recommended nor supported. There are challenges with the same origin policy, keeping the JavaScript and native portions of Cordova synchronized at the same version (since they are coupled via private APIs which may change), the trustworthiness of remote content calling native local functions, and potential app store rejection. - -The display of remotely-loaded HTML content in a webview should be done using Cordova's InAppBrowser. The InAppBrowser is designed so that JavaScript running there does not have access to the Cordova JavaScript APIs for the reasons listed above. Please refer to the [Security Guide](../appdev/security/index.html). - -# Keeping Up - -Here are a few ways to keep up to date with Cordova. - -* Subscribe to the [Cordova blog](http://cordova.apache.org/#news). -* Subscribe to the [developer list](http://cordova.apache.org/#mailing-list). Note - this is not a support group! Rather this is a place where development of Cordova is discussed. - -# Getting Help - -The following links are the best places to get help for Cordova: - -* StackOverflow: [http://stackoverflow.com/questions/tagged/cordova](http://stackoverflow.com/questions/tagged/cordova) -By using the Cordova tag, you can view and browse all Cordova questions. Note that StackOverflow automatically converts the "Phonegap" tag to "Cordova", so this way you will be able to access historical questions as well -* PhoneGap Google Group: [https://groups.google.com/forum/#!forum/phonegap](https://groups.google.com/forum/#!forum/phonegap) -This Google Group was the old support forum when Cordova was still called PhoneGap. While there are still a lot of Cordova users that frequently visit this group, the Cordova community has expressed an interest in focusing less on this group and instead using StackOverflow for support -* Meetup: [http://phonegap.meetup.com](http://phonegap.meetup.com) - -Consider finding a local Cordova/PhoneGap meetup group - - http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/edge/guide/overview/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/edge/guide/overview/index.md b/www/docs/en/edge/guide/overview/index.md deleted file mode 100644 index 146e358..0000000 --- a/www/docs/en/edge/guide/overview/index.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -license: > - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - -title: Overview ---- - -# Overview - -Apache Cordova is an open-source mobile development framework. It allows you -to use standard web technologies such as HTML5, CSS3, and JavaScript -for cross-platform development, avoiding each mobile platforms' native -development language. Applications execute within wrappers targeted -to each platform, and rely on standards-compliant API bindings to -access each device's sensors, data, and network status. - -Apache Cordova graduated in October 2012 as a top level project within the Apache Software Foundation (ASF). Through the ASF, future Cordova development will ensure open stewardship of the project. It will always remain free and open source under the Apache License, Version 2.0. Visit [cordova.apache.org](http://cordova.apache.org) for more information. - -Use Apache Cordova if you are: - -* a mobile developer and want to extend an application across more - than one platform, without having to re-implement it with each - platform's language and tool set. - -* a web developer and want to deploy a web app that's packaged for - distribution in various app store portals. - -* a mobile developer interested in mixing native application - components with a _WebView_ (special browser window) that can access - device-level APIs, or if you want to develop a plugin interface - between native and WebView components. - -## Basic Components - -Apache Cordova applications rely on a common `config.xml` file that provides -information about the app and specifies parameters affecting how it -works, such as whether it responds to orientation shifts. This file -adheres to the W3C's -[Packaged Web App](http://www.w3.org/TR/widgets/), -or _widget_, specification. - -The application itself is implemented as a web page, by default a local -file named _index.html_, that references whatever CSS, JavaScript, -images, media files, or other resources are necessary for it to run. -The app executes as a _WebView_ within the native application wrapper, -which you distribute to app stores. - -The Cordova-enabled WebView may provide the application with its -entire user interface. On some platforms, it can also be a component -within a larger, hybrid application that mixes the WebView with native -application components. (See [Embedding WebViews](../hybrid/webviews/index.html) for details.) - -A _plugin_ interface is available for Cordova and native components to -communicate with each other. This enables you to invoke native code -from JavaScript. Ideally, the JavaScript APIs to that native code are -consistent across multiple device platforms. As of version 3.0, plugins provide -bindings to standard device APIs. Third-party plugins provide -additional bindings to features not necessarily available on all -platforms. You can find these third-party plugins in the -[plugin registry](http://plugins.cordova.io) and use them in your -application. You can also develop your own plugins, as described in the -[Plugin Development Guide](../hybrid/plugins/index.html). Plugins may be necessary, for example, to -communicate between Cordova and custom native components. - -__NOTE__: As of version 3.0, when you create a Cordova project it does not have -any plugins present. This is the new default behavior. Any plugins you -desire, even the core plugins, must be explicitly added. - -Cordova does not provide any UI widgets or MV* frameworks. Cordova provides -only the runtime in which those can execute. If you wish to use UI widgets -and/or an MV* framework, you will need to select those and include them in -your application yourself as third-party material. - -## Development Paths - -As of version 3.0, you can use two basic workflows to create a mobile -app. While you can often use either workflow to accomplish the same -task, they each offer advantages: - -- __Cross-platform (CLI) workflow__: Use this workflow if you want your app - to run on as many different mobile operating systems as possible, - with little need for platform-specific development. This workflow - centers around the `cordova` utility, otherwise known as the Cordova - _CLI_, that was introduced with Cordova 3.0. The CLI is a high-level - tool that allows you to build projects for many platforms at once, - abstracting away much of the functionality of lower-level shell - scripts. The CLI copies a common set of web assets into - subdirectories for each mobile platform, makes any necessary - configuration changes for each, runs build scripts to generate - application binaries. The CLI also provides a common interface to - apply plugins to your app. For more details on the CLI, see The - Command-Line Interface. Unless you have a need for the platform-centered - workflow, the cross-platform workflow is recommended. - -- __Platform-centered workflow__: Use this workflow if you want to - focus on building an app for a single platform and need to be able - to modify it at a lower level. You need to use this approach, for - example, if you want your app to mix custom native components with - web-based Cordova components, as discussed in [Embedding WebViews](../hybrid/webviews/index.html). - As a rule of thumb, use this workflow if you need to modify the - project within the SDK. This workflow relies on a set of - lower-level shell scripts that are tailored for each supported - platform, and a separate Plugman utility that allows you to apply - plugins. While you can use this workflow to build cross-platform - apps, it is generally more difficult because the lack of a - higher-level tool means separate build cycles and plugin - modifications for each platform. Still, this workflow allows you - greater access to development options provided by each SDK, and is - essential for complex hybrid apps. See the various [Platform Guides](../platforms/index.html) - for details on each platform's available shell utilities. - -When first starting out, it may be easiest to use the cross-platform -workflow to create an app, as described in [The Command-Line Interface](../cli/index.html). -You then have the option to switch to a platform-centered workflow if -you need the greater control the SDK provides. Lower-level shell -utilities are available at -[cordova.apache.org](http://cordova.apache.org) in a separate -distribution than the CLI. For projects initially generated by the -CLI, these shell tools are also available in the project's various -`platforms/*/cordova` directories. - -__NOTE__: Once you switch from the CLI-based workflow to one centered -around the platform-specific SDKs and shell tools, you can't go back. -The CLI maintains a common set of cross-platform source code, which on -each build it uses to write over platform-specific source code. To -preserve any modifications you make to the platform-specific assets, -you need to switch to the platform-centered shell tools, which ignore -the cross-platform source code, and instead relies on the -platform-specific source code. - -## Installing Cordova - -The installation of Cordova will differ depending on the workflow above -you choose: - - * Cross-platform workflow: see [The Command-Line Interface](../cli/index.html). - - * Platform-centered workflow: see the [Platform Guides](../platforms/index.html). - -After installing Cordova, it is recommended that you review the [Platform Guides](../platforms/index.html) -for the mobile platforms that you will be developing for. It is also -recommended that you also review the [Privacy Guide](../appdev/privacy/index.html), [Security Guide](../appdev/security/index.html), and -[Next Steps](../next/index.html). For configuring Cordova, see [The config.xml File](../../config_ref/index.html). -For accessing native function on a device from JavaScript, refer -to the [Plugin APIs](../../cordova/plugins/pluginapis.html). And refer to the other included guides as necessary. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/edge/guide/platforms/amazonfireos/config.md ---------------------------------------------------------------------- diff --git a/www/docs/en/edge/guide/platforms/amazonfireos/config.md b/www/docs/en/edge/guide/platforms/amazonfireos/config.md deleted file mode 100644 index 8a99227..0000000 --- a/www/docs/en/edge/guide/platforms/amazonfireos/config.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -license: > - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - -title: Amazon Fire OS Configuration ---- - -# Amazon Fire OS Configuration - -The `config.xml` file controls an app's basic settings that apply -across each application and CordovaWebView instance. This section -details preferences that only apply to Amazon Fire OS builds. See [The config.xml -File](config_ref_index.md.html#The%20config.xml%20File) for information on global configuration options. - -- `KeepRunning` (boolean, defaults to `true`): Determines whether the - application stays running in the background even after a `[pause](../../../cordova/events/events.pause.html)` - event fires. Setting this to `false` does not kill the app after a - `[pause](../../../cordova/events/events.pause.html)` event, but simply halts execution of code within the cordova - webview while the app is in the background. - - <preference name="KeepRunning" value="false"/> - -- `ErrorUrl` (URL, defaults to `null`): - If set, will display the referenced page upon an error in the application - instead of a dialog with the title "Application Error". - - <preference name="ErrorUrl" value="error.html"/> - -- `LoadingDialog` (string, defaults to `null`): If set, displays a dialog with - the specified title and message, and a spinner, when loading the first - page of an application. The title and message are separated by a comma - in this value string, and that comma is removed before the dialog is - displayed. - - <preference name="LoadingDialog" value="Please wait, the app is loading"/> - -- `LoadingPageDialog` (string, defaults to `null`): The same as `LoadingDialog`, - but for loading every page after the first page in the application. - - <preference name="LoadingPageDialog" value="Please wait, the data is loading"/> - -- `LoadUrlTimeoutValue` (number, default is `20000`): When loading a - page, the amount of time to wait before throwing a timeout error. - This example specifies 10 seconds rather than 20: - - <preference name="LoadUrlTimeoutValue" value="10000"/> - -- `SplashScreen`: The name of the file minus its extension in the - `res/drawable` directory. Various assets must share this common - name in various subdirectories. - - <preference name="SplashScreen" value="splash"/> - -- `SplashScreenDelay` (number, defaults to `5000`): The amount of - time the splash screen image displays. - - <preference name="SplashScreenDelay" value="10000"/> - -- `ShowTitle` (boolean, defaults to `false`): Show the title at the top - of the screen. - - <preference name="ShowTitle" value="true"/> - -- `LogLevel` (string, defaults to `ERROR`): Sets the minimum log level - through which log messages from your application will be filtered. Valid - values are `ERROR`, `WARN`, `INFO`, `DEBUG`, and `VERBOSE`. - - <preference name="LogLevel" value="VERBOSE"/> - http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/edge/guide/platforms/amazonfireos/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/edge/guide/platforms/amazonfireos/index.md b/www/docs/en/edge/guide/platforms/amazonfireos/index.md deleted file mode 100644 index 055f249..0000000 --- a/www/docs/en/edge/guide/platforms/amazonfireos/index.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -license: > - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - -title: Amazon Fire OS Platform Guide ---- - -# Amazon Fire OS Platform Guide - -This guide shows how to set up your SDK development environment to -deploy Cordova apps for Amazon Fire OS devices, such as the Kindle Fire HDX. - -See the following for more detailed platform-specific information: - -* [Amazon Fire OS Configuration](config.html) -* [Amazon Fire OS WebViews](webview.html) -* [Amazon Fire OS Plugins](plugin.html) - -## Introduction - -By targeting the Amazon Fire OS platform, Cordova developers can create hybrid web apps that take advantage of the advanced web engine integrated into Kindle Fire devices. Amazon WebView API (AWV) is a Chromium-derived web runtime exclusive to Fire OS. A drop-in replacement for the WebView that comes with Android devices, AWV makes it possible to create better performing and more powerful hybrid web apps by providing support for a faster JavaScript engine (V8), remote debugging, and hardware optimizations for Kindle Fire devices including an accelerated 2D Canvas, and access to HTML5 features not supported by Androidâs built in WebView such as: CSS Calc, Form Validation, getUserMedia, IndexedDB, Web Workers, WebSockets and WebGL. - -For more information about the Amazon WebView API, please see the Amazon Developer Portal's [HTML5 Hybrid Apps page](https://developer.amazon.com/public/solutions/platforms/android-fireos/docs/building-and-testing-your-hybrid-app). For questions about getting started and other support issues, please see the Amazon Developer Portal [Forums - HTML5 Hybrid Apps](http://forums.developer.amazon.com/forums/category.jspa?categoryID=41). - - -## Requirements and Support - -Developing Cordova apps for Amazon Fire OS requires installation of a variety of support files, including everything needed for Android development, as well as the Amazon WebView SDK. Check the list below for the required installs: - -* [The Command-Line Interface](../../cli/index.html) -* [Android SDK](http://developer.android.com/sdk/) -* [Apache Ant](http://ant.apache.org) -* [Amazon WebView SDK](https://developer.amazon.com/public/solutions/platforms/android-fireos/docs/building-and-testing-your-hybrid-app) - -## Installation - - -### Android SDK and Apache Ant - -Install the Android SDK from -[developer.android.com/sdk](http://developer.android.com/sdk/). You -may be presented with a choice of where to install the SDK, otherwise -move the downloaded `adt-bundle` tree to wherever you store -development tools. - -You'll need to run the Android SDK Manager (`android` from a command line) at least once before starting your Cordova project. Make sure to install the most recent version of the Android SDK Tools and SDK Platform **specifically API level 19**. Please see [Setting up your Development Environment](https://developer.amazon.com/public/resources/development-tools/ide-tools/tech-docs/01-setting-up-your-development-environment) on the Amazon Developer Portal for more information about setting up your development environment for Kindle Fire OS devices. - -Install the Apache Ant build tool by [downloading an Ant binary distribution](http://ant.apache.org/bindownload.cgi), unzipping into a directory you can refer to later. See the [Ant manual](http://ant.apache.org/manual/index.html) for more info. - -For Cordova command-line tools to work, you need to include the Android SDK's -`tools`, `platform-tools` and `apache-ant/bin` directories in your PATH environment. - -#### Mac/Linux Path - -On Mac, Linux or other Unix-like platforms, you can use a text editor to create or modify the -`~/.bash_profile` file, adding a line such as the following, depending -on where the SDK and Ant are installed: - - export PATH=${PATH}:/Development/adt-bundle/sdk/platform-tools:/Development/adt-bundle/sdk/tools:/Development/apache-ant/bin - -This exposes SDK tools in newly opened terminal windows. Otherwise run -this to make them available in the current session: - - $ source ~/.bash_profile - -#### Windows Path - -To modify the PATH environment on Windows: - -* Click on the __Start__ menu in the lower-left corner of the desktop, - right-click on __Computer__, then click __Properties__. - -* Click __Advanced System Settings__ in the column on the left. - -* In the resulting dialog box, press __Environment Variables__. - -* Select the __PATH__ variable and press __Edit__. - -* Append the following to the PATH based on where you installed the - SDK and Ant, for example: - - ;C:\Development\adt-bundle\sdk\platform-tools;C:\Development\adt-bundle\sdk\tools;C:\Development\apache-ant\bin - -* Save the value and close both dialog boxes. - -* You will also need to enable Java. Open a command prompt and -type `java`, if it does not run, append the location of the Java binaries to your PATH as well. Make sure %JAVA_HOME% is pointing to installed JDK directory. You might have to add JAVA_HOME environment variable seperately. - - ;%JAVA_HOME%\bin - - -### Amazon WebView SDK - -In order to create Cordova apps using the Amazon Fire OS platform target, you'll need to download, unpack and install the Amazon WebView SDK support files. This step will only need to be done for your first Amazon Fire OS project. - -* Download the Amazon WebView SDK from the [Amazon Developer Portal](https://developer.amazon.com/public/solutions/platforms/android-fireos/docs/building-and-testing-your-hybrid-app). - -* Copy `awv_interface.jar` from the downloaded SDK to Cordova's working directory. Create commonlibs(shown below) folder if it doesn't exist: - - **Mac/Linux:** - `~/.cordova/lib/commonlibs/` - - **Windows:** - `%USERPROFILE%\.cordova\lib\commonlibs` - - -## Create New Project for Amazon Fire OS - -Use the `cordova` utility to set up a new project, as described in The -Cordova [The Command-Line Interface](../../cli/index.html). For example, in a source-code directory: - - $ cordova create hello com.example.hello "HelloWorld" - $ cd hello - $ cordova platform add amazon-fireos - $ cordova build - -***Note:*** The first time the amazon-fireos platform is installed on your system, it will download the appropriate files to the Cordova working directory, but will then fail as it is missing the AWV SDK support files (see above). Follow the instructions above to install the `awv_interface.jar`, then remove and re-add the amazon-fireos platform to your project. This step will only need to be done for first Amazon Fire OS project. - - -## Deploy to Device - -To push an app directly to the device, make sure USB debugging is enabled on your device as described on the -[Android Developer Site](http://developer.android.com/tools/device.html), -and use a mini USB cable to plug it into your system. - -You can push the app to the device from the command line: - - $ cordova run amazon-fireos - -Alternately within Eclipse, right-click the project and choose __Run -As → Android Application__. - -__Note__: Currently, testing via an emulator is not supported for Amazon WebView based apps, additionally the Amazon WebView API is only available on Fire OS devices. For more information, please see the [Amazon WebView API SDK](https://developer.amazon.com/public/solutions/platforms/android-fireos/docs/building-and-testing-your-hybrid-app) documentation. - -### Run Flags - -The run command accepts optional parameters as specified in the Cordova Command Line Interface document, Fire OS also accepts an additional `--debug` flag which will enable Chromium's Developer Tools for remote web debugging. - -To use Developer Tools, enter: - - $ cordova run --debug amazon-fireos - -This will enable the tools on the running client. You can then connect to the client by port forwarding using the Android Debug Bridge (adb) referring to the app's package name. - -For example: - - adb forward tcp:9222 localabstract:com.example.helloworld.devtools - -You can then use the DevTools via a Chromium-based browser by navigating to: `http://localhost:9222`. - -### Optional Eclipse support - -Once created, you can use the Eclipse that comes along with the Android SDK to modify the project. Beware that modifications made through Eclipse will be overwritten if you continue to use Cordova command line tools. - -* Launch the __Eclipse__ application. - -* Select the __New Project__ menu item. - -* Choose __Android Project from Existing Code__ from the resulting dialog box, and press __Next__: -  - -* Navigate to `hello`, or whichever directory you created for the project, then to the `platforms/amazon-fireos` subdirectory. - -* Eclipse will show you hello and hello-CorddovaLib - 2 projects to be added. Add both. - -* Press __Finish__. - -Once the Eclipse window opens, a red __X__ may appear to indicate -unresolved problems. If so, follow these additional steps: - -* Right-click on the project directory. - -* In the resulting __Properties__ dialog, select __Android__ from the navigation pane. - -* For the project build target, select the highest Android API level (currently API Level 19) you have installed. - -* Click __OK__. - -* Select __Clean__ from the __Project__ menu. This should correct all the errors in the project. - http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/edge/guide/platforms/amazonfireos/plugin.md ---------------------------------------------------------------------- diff --git a/www/docs/en/edge/guide/platforms/amazonfireos/plugin.md b/www/docs/en/edge/guide/platforms/amazonfireos/plugin.md deleted file mode 100644 index d4fdac4..0000000 --- a/www/docs/en/edge/guide/platforms/amazonfireos/plugin.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -license: > - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - -title: Amazon Fire OS Plugins ---- - -# Amazon Fire OS Plugins - -Follow the instructions provided in the [Android Plugins](../android/plugin.html) Guide for an overview of developing custom plugins. - -## Echo Amazon Fire OS Plugin Example - -To match the JavaScript interface's _echo_ feature described in -Application Plugins, use the `plugin.xml` to inject a `feature` -specification to the local platform's `config.xml` file: - - <platform name="amazon-fireos"> - <config-file target="config.xml" parent="/*"> - <feature name="Echo"> - <param name="android-package" value="org.apache.cordova.plugin.Echo"/> - </feature> - </config-file> - </platform> - -Then add the following to the -`src/org/apache/cordova/plugin/Echo.java` file: - - package org.apache.cordova.plugin; - - import org.apache.cordova.CordovaPlugin; - import org.apache.cordova.CallbackContext; - - import org.json.JSONArray; - import org.json.JSONException; - import org.json.JSONObject; - - /** - * This class echoes a string called from JavaScript. - */ - public class Echo extends CordovaPlugin { - - @Override - public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException { - if (action.equals("echo")) { - String message = args.getString(0); - this.echo(message, callbackContext); - return true; - } - return false; - } - - private void echo(String message, CallbackContext callbackContext) { - if (message != null && message.length() > 0) { - callbackContext.success(message); - } else { - callbackContext.error("Expected one non-empty string argument."); - } - } - } - -If you want to reuse Android Plugin code for the Amazon Fire OS platform then modify the plugin.xml to point to the `android` specific source file. For example, - - <platform name="amazon-fireos"> - <config-file target="config.xml" parent="/*"> - <feature name="Echo"> - <param name="android-package" value="org.apache.cordova.plugin.Echo"/> - </feature> - </config-file> - <source-file src="src/android/Echo.java" target-dir="src/org/apache/cordova/plugin" /> - </platform> - -If you want to write a customized plugin for the Amazon Fire OS platform then create a folder named `amazon` under your plugin src/ folder and modify the plugin.xml to point to the `amazon` specific source file. For example, - - <platform name="amazon-fireos"> - <config-file target="config.xml" parent="/*"> - <feature name="Echo"> - <param name="android-package" value="org.apache.cordova.plugin.Echo"/> - </feature> - </config-file> - <source-file src="src/amazon/Echo.java" target-dir="src/org/apache/cordova/plugin" /> - </platform> - -## Using Amazon WebView in your plugin - -Cordova for Amazon Fire OS makes use of custom Amazon WebView that is built on the open-source Chromium project. It is GPU accelerated and optimized for fluid performance on Kindle Fire. - -To understand how to best use Amazon WebView in your project, check out the [Amazon Developer Portal](https://developer.amazon.com/sdk/fire/IntegratingAWV.html). --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@cordova.apache.org For additional commands, e-mail: commits-h...@cordova.apache.org
