Return-Path: X-Original-To: apmail-cordova-commits-archive@www.apache.org Delivered-To: apmail-cordova-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 468C810AFB for ; Thu, 20 Feb 2014 21:09:30 +0000 (UTC) Received: (qmail 70231 invoked by uid 500); 20 Feb 2014 21:08:59 -0000 Delivered-To: apmail-cordova-commits-archive@cordova.apache.org Received: (qmail 69606 invoked by uid 500); 20 Feb 2014 21:08:45 -0000 Mailing-List: contact commits-help@cordova.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@cordova.apache.org Delivered-To: mailing list commits@cordova.apache.org Received: (qmail 69512 invoked by uid 99); 20 Feb 2014 21:08:44 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 20 Feb 2014 21:08:44 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id DD6C592A780; Thu, 20 Feb 2014 21:08:42 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: purplecabbage@apache.org To: commits@cordova.apache.org Date: Thu, 20 Feb 2014 21:09:27 -0000 Message-Id: <75abd74b81b346949c4f06cac40bb0a4@git.apache.org> In-Reply-To: References: X-Mailer: ASF-Git Admin Mailer Subject: [48/50] [abbrv] Version 3.4.0 http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/guide/cli/index.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/guide/cli/index.md b/docs/en/3.4.0/guide/cli/index.md new file mode 100644 index 0000000..ac02a64 --- /dev/null +++ b/docs/en/3.4.0/guide/cli/index.md @@ -0,0 +1,497 @@ +--- +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. + +--- + +# 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 (See the Overview for a description +of the various workflows.) However, you can also use the CLI to initialize project code, after +which you use 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 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) +* BlackBerry 10 (Mac, Linux, Windows) +* Windows Phone 7 (Windows) +* Windows Phone 8 (Windows) +* Windows 8 (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_. + +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. + +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` or `npm` on your + command line. + +1. Install the `cordova` utility. In Unix, prefixing the additional + `sudo` command may be necessary to install development utilities in + otherwise restricted directories: + + $ sudo npm install -g cordova + + The installation log may produce errors for any uninstalled + platform SDKs. Following installation, you should be able to run + `cordova` on the command line. + + **NOTE**: The `-g` flag above tells npm to install cordova globally. + 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` and on Unix at + `/usr/local/share/npm`. + +## 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. 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 wp7 + $ cordova platform add wp8 + $ cordova platform add windows8 + $ 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 are strongly discouraged +from editing any files in the `/platforms/` folder unless you know what you are doing +or are specifically told otherwise in documentation. This is because the files in the +`/platforms/` directory will be overwritten on prepare or plugin reinstallation. + +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 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` 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 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: + +![](img/guide/cli/android_emulate_init.png) + +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: + +![](img/guide/cli/android_emulate_install.png) + +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 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 and Plugin Development +Guide for details.) More commonly, you would add a plugin to enable +one of Cordova's basic device-level features +detailed in the API Reference. A list of these plugins, including +additional plugins provided by the community, can be found 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: + + org.apache.cordova.statusbar - Cordova StatusBar Plugin + +The `cordova plugin add` command requires you to specify the +repository for the plugin code. Please note that when you follow the +Web Project Dev workflow and use the CLI, the CLI will take care of adding +the plugin code to the appropriate place for each platform. (If you are following the +Native Project Dev Workflow, you will have to add plugins using Plugman (guide link here), +multiple times for each platform.) + +Here are examples of how you might use the CLI to add features to the app: + +* Basic device information (Device API): + + $ cordova plugin add org.apache.cordova.device + +* Network Connection and Battery Events: + + $ cordova plugin add org.apache.cordova.network-information + $ cordova plugin add org.apache.cordova.battery-status + +* Accelerometer, Compass, and Geolocation: + + $ cordova plugin add org.apache.cordova.device-motion + $ cordova plugin add org.apache.cordova.device-orientation + $ cordova plugin add org.apache.cordova.geolocation + +* Camera, Media playback and Capture: + + $ cordova plugin add org.apache.cordova.camera + $ cordova plugin add org.apache.cordova.media-capture + $ cordova plugin add org.apache.cordova.media + +* Access files on device or network (File API): + + $ cordova plugin add org.apache.cordova.file + $ cordova plugin add org.apache.cordova.file-transfer + +* Notification via dialog box or vibration: + + $ cordova plugin add org.apache.cordova.dialogs + $ cordova plugin add org.apache.cordova.vibration + +* Contacts: + + $ cordova plugin add org.apache.cordova.contacts + +* Globalization: + + $ cordova plugin add org.apache.cordova.globalization + +* Splashscreen: + + $ cordova plugin add org.apache.cordova.splashscreen + +* Open new browser windows (InAppBrowser): + + $ cordova plugin add org.apache.cordova.inappbrowser + +* Debug console: + + $ cordova plugin add org.apache.cordova.console + +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' + [ 'org.apache.cordova.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 org.apache.cordova.console + $ cordova plugin remove org.apache.cordova.console # same + +You can batch-remove or add plugins by specifying more than one +argument for each command: + + $ cordova plugin add org.apache.cordova.console org.apache.cordova.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 org.apache.cordova.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 org.apache.cordova.console@latest + $ cordova plugin add org.apache.cordova.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: + + $ cordova plugin add https://github.com/apache/cordova-plugin-console.git#r0.2.0 + +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: + + + +* 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` 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 + +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. 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/0e2118b6/docs/en/3.4.0/guide/hybrid/plugins/index.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/guide/hybrid/plugins/index.md b/docs/en/3.4.0/guide/hybrid/plugins/index.md new file mode 100644 index 0000000..b8dd5ea --- /dev/null +++ b/docs/en/3.4.0/guide/hybrid/plugins/index.md @@ -0,0 +1,211 @@ +--- +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. +--- + +# Plugin Development Guide + +A _plugin_ is a package of injected code that allows the Cordova webview within +which your 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. + +Plugins comprise a single JavaScript interface along with +corresponding native code libraries for each supported platform. 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](https://github.com/apache/cordova-android/tree/master/framework/src/org/apache/cordova) +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. This abbreviated version of +the `Device` plugin provides a simple example to use as a model: + + + + Device + Cordova Device Plugin + Apache 2.0 + cordova,device + + + + + + + + + + + + + + +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. 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: + + + +Then run a command such as the following to test whether iOS +dependencies load properly: + + $ plugman -platform ios /path/to/my/project/www /path/to/my/plugin + +For details on `plugman` options, see Using Plugman to Manage Plugins. +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 +- Android Plugins +- iOS Plugins +- BlackBerry 10 Plugins +- Windows Phone Plugins + +The Tizen platform does not support plugins. + +## Publishing Plugins + +Once you develop your plugin, you may want to publish and share it +with the community. You can publish your plugin to the cordova +registry (based on [`npmjs`](https://github.com/isaacs/npmjs.org)) or +to any other `npmjs`-based registry. Other developers can install it +automatically using either `plugman` or the Cordova CLI. (For details +on each development path, see Using Plugman to Manage Plugins and The +Command-Line Interface.) + +To publish a plugin you need to use the `plugman` tool and go through +the following steps: + + $ plugman adduser # that is if you don't have an account yet + $ plugman 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/0e2118b6/docs/en/3.4.0/guide/hybrid/webviews/index.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/guide/hybrid/webviews/index.md b/docs/en/3.4.0/guide/hybrid/webviews/index.md new file mode 100644 index 0000000..e08b25b --- /dev/null +++ b/docs/en/3.4.0/guide/hybrid/webviews/index.md @@ -0,0 +1,36 @@ +--- +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. +--- + +# 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 +- Android WebViews +- iOS WebViews + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/guide/overview/index.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/guide/overview/index.md b/docs/en/3.4.0/guide/overview/index.md new file mode 100644 index 0000000..2ceb5c8 --- /dev/null +++ b/docs/en/3.4.0/guide/overview/index.md @@ -0,0 +1,139 @@ +--- +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. + +--- + +# Overview + +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. + +Use 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_ (browser window) that can access + device-level APIs, or if you want to develop a plugin interface + between native and WebView components. + +## Basic Components + +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, named +_index.html_ by default, 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. For the web app to interact with +various device features the way native apps do, it must also reference +a `cordova.js` file, which provides API bindings. + +The Cordova-enabled WebView may provide the application with its +entire user interface. It can also be a component within a larger, +hybrid application that mixes the WebView with native application +components. Cordova provides a _plugin_ interface for these +components to communicate with each other. + +## Development Paths + +As of version 3.0, you can use two basic workflows to create +a mobile application. While you can accomplish the same +thing using both workflows, certain tasks are better suited to using one workflow +over the other. For this reason, you should understand both workflows so +that you can use the best tool for the best situation. + +The two main workflows that are supported are the _Web Project Dev_ workflow and the _Native Platform Dev_ workflow. + +### Web Project Dev + +You can think of the first workflow as the _Web Project Dev_ workflow. You should use +this workflow when you want to create a Cordova application that runs on +as many mobile operating systems as possible with as little platform-specific +development work as possible. This workflow came into existence with Cordova 3.0 +and the creation of the Cordova _Command-line Interface_ (CLI). The CLI abstracts +away a lot of the functionality of lower-level shell scripts that take care of the +details involved with building your app, such as copying your web assets into +the correct folders for each mobile platform, making platform specific configuration +changes, or running specific build scripts to generate application binaries. You can read +more about the _Web Project Dev_ workflow in The Command-line Interface. Please note +that often when people speak of the "CLI," they are talking about this _Web Project Dev_ +workflow. + +### Native Platform Dev + +The second workflow can be thought of as a _Native Platform Dev_ workflow. You should use it +when you want to focus on building an application for a single platform and are +interested in changing the lower-level platform details. While you can still use this workflow +to build cross-platform apps, the lack of tools to abstract away the various build steps will +make it more difficult. For example, you will have to use Plugman to +install the same plugin once for each platform that you want to support. The +benefit to using this _Native Platform Dev_ workflow is that it gives you access to the lower-level +shell scripts to build and test the application, so if you are hacking on the native +side of things, this workflow is the most efficient way to test your changes. This workflow +is also appropriate if you want to use the CordovaWebView as a small part in a larger native +application (See the Embedding WebViews guide.) You can read about this workflow in the different +Shell Tool guides, for instance, Android Shell Tool Guide and iOS Shell Tool Guide. + +When first starting out, it might be easiest to use the _Web Project Dev_ workflow +to create an application. (To install the CLI, see The Command-line Interface.) +Depending on the set of platforms you wish to target, you can rely on +the CLI for progressively greater shares of the development cycle: + +* In the most basic scenario, you can use the CLI simply to create a + new project that is populated with default configuration for you to + modify. + +* For many mobile platforms, you can also use the CLI to set up + additional project files required to compile within each SDK. For + this to work, you must install each targeted platform's SDK. + (See the Platform Guides for instructions.) + As indicated in the Platform Support table, you may need to + run the CLI on different operating systems depending on the targeted + platform. + +* For supporting platforms, the CLI can compile executable + applications and run them in an SDK-based device emulator. + For comprehensive testing, you can also generate application files + and install them directly on a device. + +At any point in the development cycle, you can switch to using more of the _Native Platform +Dev_ workflow. The platform-specific SDK tools provided may provide a richer set of +options. (See the Platform Guides for details about each platform's SDK tool set.) + +An SDK environment is more appropriate if you want implement a hybrid +app that mixes web-based and native application components. +You may use the command-line utility to initially generate the app, or +iteratively thereafter to feed updated code to SDK tools. You may +also build the app's configuration file yourself. +(See The config.xml File for details.) + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/guide/platforms/amazonfireos/config.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/guide/platforms/amazonfireos/config.md b/docs/en/3.4.0/guide/platforms/amazonfireos/config.md new file mode 100644 index 0000000..436d292 --- /dev/null +++ b/docs/en/3.4.0/guide/platforms/amazonfireos/config.md @@ -0,0 +1,66 @@ +--- +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. +--- + +# 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 for information on global configuration options. + +- `KeepRunning` (boolean, defaults to `true`): Determines whether the + application stays running in the background even after a `pause` + event fires. + + + +- `ErrorUrl`: Specifies an error page that displays in response to + standard HTTP errors in the 400-500 range. Place the specified file + in the top-level directory containing the home page and other web + assets. + + + +- `LoadingDialog`: Display a native dialog when loading the app. The + value's format is _Title, Message_ + + + +- `LoadingPageDialog`: Display a native dialog when loading sub-pages + within an app. The value's format is _Title, Message_ + + + +- `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: + + + +- `SplashScreen`: The name of the file minus its extension in the + `res/drawable` directory. Various assets must share this common + name in various subdirectories. + + + +- `SplashScreenDelay` (number, defaults to `5000`): The amount of + time the splash screen image displays. + + + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/guide/platforms/amazonfireos/index.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/guide/platforms/amazonfireos/index.md b/docs/en/3.4.0/guide/platforms/amazonfireos/index.md new file mode 100644 index 0000000..f4b81ac --- /dev/null +++ b/docs/en/3.4.0/guide/platforms/amazonfireos/index.md @@ -0,0 +1,145 @@ +--- +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. +--- + +# 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 +* Amazon Fire OS WebViews +* Amazon Fire OS Plugins + +## Requirements and Support + +Developing Cordova apps for Amazon Fire OS requires the Android SDK and the Amazon WebView SDK. Check the requirements for these SDKs at the links below: + +* [Android SDK System](http://developer.android.com/sdk/) + +* [Amazon WebView SDK](https://developer.amazon.com/sdk/fire/IntegratingAWV.html#installawv) + +## Installation + + +### Android SDK + +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. + +For Cordova command-line tools to work, you need to include the SDK's +`tools` and `platform-tools` directories in your PATH environment. + +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 installs: + + export PATH=${PATH}:/Development/adt-bundle/sdk/platform-tools:/Development/adt-bundle/sdk/tools + +This exposes SDK tools in newly opened terminal windows. Otherwise run +this to make them available in the current session: + + $ source ~/.bash_profile + +To modify the PATH environment on Windows 7: + +* 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, for example: + + ;C:\Development\adt-bundle\sdk\platform-tools;C:\Development\adt-bundle\sdk\tools + +* Save the value and close both dialog boxes. + +You may also need to enable Java and Ant. Open a command prompt and +type `java`, and also type `ant`. Append to the PATH whichever fail to +run: + + ;%JAVA_HOME%\bin;%ANT_HOME%\bin + +### Amazon WebView SDK + +Download the Amazon WebView SDK from the [Amazon Developer Portal](https://developer.amazon.com/sdk/fire/IntegratingAWV.html#installawv). + +* Create a `libs/` folder in `~/.cordova/lib/amazon-fireos/cordova/3.1.0/` folder. +* Add the `awv_interface.jar` from the downloaded SDK to `~/.cordova/lib/amazon-fireos/cordova/3.1.0/libs/` + + +## Open a Project in the SDK + +Use the `cordova` utility to set up a new project, as described in The +Cordova The Command-line Interface. For example, in a source-code directory: + + $ cordova create hello com.example.hello "HelloWorld" + $ cd hello + $ cordova platform add amazon-fireos + $ cordova build + +Once created, you can use the Eclipse that comes along with the Android SDK to modify it: + +* Launch the __Eclipse__ application. + +* Select the __New Project__ menu item. + +* Choose __Android Project from Existing Code__ from the resulting dialog box, and press __Next__: + ![](img/guide/platforms//eclipse_new_project.png) + +* Navigate to `hello`, or whichever directory you created for the project, then to the `platforms/amazon-fireos` subdirectory. + +* 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 you have installed. + +* Click __OK__. + +* Select __Clean__ from the __Project__ menu. This should correct all the errors in the 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. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/guide/platforms/amazonfireos/plugin.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/guide/platforms/amazonfireos/plugin.md b/docs/en/3.4.0/guide/platforms/amazonfireos/plugin.md new file mode 100644 index 0000000..3fc5ca9 --- /dev/null +++ b/docs/en/3.4.0/guide/platforms/amazonfireos/plugin.md @@ -0,0 +1,100 @@ +--- +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. +--- + +# Amazon Fire OS Plugins + +Follow the instructions provided in the Android Plugins 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: + + + + + + + + + +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, + + + + + + + + + + +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, + + + + + + + + + + +## 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). http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/guide/platforms/amazonfireos/webview.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/guide/platforms/amazonfireos/webview.md b/docs/en/3.4.0/guide/platforms/amazonfireos/webview.md new file mode 100644 index 0000000..87fda43 --- /dev/null +++ b/docs/en/3.4.0/guide/platforms/amazonfireos/webview.md @@ -0,0 +1,113 @@ +--- +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. +--- + +# Amazon Fire OS WebViews + +Beginning with 3.0.0, you can use Cordova as a component in Amazon Fire OS applications. Amazon Fire OS refers to this component as `CordovaWebView`. `CordovaWebView` extends Amazon WebView that is built on the open source Chromium Project. By leveraging this feature, your web apps can utilize the latest HTML5 web standards running in a modern web runtime engine. + +## Prerequisites + +* Cordova 3.0.0 or greater + +* Android SDK updated to the latest SDK + +* Amazon WebView SDK + +## Guide to using CordovaWebView in a Amazon Fire OS Project + +1. Download and expand the [Amazon WebView SDK](https://developer.amazon.com/sdk/fire/IntegratingAWV.html#installawv) , then copy the awv_interface.jar into `/framework/libs` directory. Create a libs/ folder if it doesn't exist. + +2. `cd` into `/framework` and run `ant jar` to build the cordova jar. It creates the .jar file formed as `cordova-3.4.0.jar` in the `/framework` directory. + +3. Edit your application's `main.xml` file (under `/res/layout`) to look like the following, with the `layout_height`, `layout_width` and `id` modified to suit your application: + + + +4. Modify your activity so that it implements the `CordovaInterface`. You should implement the included methods. You may wish to copy them from `/framework/src/org/apache/cordova/CordovaActivity.java`, or implement them on your own. The code fragment below shows a basic application that uses the interface. Note how the referenced view id matches the `id` attribute specified in the XML fragment shown above: + + public class CordovaViewTestActivity extends Activity implements CordovaInterface { + CordovaWebView cwv; + /* Called when the activity is first created. */ + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + cwv = (CordovaWebView) findViewById(R.id.tutorialView); + Config.init(this); + cwv.loadUrl(Config.getStartUrl()); + } + +If you use the camera, you should also implement this: + + @Override + public void setActivityResultCallback(CordovaPlugin plugin) { + this.activityResultCallback = plugin; + } + /** + * Launch an activity for which you would like a result when it finished. When this activity exits, + * your onActivityResult() method is called. + * + * @param command The command object + * @param intent The intent to start + * @param requestCode The request code that is passed to callback to identify the activity + */ + public void startActivityForResult(CordovaPlugin command, Intent intent, int requestCode) { + this.activityResultCallback = command; + this.activityResultKeepRunning = this.keepRunning; + + // If multitasking turned on, then disable it for activities that return results + if (command != null) { + this.keepRunning = false; + } + + // Start activity + super.startActivityForResult(intent, requestCode); + } + + @Override + /** + * Called when an activity you launched exits, giving you the requestCode you started it with, + * the resultCode it returned, and any additional data from it. + * + * @param requestCode The request code originally supplied to startActivityForResult(), + * allowing you to identify who this result came from. + * @param resultCode The integer result code returned by the child activity through its setResult(). + * @param data An Intent, which can return result data to the caller (various data can be attached to Intent "extras"). + */ + protected void onActivityResult(int requestCode, int resultCode, Intent intent) { + super.onActivityResult(requestCode, resultCode, intent); + CordovaPlugin callback = this.activityResultCallback; + if (callback != null) { + callback.onActivityResult(requestCode, resultCode, intent); + } + } + +Finally, remember to add the thread pool, otherwise the plugins have no threads to run on: + + @Override + public ExecutorService getThreadPool() { + return threadPool; + } + +6. Copy your application's HTML and JavaScript files to your Amazon Fire OS project's `/assets/www` directory. + +7. Copy `config.xml` from `/framework/res/xml` to your project's `/res/xml` directory. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/guide/platforms/android/config.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/guide/platforms/android/config.md b/docs/en/3.4.0/guide/platforms/android/config.md new file mode 100644 index 0000000..fdf1744 --- /dev/null +++ b/docs/en/3.4.0/guide/platforms/android/config.md @@ -0,0 +1,93 @@ +--- +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. +--- + +# Android 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 Android builds. See The +config.xml File for information on global configuration options. + +- `KeepRunning` (boolean, defaults to `true`): Determines whether the + application stays running in the background even after a `pause` + event fires. Note: setting this to false will not kill the app after + a pause event, it will only halt execution of code in the cordova + webview while the app is in the background. + + + +- `LoadUrlTimeoutValue` (number in milliseconds, default to `20000`, + 20 seconds): When loading a page, the amount of time to wait before throwing + a timeout error. This example specifies 10 seconds rather than 20: + + + +- `SplashScreen` (string, defaults to `splash`): The name of the file minus + its extension in the `res/drawable` directory. Various assets must share + this common name in various subdirectories. + + + +- `SplashScreenDelay` (number in milliseconds, defaults to `3000`): The amount + of time the splash screen image displays. + + + +- `InAppBrowserStorageEnabled` (boolean, defaults to `true`): Controls + whether pages opened within an InAppBrowser can access the same + localStorage and WebSQL storage as pages opened with the default + browser. + + + +- `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. + + + +- `LoadingPageDialog` (string, defaults to `null`): The same as `LoadingDialog`, + but for loading every page after the first page in the application. + + + +- `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". + + + +- `ShowTitle` (boolean, defaults to `false`): Show the title at the top + of the screen. + + + +- `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`. + + + +- `SetFullscreen` (boolean, defaults to `false`): Same as the `Fullscreen` + parameter in the global configuration of this xml file. This Android-specific + element is deprecated in favor of the global `Fullscreen` element, and will + be removed in a future version. + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/guide/platforms/android/index.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/guide/platforms/android/index.md b/docs/en/3.4.0/guide/platforms/android/index.md new file mode 100644 index 0000000..1bb1ec1 --- /dev/null +++ b/docs/en/3.4.0/guide/platforms/android/index.md @@ -0,0 +1,244 @@ +--- +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. +--- + +# Android Platform Guide + +This guide shows how to set up your SDK development environment to +deploy Cordova apps for Android devices. It walks you through the process +of installing the Android SDK, opening an Android project in Eclipse SDK, +and deploying to an emulator or device. You will need to follow this guide +to at least Install the Android SDK, regardless of which workflow you +are following. (Both the _Web Project Dev_ and _Native Platform Dev_ workflows +require the Android SDK to be installed and accessible via your PATH.) + +See the following for more detailed platform-specific information: + +* Android Configuration +* Android WebViews +* Android Plugins +* Upgrading Android +* Android Command-line Tools + +The command-line tools above refer to versions prior to Cordova 3.0. +See The Command-Line Interface for information about the +current interface. + +## Requirements and Support + +See the [System Requirements](http://developer.android.com/sdk/index.html) +for the Android SDK. + +Cordova supports Android 2.2, 2.3, and 4.x. As a general rule, +platforms are deprecated as they dip below 5% on Google's +[distribution dashboard](http://developer.android.com/about/dashboards/index.html). + + + +Developers should use the `cordova` utility in conjunction with +the Android SDK. See The Command-Line Interface for +information how to install it, add projects, then build and deploy a +project. + +Install the Android SDK from +[developer.android.com/sdk](http://developer.android.com/sdk/). The android sdk +is distributed as an 'adt-bundle---' file. +On windows, the adt-bundle is packaged with an installer. +On OSX and Linux, simply unpack the 'adt-bundle' in the location you store development tools. +[More detailed information on Android SDK setup can be found here](http://developer.android.com/sdk/installing/bundle.html) + + +For Cordova command-line tools to work, you need to include the SDK's +`tools` and `platform-tools` directories in your PATH environment. On +Mac, 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 installs: + + export PATH=${PATH}:/Development/adt-bundle/sdk/platform-tools:/Development/adt-bundle/sdk/tools + +This exposes SDK tools in newly opened terminal windows. Otherwise run +this to make them available in the current session: + + $ source ~/.bash_profile + +To modify the PATH environment on Windows 7: + +* 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, for example: + + ;C:\Development\adt-bundle\sdk\platform-tools;C:\Development\adt-bundle\sdk\tools + +* Save the value and close both dialog boxes. + +You may also need to enable Java and Ant. Open a command prompt and +type `java`, and also type `ant`. Append to the PATH whichever fail to +run: + + ;%JAVA_HOME%\bin;%ANT_HOME%\bin + +## Open a Project in the SDK + +Use the `cordova` utility to set up a new project, as described in The +Cordova The Command-Line Interface. For example, in a source-code directory: + + $ cordova create hello com.example.hello "HelloWorld" + $ cd hello + $ cordova platform add android + $ cordova build + +Once created, you can use the Eclipse that comes along with the Android SDK to modify it: + +* Launch the __Eclipse__ application. + +* Select the __New Project__ menu item. + +* Choose __Android Project from Existing Code__ from the resulting dialog box, and press __Next__: + ![](img/guide/platforms/android/eclipse_new_project.png) + +* Navigate to `hello`, or whichever directory you created for the project, then to the `platforms/android` subdirectory. + +* Make sure both `hello` and `hello-CordovaLib` projects are selected to be imported. The `hello-CordovaLib` project is needed as of Cordova 3.3.0 because Cordova is now used as an Android Library instead of a .jar file. + +* 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 you have installed. + +* Click __OK__. + +* Select __Clean__ from the __Project__ menu. This should correct all the errors in the project. + +## Deploy to Emulator + +You can use the `cordova` utility to run an app in an emulator, or you +can run it within the SDK. Either way, the SDK must first be +configured to display at least one device. To do so, use the Android +SDK Manager, a Java application that runs separately from Eclipse. +There are two ways to open it: + +* Run `android` on the command line. + +* From within Eclipse, press this toolbar icon: + + ![](img/guide/platforms/android/eclipse_android_sdk_button.png) + +Once open, the Android SDK Manager displays various runtime libraries: + +![](img/guide/platforms/android/asdk_window.png) + +Choose __Tools → Manage AVDs__ (Android Virtual Devices), then +choose any item from __Device Definitions__ in the resulting dialog +box: + +![](img/guide/platforms/android/asdk_device.png) + +Press __Create AVD__, optionally modifying the name, then press __OK__ +to accept the changes: + +![](img/guide/platforms/android/asdk_newAVD.png) + +The AVD then appears in the __Android Virtual Devices__ list: + +![](img/guide/platforms/android/asdk_avds.png) + +To open the emulator as a separate application, select the AVD and +press __Start__. It launches much as it would on the device, with +additional controls available for hardware buttons: + +![](img/guide/platforms/android/asdk_emulator.png) + +At this point you can use the `cordova` utility to deploy the +application to the emulator from the command line: + + $ cordova emulate android + +If instead you work within Eclipse, right-click the project and +choose __Run As → Android Application__. You may be asked to +specify an AVD if none are already open. + +For a faster experience, you can use the `Virtual Machine Acceleration` to improve +the execution speed. +Many modern CPUs provide extensions to execute Virtual Machines more efficiently. +Before attempting to use this type of acceleration, you need to determine if your +current development system's CPU, supports one the following virtualization technologies: + +* __Intel Virtualization Technology__ (VT-x, vmx) → [Intel VT-x supported processor list](http://ark.intel.com/products/virtualizationtechnology) +* __AMD Virtualization__ (AMD-V, SVM), only supported for Linux (Since May 2006, all CPUs AMD include AMD-V, except Sempron). + +Another way to find out if your Intel processor supports VT-x Technology, it's by executing the +`Intel Processor Identification Utility`, for `Windows`you can download it from the Intel [Download Center](https://downloadcenter.intel.com/Detail_Desc.aspx?ProductID=1881&DwnldID=7838), +or you can use the [booteable utility](https://downloadcenter.intel.com/Detail_Desc.aspx?ProductID=1881&DwnldID=7840&lang=eng), which is `OS Independent`. + +After install and execute the `Intel Processor Identification Utility` over Windows, you will get the following window, +in order to check if your CPU supports the Virtualization Technologies: + +![](img/guide/platforms/android/intel_pid_util_620px.png) + +In order to speed up the emulator, you need to download and install one or more `Intel x86 Atom` System Images, +as well as the `Intel Hardware Accelerated Execution Manager (HAXM)`. + +Open your Android SDK Manager, and select the `Intel x86 Atom` System Image, for whichever version that you want to test. Then go to `Extras` +and select `Intel x86 Emulator Accelerator (HAXM)`, and install those packages: + +![](img/guide/platforms/android/asdk_man_intel_image_haxm.png) + +After download, run the Intel installer, which is available within your +Android SDK at `extras/intel/Hardware_Accelerated_Execution_Manager`. +__Note__:`If you have any problems installing the package, you can find more information and step by step guidance check this` +[Intel Article](http://software.intel.com/en-us/android/articles/speeding-up-the-android-emulator-on-intel-architecture). + +Once installed, in order to test it, create new a AVD with the `CPU/ABI` set to an `Intel (Atom) x86` Image: + +![](img/guide/platforms/android/asdk_new_and_dev_intel.png) + +If you are using `Linux-based system`, follow the instructions in the [Android Developer Site](http://developer.android.com/tools/devices/emulator.html#vm-linux). + +When starting the emulator, ensure there are no error messages indicating a failure to load HAXM modules. + +## 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 android + +Alternately within Eclipse, right-click the project and choose __Run +As → Android Application__. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/guide/platforms/android/plugin.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/guide/platforms/android/plugin.md b/docs/en/3.4.0/guide/platforms/android/plugin.md new file mode 100644 index 0000000..55e0fe1 --- /dev/null +++ b/docs/en/3.4.0/guide/platforms/android/plugin.md @@ -0,0 +1,240 @@ +--- +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. +--- + +# Android Plugins + +This section provides details for how to implement native plugin code +on the Android platform. Before reading this, see Application Plugins +for an overview of the plugin's structure and its common JavaScript +interface. This section continues to demonstrate the sample _echo_ +plugin that communicates from the Cordova webview to the native +platform and back. For another sample, see also the comments in +[CordovaPlugin.java](https://github.com/apache/cordova-android/blob/master/framework/src/org/apache/cordova/CordovaPlugin.java). + +Android plugins are based on Cordova-Android, which consists of an +Android WebView with hooks attached to it. Plugins are represented as +class mappings in the `config.xml` file. A plugin consists of at +least one Java class that extends the `CordovaPlugin` class, +overriding one of its `execute` methods. As best practice, the plugin +should also handle `pause` and `resume` events, along with any message +passing between plugins. Plugins with long-running requests, +background activity such as media playback, listeners, or internal +state should implement the `onReset()` method as well. It executes +when the `WebView` navigates to a new page or refreshes, which reloads +the JavaScript. + +## Plugin Class Mapping + +The plugin's JavaScript interface uses the `cordova.exec` method as +follows: + + exec(, , , , []); + +This marshals a request from the WebView to the Android native side, +effectively calling the `action` method on the `service` class, with +additional arguments passed in the `args` array. + +Whether you distribute a plugin as Java file or as a _jar_ file of its +own, the plugin must be specified in your Cordova-Android +application's `res/xml/config.xml` file. See Application Plugins for +more information on how to use the `plugin.xml` file to inject this +`feature` element: + + + + + +The service name matches the one used in the JavaScript `exec` call. +The value is the Java class's fully qualified namespace identifier. +Otherwise, the plugin may compile but still be unavailable to Cordova. + +## Plugin Initialization and Lifetime + +One instance of a plugin object is created for the life of each +`WebView`. Plugins are not instantiated until they are first +referenced by a call from JavaScript, unless `` with an `onload` +`name` attribute is set to `"true"` in `config.xml`. E.g.: + + + + + + +Plugins should use the `initialize` method for their start-up logic. + + @override + public void initialize(CordovaInterface cordova, CordovaWebView webView) { + super.initialize(cordova, webView); + // your init code here + } + +## Writing an Android Java Plugin + +A JavaScript call fires off a plugin request to the native side, and +the corresponding Java plugin is mapped properly in the `config.xml` +file, but what does the final Android Java Plugin class look like? +Whatever is dispatched to the plugin with JavaScript's `exec` function +is passed into the plugin class's `execute` method. Most `execute` +implementations look like this: + + @Override + public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException { + if ("beep".equals(action)) { + this.beep(args.getLong(0)); + callbackContext.success(); + return true; + } + return false; // Returning false results in a "MethodNotFound" error. + } + +The JavaScript `exec` function's `action` parameter corresponds to a +private class method to dispatch with optional parameters. + +When catching exceptions and returning errors, it's important for the +sake of clarity that errors returned to JavaScript match Java's +exception names as much as possible. + +## Threading + +The plugin's JavaScript does _not_ run in the main thread of the +`WebView` interface; instead, it runs on the `WebCore` thread, as +does the `execute` method. If you need to interact with the user +interface, you should use the following variation: + + @Override + public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException { + if ("beep".equals(action)) { + final long duration = args.getLong(0); + cordova.getActivity().runOnUiThread(new Runnable() { + public void run() { + ... + callbackContext.success(); // Thread-safe. + } + }); + return true; + } + return false; + } + +Use the following if you do not need to run on the main interface's +thread, but do not want to block the `WebCore` thread either: + + @Override + public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException { + if ("beep".equals(action)) { + final long duration = args.getLong(0); + cordova.getThreadPool().execute(new Runnable() { + public void run() { + ... + callbackContext.success(); // Thread-safe. + } + }); + return true; + } + return false; + } + +## Echo Android 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: + + + + + + + + + +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."); + } + } + } + +The necessary imports at the top of the file extends the class from +`CordovaPlugin`, whose `execute()` method it overrides to receive +messages from `exec()`. The `execute()` method first tests the value +of `action`, for which in this case there is only one valid `echo` +value. Any other action returns `false` and results in an +`INVALID_ACTION` error, which translates to an error callback invoked +on the JavaScript side. + +Next, the method retrieves the echo string using the `args` object's +`getString` method, specifying the first parameter passed to the +method. After the value is passed to a private `echo` method, it is +parameter-checked to make sure it is not `null` or an empty string, in +which case `callbackContext.error()` invokes JavaScript's error +callback. If the various checks pass, the `callbackContext.success()` +passes the original `message` string back to JavaScript's success +callback as a parameter. + +## Android Integration + +Android features an `Intent` system that allows processes to +communicate with each other. Plugins have access to a +`CordovaInterface` object, which can access the Android `Activity` +that runs the application. This is the `Context` required to launch a +new Android `Intent`. The `CordovaInterface` allows plugins to start +an `Activity` for a result, and to set the callback plugin for when +the `Intent` returns to the application. + +As of Cordova 2.0, Plugins can no longer directly access the +`Context`, and the legacy `ctx` member is deprecated. All `ctx` +methods exist on the `Context`, so both `getContext()` and +`getActivity()` can return the required object. + +## Debugging Android Plugins + +Eclipse allows you to debug plugins as Java source included in the +project. Only the latest version of the Android Developer Tools +allows you to attach source code to _JAR_ dependencies, so this +feature is not yet fully supported.