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 andPlugin 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.
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 atplugins.cordova.io. You can use the CLI to search for plugins
from this registry. For example, searching for bar and codeproduces
a single result that matches both terms as case-insensitive substrings:
$ cordova plugin search bar code
com.phonegap.plugins.barcodescanner - Scans Barcodes
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. 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
$ cordova plugin add org.apache.cordova.network-information
$ cordova plugin add org.apache.cordova.battery-status
$ 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
$ 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
$ 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
$ 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
$ 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
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, you need to run the Plugman utility to add plugins
separately for each platform. (For more information, see Using Plugman to Manage Plugins.)
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' ]
[ '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
$ 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
When
adding a plugin, several options allow you to specify from where to fetch the
plugin. The examples above use a well-knownregistry.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
$ 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
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 events
from the corresponding hardware button.
Cordova
features a couple of global commands, which may help you if you get stuck or
experience a problem. The helpcommand
displays all available Cordova commands and their syntax:
$
cordova help
$ cordova # same
$ 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.
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 wwwdirectory.
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.
$ cordova platform update ios
...etc.
No comments:
Post a Comment