This is an automated email from the ASF dual-hosted git repository.
erisu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cordova-docs.git
The following commit(s) were added to refs/heads/master by this push:
new 8941c83a5f doc: various page improvements (#1319)
8941c83a5f is described below
commit 8941c83a5fe3d8326e1a09d8fe757e5406cf5ad2
Author: エリス <[email protected]>
AuthorDate: Thu Jun 1 13:06:59 2023 +0900
doc: various page improvements (#1319)
* doc: fix layout formatting & add missing vartype tags
* doc(ios): improve clarity of defaultlocale preference config
* doc(ios|android): combine ErrorUrl preference config
* doc(ios): replace CFBundleVersion archive documentation link with current
docs
* doc(ios): improve ios-CFBundleIdentifier description
* doc(android): improve android-packageName description
* doc: improve config.xml access, allow-navigation, and allow-intent
* doc: clean up MD formatting
* doc: move sample config.xml to top of page & update with default template
as base
* doc: improve config.xml overview section
* doc: cleanup table headers
* doc(android): add missing preferences & supporting inforamtion
* doc: convert MD table to HTML table to support UL/LI lists
* doc(android): remove old image from platform guide
* doc: refactor allow listed wording
* doc: refactor lib-file for Android only
* doc: cleaup platform support guide
* removed deprecated platforms
* refactor layout design
* doc: refactor plugin.xml - remove deprecated platforms
* doc: refactor plugin.xml - improve tagging for variable and platform type
* chore: apply suggestions from code review
* doc: remove html format from plugin.xml engine tag
---------
Co-authored-by: Niklas Merz <[email protected]>
---
www/docs/en/dev/config_ref/index.md | 193 ++++++++++--------
www/docs/en/dev/guide/appdev/security/index.md | 6 +-
www/docs/en/dev/guide/cli/index.md | 1 -
www/docs/en/dev/guide/platforms/android/index.md | 128 ++++++++++--
www/docs/en/dev/guide/platforms/ios/plugin.md | 4 +-
www/docs/en/dev/guide/support/index.md | 79 ++------
www/docs/en/dev/plugin_ref/spec.md | 242 ++++++++---------------
7 files changed, 324 insertions(+), 329 deletions(-)
diff --git a/www/docs/en/dev/config_ref/index.md
b/www/docs/en/dev/config_ref/index.md
index 279f9aa6ed..912c121920 100644
--- a/www/docs/en/dev/config_ref/index.md
+++ b/www/docs/en/dev/config_ref/index.md
@@ -25,49 +25,76 @@ description: List of supported tags in the config.xml file.
# Config.xml
-`config.xml` is a global configuration file that controls many aspects
-of a cordova application's behavior. This
-platform-agnostic XML file is arranged based on the W3C's [Packaged
-Web Apps (Widgets)](https://www.w3.org/TR/widgets/) specification, and
-extended to specify core Cordova API features, plugins, and
-platform-specific settings.
+The `config.xml` file is a global configuration file that manages various
aspects of a Cordova application's behavior. It is written in XML format and
follows the structure outlined in the W3C's [Packaged Web Apps
(Widgets)](https://www.w3.org/TR/widgets/) specification. Additionally, it is
extended to include core Cordova API features, plugins, and platform-specific
settings.
-For projects created with the Cordova CLI (described in [The
-Command-Line Interface](../guide/cli/index.html)), this file can be found in
the top-level
-directory:
+If you are using the Cordova CLI to create your project (as explained in [The
Command-Line Interface](../guide/cli/index.html)), you can locate the
`config.xml` file in the top-level directory of your project.
+```bash
+./hellocordova
+└── config.xml
```
-app/config.xml
+
+When using the CLI to build a project, versions of this file are passively
copied into various `platforms/` subdirectories. For example:
+
+```bash
+./hellocordova
+└── platforms
+ ├── android
+ │ └── app
+ │ └── src
+ │ └── main
+ │ └── res
+ │ └── xml
+ │ └── config.xml
+ └── ios
+ └── HelloCordova
+ └── config.xml
```
-Note that before version 3.3.1-0.2.0, the file existed at `app/www/config.xml`,
-and that having it here is still supported.
+Some platforms offer integrated development environments (IDEs) like Xcode for
iOS and Android Studio for Android, which allow you to build and test your
application. If you choose to use these IDEs for building and testing your
project, it is recommended to run the `cordova prepare` CLI command whenever
you make changes to the Cordova application's `config.xml`. This ensures that
the updated configurations are copied into the respective `platforms/`
subdirectories.
-When using the CLI to build a project, versions of this file are
-passively copied into various `platforms/` subdirectories.
-For example:
+In addition to the configuration options described below, you have the ability
to customize the core set of images for your application on each target
platform. For more information, please refer to the topic on [Customizing
Icons](images.html).
-```
-app/platforms/ios/AppName/config.xml
-app/platforms/android/res/xml/config.xml
+**Sample `config.xml`:**
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<widget xmlns="http://www.w3.org/ns/widgets";
+ xmlns:cdv="http://cordova.apache.org/ns/1.0";
+ id="io.cordova.hellocordova"
+ version="1.0.0">
+ <name>HelloCordova</name>
+ <description>Sample Apache Cordova App</description>
+ <author email="[email protected]" href="https://cordova.apache.org";>
+ Apache Cordova Team
+ </author>
+
+ <content src="index.html" />
+
+ <!-- Security Related Settings -->
+ <access origin="https://cordova.apache.org"; />
+ <allow-intent href="http://*/*"; />
+ <allow-intent href="https://*/*"; />
+
+ <!-- Platform Configs & Platform Overriding Configs -->
+ <platform name="android"></platform>
+ <platform name="ios"></platform>
+</widget>
```
-In addition to the various configuration options detailed below, you
-can also configure an application's core set of images for each target
-platform. See [Customize icons topic](images.html) for more information.
+## widget
-# widget
Root element of the config.xml document.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
id<br/>{% cdv_vartype string %} | *Required* <br/> Specifies the app's
identifier. The `id` should be in a [reverse-DNS
format](https://en.wikipedia.org/wiki/Reverse_domain_name_notation#Examples)
however, only alphanumeric and dot characters are allowed. e.g:
`com.example.myapp`
version<br/>{% cdv_vartype string %} | *Required* <br/> Full version number
expressed in major/minor/patch notation.
android-versionCode<br/>{% cdv_vartype string %} {% cdv_platform android %} |
Alternative version for Android. Sets the [version
code](https://developer.android.com/tools/publishing/versioning.html) for the
application. See [the Android
guide](../guide/platforms/android/index.html#setting-the-version-code) for
information on how this attribute may be modified.
-ios-CFBundleVersion<br/>{% cdv_vartype string %} {% cdv_platform ios %} |
Alternative version for iOS. For further details, see [iOS
versioning](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-102364).
-android-packageName<br/>{% cdv_vartype string %} {% cdv_platform android %} |
Alternative package name for Android, overrides `id`.
-ios-CFBundleIdentifier<br/>{% cdv_vartype string %} <br/> {% cdv_platform ios
%} | Alternative bundle id for iOS. Overrides `id`.
-defaultlocale <br /> {% cdv_platform ios %} | Specified the default language
of the app, as an IANA language code.
+ios-CFBundleVersion<br/>{% cdv_vartype string %} {% cdv_platform ios %} |
Alternative version for iOS. For further details, see [Apple Developer -
CFBundleVersion](https://developer.apple.com/documentation/bundleresources/information_property_list/cfbundleversion).
+android-packageName<br/>{% cdv_vartype string %} {% cdv_platform android %} |
This preference overrides the id attribute with an alternative package name
specifically for Android.
+ios-CFBundleIdentifier<br/>{% cdv_vartype string %} {% cdv_platform ios %} |
This preference overrides the id attribute with an alternative bundle ID
specifically for iOS.
+defaultlocale <br /> {% cdv_vartype string %}{% cdv_platform ios %} | Specify
the default language of the app using an IANA language code. This preference
key explicitly sets the value for
[CFBundleDevelopmentRegion](https://developer.apple.com/documentation/bundleresources/information_property_list/cfbundledevelopmentregion).
For example, you can use values like `en` or `en_US`.
android-activityName<br/>{% cdv_vartype string %} {% cdv_platform android %} |
Set the activity name for your app in AndroidManifest.xml. Note that this is
only set once after the Android platform is first added.
xmlns<br/>{% cdv_vartype string %} | *Required* <br/> Namespace for the
config.xml document.
xmlns:cdv<br/>{% cdv_vartype string %} | *Required* <br/> Namespace prefix.
@@ -85,6 +112,7 @@ Examples:
```
## name
+
Specifies the app's formal name, as it appears on the device's home screen and
within app-store interfaces.
Examples:
@@ -96,6 +124,7 @@ Examples:
```
### short name
+
Specifies an optional display name for the app. Sometimes the app name should
be displayed differently on device's home screen than on informational and
app-store interfaces due to limited space.
Examples:
@@ -107,6 +136,7 @@ Examples:
```
## description
+
Specifies metadata that may appear within app-store listings.
Examples:
@@ -118,9 +148,10 @@ Examples:
```
## author
+
Specifies contact information that may appear within app-store listings.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
----------------- | ------------
email<br/>{% cdv_vartype string %} | *Required* <br/> Email of the author.
href<br/>{% cdv_vartype string %} | *Required* <br/> Website of the author.
@@ -135,9 +166,10 @@ Examples:
## content
+
Defines the app's starting page in the top-level web assets directory. The
default value is index.html, which customarily appears in a project's top-level
```www``` directory.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
----------------- | ------------
src<br/>{% cdv_vartype string %} | *Required* <br/> Defines the app's starting
page in the top-level web assets directory. The default value is index.html,
which customarily appears in a project's top-level ```www``` directory.
@@ -150,11 +182,12 @@ Examples:
```
## access
-Defines the set of external domains the app is allowed to communicate with.
The default value shown above allows it to access any server. See the Domain
[Whitelist Guide](../guide/appdev/allowlist/index.html) for details.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Defines the external domains that the app is allowed to communicate with. When
the access origin is set to "*", the app can access any server, but this can
potentially create a security risk. It is recommended to explicitly specify the
permitted URLs to ensure a secure configuration. For detailed instructions,
please refer to the [Allow List Guide](../guide/appdev/allowlist/index.html).
+
+Attributes | Description
----------------- | ------------
-origin<br/>{% cdv_vartype string %} | *Required* <br/> Defines the set of
external domains the app is allowed to communicate with. The default value
shown above allows it to access any server. See the Domain [Whitelist
Guide](../guide/appdev/allowlist/index.html) for details.
+origin<br/>{% cdv_vartype string %} | *Required* <br/> Defines the external
domain URL or URL pattern that the app is allowed to communicate with.
Examples:
@@ -168,13 +201,13 @@ Examples:
</widget>
```
-
## allow-navigation
-Controls which URLs the WebView itself can be navigated to. Applies to
top-level navigations only.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Controls which URLs the WebView can be navigated to. Applies to top-level
navigations only. See the [Allow List Guide][allow_list_navigation] for details.
+
+Attributes | Description
----------------- | ------------
-href<br/>{% cdv_vartype string %} | *Required* <br/> Defines the set of
external domains the WebView is allowed to navigate to. See the [Allow List
Guide][whitelist_navigation] for details.
+href<br/>{% cdv_vartype string %} | *Required* <br/> Defines the external
domain or domain pattern that the WebView is allowed to navigate to.
Examples:
@@ -187,11 +220,12 @@ Examples:
```
## allow-intent
-Controls which URLs the app is allowed to ask the system to open. By default,
no external URLs are allowed.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Controls which URLs the app is allowed to ask the system to open. By default,
no external URLs are allowed. See the [Allow List Guide][allow_list_intent] for
details.
+
+Attributes | Description
----------------- | ------------
-href<br/>{% cdv_vartype string %} | *Required* <br/> Defines which URLs the
app is allowed to ask the system to open. See the [Allow List
Guide][whitelist_intent] for details.
+href<br/>{% cdv_vartype string %} | *Required* <br/> Defines the URL or URL
pattern that the app is allowed to ask the system to open.
Examples:
@@ -201,6 +235,7 @@ Examples:
<allow-intent href="tel:*" />
<allow-intent href="sms:*" />
```
+
## edit-config
See [<config-file> docs][edit_config] for plugin.xml.
@@ -210,9 +245,10 @@ See [<config-file> docs][edit_config] for plugin.xml.
See [<config-file> docs][config_file] for plugin.xml.
## engine
+
Specifies details about what platform to restore during a prepare.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
----------------- | ------------
name<br/>{% cdv_vartype string %} | *Required* <br/> Name of the platform to
be restored
spec<br/>{% cdv_vartype string %} | *Required* <br/> Details about the
platform to be restored. This could be a ```major.minor.patch``` version
number, a directory containing the platform or a url pointing to a git
repository. This information will be used to retrieve the platform code to
restore from NPM, a local directory or a git repository. See [Platform
Spec][platform_spec] for further details.
@@ -225,6 +261,7 @@ Examples:
```
## plugin
+
Specifies details about what plugin to restore during a prepare. This element
is automatically added to a project's `config.xml` when a plugin is added using
the `--save` flag. See the [CLI reference][plugin_cli] for more information on
@@ -232,7 +269,7 @@ adding plugins.
_Note: As of Cordova 9.x, this tag is obsolete. [Learn
More](https://github.com/apache/cordova-lib/pull/750)_
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
----------------- | ------------
name<br/>{% cdv_vartype string %} | *Required* <br/> Name of the plugin to be
restored
spec<br/>{% cdv_vartype string %} | *Required* <br/> Details about the plugin
to be restored. This could be a ```major.minor.patch``` version number, a
directory containing the plugin or a url pointing to a git repository. This
information will be used to retrieve the plugin code to restore from NPM, a
local directory or a git repository. See [Plugin Spec][plugin_spec] for further
details.
@@ -245,6 +282,7 @@ Examples:
```
### variable
+
Persists the value of a CLI variable to be used when restoring a plugin during
a
prepare. This element is added to `config.xml` when a plugin that uses CLI
variables
is added using the `--save` flag. See the [CLI reference][plugin_cli] for more
@@ -256,7 +294,7 @@ project. In order for changes to this value to take effect,
remove the plugin fr
project and restore it by running `cordova prepare`. See the
[preference element][plugin_preference] of `plugin.xml` for more details on
CLI variables.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
----------------- | ------------
name<br/>{% cdv_vartype string %} | *Required* <br/> Name of the CLI variable.
Can only contain capital letters, digits, and underscores.
value<br/>{% cdv_vartype string %} | *Required* <br/> Value of the CLI
variable to be used when restoring the parent plugin during a prepare.
@@ -270,18 +308,28 @@ Examples:
```
## preference
+
Sets various options as pairs of name/value attributes. Each preference's name
is case-insensitive. Many preferences are unique to specific platforms,
and will be indicated as such.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
----------------- | ------------
AllowInlineMediaPlayback<br/>{% cdv_vartype boolean %} {% cdv_platform ios %}
| *Default: false* <br/> Set to true to allow HTML5 media playback to appear
inline within the screen layout, using browser-supplied controls rather than
native controls. For this to work, add the ```playsinline``` attribute to any
```<video>``` elements. *NOTE*: Prior to iOS 10, ```<video>``` elements need to
use the ```webkit-playsinline``` attribute name instead.
AllowNewWindows<br/>{% cdv_vartype boolean %} {% cdv_platform ios %} |
*Default: false* <br/> Set to true to allow JavaScript `window.open` and HTML
`target="_blank"` links to open a new view overlaying the web view.
AndroidLaunchMode<br/>{% cdv_vartype string %} {% cdv_platform android %} |
*Default: singleTop* <br/> Allowed values: standard, singleTop, singleTask,
singleInstance <br/> Sets the Activity android:launchMode attribute. This
changes what happens when the app is launched from app icon or intent and is
already running.
AndroidInsecureFileModeEnabled<br/>{% cdv_vartype boolean %} {% cdv_platform
android %} | *Default: false* <br/> If set to `true` loading `file:///` URLs
is allowed. __Note__: Enabling this setting allows malicious scripts loaded in
a `file:///` context to launch cross-site scripting attacks, either accessing
arbitrary local files including WebView cookies, app private data or even
credentials used on arbitrary web sites.
android-maxSdkVersion<br/>{% cdv_vartype number %} {% cdv_platform android %}
| *Default: Not Specified* <br/> Sets the `maxSdkVersion` attribute of the
`<uses-sdk>` tag in the project's `AndroidManifest.xml` (see [here][uses-sdk]).
-android-minSdkVersion<br/>{% cdv_vartype number %} {% cdv_platform android %}
| *Default: Dependent on cordova-android Version* <br/> Sets the
`minSdkVersion` attribute of the `<uses-sdk>` tag in the project's
`AndroidManifest.xml` (see [here][uses-sdk]).
-android-targetSdkVersion<br/>{% cdv_vartype number %} {% cdv_platform android
%} | *Default: Dependent on cordova-android Version* <br/> Sets the
`targetSdkVersion` attribute of the `<uses-sdk>` tag in the project's
`AndroidManifest.xml` (see [here][uses-sdk]).
+android-minSdkVersion<br/>{% cdv_vartype number %} {% cdv_platform android %}
| *Default: [Dependent on cordova-android
Version](../../guide/platforms/android/index.html#android-api-level-support)*
<br/> Sets the `minSdkVersion` attribute of the `<uses-sdk>` tag in the
project's `AndroidManifest.xml` (see [here][uses-sdk]).
+android-targetSdkVersion<br/>{% cdv_vartype number %} {% cdv_platform android
%} | *Default: [Dependent on cordova-android
Version](../../guide/platforms/android/index.html#android-api-level-support)*
<br/> Sets the `targetSdkVersion` attribute of the `<uses-sdk>` tag in the
project's `AndroidManifest.xml` (see [here][uses-sdk]).
+android-compileSdkVersion<br/>{% cdv_vartype number %} {% cdv_platform android
%} | *Default: [Dependent on cordova-android
Version](../../guide/platforms/android/index.html#android-api-level-support)*
<br/> Sets the `compileSdkVersion` attribute.
+android-buildToolsVersion<br/>{% cdv_vartype semver %} {% cdv_platform android
%} | *Default: [Dependent on cordova-android
Version](../../guide/platforms/android/index.html#android-api-level-support)*
<br/> Expects a full version string eg. "32.0.0". Changing this may also
requires changing the PATH environment variable to find the proper build
tools.<br/><br/>This preference is primarily for cordova development, for
testing upcoming versions of the Android SDK. Changing this has a high [...]
+GradleVersion<br/>{% cdv_vartype string %} {% cdv_platform android %} |
*Default: [Dependent on cordova-android
Version](../../guide/platforms/android/index.html#android-api-level-support)*
<br/> Sets the gradle wrapper version to use.<br/> <br/>This preference is
primarily for cordova development, for testing upcoming versions of the Android
SDK. Changing this has a high risk of breaking builds as newer build tools
frequently introduce breaking changes.
+AndroidGradlePluginVersion<br/>{% cdv_vartype semver %} {% cdv_platform
android %} | *Default: [Dependent on cordova-android
Version](../../guide/platforms/android/index.html#android-api-level-support)*
<br/> Sets the Android Gradle Plugin version to use.<br/> <br/>This preference
is primarily for cordova development, for testing upcoming versions of the
Android SDK. Changing this has a high risk of breaking builds as newer build
tools frequently introduce breaking changes.
+AndroidXAppCompatVersion<br/>{% cdv_vartype semver %} {% cdv_platform android
%} | *Default: [Dependent on cordova-android
Version](../../guide/platforms/android/index.html#android-api-level-support)*
<br/> Overrides Android App Compat library version.
+AndroidXWebKitVersion<br/>{% cdv_vartype semver %} {% cdv_platform android %}
| *Default: [Dependent on cordova-android
Version](../../guide/platforms/android/index.html#android-api-level-support)*
<br/>Overrides Android WebKit library version.
+AndroidGradlePluginGoogleServicesVersion<br/>{% cdv_vartype semver %} {%
cdv_platform android %} | *Default: [Dependent on cordova-android
Version](../../guide/platforms/android/index.html#android-api-level-support)*
<br/>Overrides the Google Services library version.
+AndroidGradlePluginGoogleServicesEnabled<br/>{% cdv_vartype boolean %} {%
cdv_platform android %} | *Default: false* <br/>Enables Google Services. The
`google-services.json` file will be required.
+GradlePluginKotlinEnabled<br/>{% cdv_vartype boolean %} {% cdv_platform
android %} | *Default: false* <br/>Enables Kotlin plugin for Kotline support.
AppendUserAgent<br/>{% cdv_vartype string %} {% cdv_platform android %} {%
cdv_platform ios %} | If set, the value will append to the end of old UserAgent
of webview. When using with OverrideUserAgent, this value will be ignored.
BackgroundColor<br/>{% cdv_vartype string %} {% cdv_platform android %} {%
cdv_platform ios %} | Sets the app's background color. Supports a four-byte hex
value, with the first byte representing the alpha channel, and standard RGB
values for the following three bytes. <br/>__Note__: `transparent` value will
set the application tile background to the accent color on Windows.
BackupWebStorage<br/>{% cdv_vartype string %} {% cdv_platform ios %} |
*Default: cloud* <br/> Allowed values: none, local, cloud. <br/> Set to cloud
to allow web storage data to backup via iCloud. Set to local to allow only
local backups via iTunes sync. Set to none prevent web storage backups.
@@ -289,8 +337,7 @@ CordovaWebViewEngine<br/>{% cdv_vartype string %} {%
cdv_platform ios %} | *Defa
DefaultVolumeStream<br/>{% cdv_vartype string %} {% cdv_platform android %} |
*Default: default* <br/> Added in cordova-android 3.7.0, This preference sets
which volume the hardware volume buttons link to. By default this is "call" for
phones and "media" for tablets. Set this to "media" to have your app's volume
buttons always change the media volume. Note that when using Cordova's media
plugin, the volume buttons will dynamically change to controlling the media
volume when any Media ob [...]
DisallowOverscroll<br/>{% cdv_vartype boolean %} {% cdv_platform ios %} {%
cdv_platform android %} | *Default: false* <br/> Set to **true** if you don't
want the interface to display any feedback when users scroll past the beginning
or end of content. On iOS, overscroll gestures cause content to bounce back to
its original position. on Android, they produce a more subtle glowing effect
along the top or bottom edge of the content. <br/>
EnableViewportScale<br/>{% cdv_vartype boolean %} {% cdv_platform ios %} |
*Default: false* <br/> Set to true to allow a viewport meta tag to either
disable or restrict the range of user scaling, which is enabled by default.
Place a viewport such as the following in the HTML to disable scaling and fit
content flexibly within the rendering WebView: <br/> ```<meta name='viewport'
content='width=device-width, initial-scale=1, user-scalable=no' />```
-ErrorUrl<br/>{% cdv_vartype url %} {% cdv_platform android %} | *Default:
null* <br/> If set, will display the referenced page upon an error in the
application instead of a dialog with the title "Application Error".
-ErrorUrl<br/>{% cdv_vartype string %} {% cdv_platform ios %} | If set, will
display the referenced local page upon an error in the application.
+ErrorUrl<br/>{% cdv_vartype url %} {% cdv_platform android %} {% cdv_platform
ios %} | *Default: null* <br/>When this preference is set, the application will
display the specified local page upon encountering an error. Additionally, if
this preference is set, the Android system will suppress the default dialog
titled "Application Error".
FullScreen<br/>{% cdv_vartype boolean %} {% cdv_platform android %} |
*Default: false* <br/> Allows you to hide the status bar at the top of the
screen. <br/> __Note__: Recommended platform-agnostic way to achieve this is to
use the [StatusBar plugin][statusbar_plugin].
GapBetweenPages<br/>{% cdv_vartype float %} {% cdv_platform ios %} | *Default:
0* <br/> The size of the gap, in points, between pages.
GradlePluginGoogleServicesEnabled<br/>{% cdv_vartype boolean %} {%
cdv_platform android %} | *Default: false* <br/> Set to true to enable the
Google Services Gradle plugin.
@@ -378,22 +425,24 @@ Examples:
```
## feature
+
If you use the CLI to build applications, you use the plugin command to enable
device APIs. This does not modify the top-level config.xml file, so the
<feature> element does not apply to your workflow. If you work directly in an
SDK and using the platform-specific config.xml file as source, you use the
<feature> tag to enable device-level APIs and external plugins. They often
appear with custom values in platform-specific config.xml files. See the API
Reference for details on how to spec [...]
the [Plugin Development Guide](../guide/hybrid/plugins/index.html) for more
information on plugins.
NOTE: Most of the time, you do NOT want to set this directly.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
----------------- | ------------
name<br/>{% cdv_vartype string %} | *Required* <br/> The name of the plugin to
enable.
### param
+
Used to specify certain plugin parameters such as: what package to retrieve
the plugin code from, and whether the plugin code is to be initialized during
the Webview's initialization.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
----------------- | ------------
name<br/>{% cdv_vartype string %} {% cdv_platform ios %} {% cdv_platform
android %} | *Required* <br/> Allowed values: android-package, ios-package,
onload. <br/> 'ios-package' and 'android-package' are used to specify the name
of the package (as specified by the 'value' attribute) to be used to initialize
the plugin code, while 'onload' is used to specify whether the corresponding
plugin (as specified in the 'value' attribute) is to be instantiated when the
controller is initialized.
-value(string or boolean) <br/> {% cdv_platform ios %} {% cdv_platform android
%} | *Required* <br/> Specifies the name of the package to be used to
initialize the plugin code (when the 'name' attribute is android-package or
ios-package), specifies the name of the plugin to be loaded during controller
initialization (when 'name' attribute is set to 'onload').
+value <br/> {% cdv_vartype String/Boolean %} {% cdv_platform ios %} {%
cdv_platform android %} | *Required* <br/> Specifies the name of the package
to be used to initialize the plugin code (when the 'name' attribute is
android-package or ios-package), specifies the name of the plugin to be loaded
during controller initialization (when 'name' attribute is set to 'onload').
Examples:
@@ -413,9 +462,10 @@ Examples:
## platform
+
When using the CLI to build applications, it is sometimes necessary to specify
preferences or other elements specific to a particular platform. Use the
<platform> element to specify configuration that should only appear in a single
platform-specific config.xml file.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
----------------- | ------------
name<br/>{% cdv_vartype string %} | *Required* <br/> The platform whose
preferences are being defined.
@@ -428,12 +478,13 @@ Examples:
```
## hook
+
Represents your custom script which will be called by Cordova when
certain action occurs (for example, after plugin is added or platform
prepare logic is invoked). This is useful when you need to extend
default Cordova functionality. See [Hooks
Guide](../guide/appdev/hooks/index.html) for more information.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
----------------- | ------------
type<br/>{% cdv_vartype string %} | *Required* <br/> Specifies the action
during which the custom script is to be called.
src<br/>{% cdv_vartype string %} | *Required* <br/> Specifies the location of
the script to be called when a specific action occurs.
@@ -448,7 +499,7 @@ Examples:
This tag installs resource files into your platform, and is similar to the
same tag in plugin.xml. This tag is currently only supported on
`[email protected]` or greater and `[email protected]` or greater.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
src<br/>{% cdv_vartype string %} {% cdv_platform ios %} {% cdv_platform
android %}| *Required* <br/> Location of the file relative to `config.xml`.
target<br/>{% cdv_vartype string %} | Path to where the file will be copied in
your directory.
@@ -460,45 +511,13 @@ For Android:
<resource-file src="FooPluginStrings.xml"
target="res/values/FooPluginStrings.xml" />
```
-
-# Sample config.xml
-Below is a sample config.xml file:
-
-```xml
-<?xml version='1.0' encoding='utf-8'?>
-<widget id="io.cordova.hellocordova" version="0.0.1"
xmlns="http://www.w3.org/ns/widgets";
xmlns:cdv="http://cordova.apache.org/ns/1.0";>
- <name>HelloCordova</name>
- <description>
- A sample Apache Cordova application that responds to the deviceready
event.
- </description>
- <author email="[email protected]" href="https://cordova.io";>
- Apache Cordova Team
- </author>
- <content src="index.html" />
- <access origin="*" />
- <allow-intent href="http://*/*"; />
- <allow-intent href="https://*/*"; />
- <allow-intent href="tel:*" />
- <allow-intent href="sms:*" />
- <allow-intent href="mailto:*"; />
- <allow-intent href="geo:*" />
- <platform name="android">
- <allow-intent href="market:*" />
- </platform>
- <platform name="ios">
- <allow-intent href="itms:*" />
- <allow-intent href="itms-apps:*" />
- </platform>
-</widget>
-```
-
[uses-sdk]:
https://developer.android.com/guide/topics/manifest/uses-sdk-element.html
[platform_spec]: ../reference/cordova-cli/index.html#platform-spec
[plugin_preference]: ../plugin_ref/spec.html#preference
[plugin_spec]: ../reference/cordova-cli/index.html#plugin-spec
[plugin_cli]:
../reference/cordova-cli/index.html#cordova-plugin-command
-[whitelist_navigation]:
../guide/appdev/allowlist/index.html#navigation-allow-list
-[whitelist_intent]: ../guide/appdev/allowlist/index.html#intent-allow-list
+[allow_list_navigation]:
../guide/appdev/allowlist/index.html#navigation-allow-list
+[allow_list_intent]: ../guide/appdev/allowlist/index.html#intent-allow-list
[statusbar_plugin]: ../reference/cordova-plugin-statusbar/
[edit_config]: ../plugin_ref/spec.html#edit-config
[config_file]: ../plugin_ref/spec.html#config-file
diff --git a/www/docs/en/dev/guide/appdev/security/index.md
b/www/docs/en/dev/guide/appdev/security/index.md
index 803cb6aeca..71e3e33110 100644
--- a/www/docs/en/dev/guide/appdev/security/index.md
+++ b/www/docs/en/dev/guide/appdev/security/index.md
@@ -42,7 +42,7 @@ By default the app's navigation is unrestricted. It's
recommended to restrict th
## Iframes and the Callback Id Mechanism
-If content is served in an iframe from a whitelisted domain, that domain will
have access to the native Cordova bridge. This means that if you whitelist a
third-party advertising network and serve those ads through an iframe, it is
possible that a malicious ad will be able to break out of the iframe and
perform malicious actions. Because of this, you should generally not use
iframes unless you control the server that hosts the iframe content. Also note
that there are third party plugins [...]
+If content is served in an iframe from a allow listed domain, that domain will
have access to the native Cordova bridge. This means that if you allow a
third-party advertising network and serve those ads through an iframe, it is
possible that a malicious ad will be able to break out of the iframe and
perform malicious actions. Because of this, you should generally not use
iframes unless you control the server that hosts the iframe content. Also note
that there are third party plugins av [...]
## Certificate Pinning
@@ -82,10 +82,10 @@ When running Cordova on Android, using
`android:debuggable="true"` in the applic
### Do not use Android Gingerbread!
* Set your min-target-sdk level higher than 10. API 10 is Gingerbread, and
Gingerbread is no longer supported by Google or device manufacturers, and is
therefore not recommend by the Cordova team.
* Gingerbread has been shown to be insecure and one of the most targeted
mobile OSs
[https://www.mobilemag.com/2012/11/06/andriod-2-3-gingerbread-security/](https://bgr.com/2012/11/06/android-security-gingerbread-malware/).
-* The Whitelist on Android does not work with Gingerbread or lower. This means
an attacker can load malicious code in an iframe that would then have access to
all of the Cordova APIs and could use that access to steal personal data, send
SMS messages to premium-rate numbers, and perform other malicious acts.
+* The Allowlist on Android does not work with Gingerbread or lower. This means
an attacker can load malicious code in an iframe that would then have access to
all of the Cordova APIs and could use that access to steal personal data, send
SMS messages to premium-rate numbers, and perform other malicious acts.
### Use InAppBrowser for outside links
-* Use the InAppBrowser when opening links to any outside website. This is much
safer than whitelisting a domain name and including the content directly in
your application because the InAppBrowser will use the native browser's
security features and will not give the website access to your Cordova
environment. Even if you trust the third party website and include it directly
in your application, that third party website could link to malicious web
content.
+* Use the InAppBrowser when opening links to any outside website. This is much
safer than allow listing a domain name and including the content directly in
your application because the InAppBrowser will use the native browser's
security features and will not give the website access to your Cordova
environment. Even if you trust the third party website and include it directly
in your application, that third party website could link to malicious web
content.
### Validate all user input
* Always validate any and all input that your application accepts. This
includes usernames, passwords, dates, uploaded media, etc. Because an attacker
could manipulate your HTML and JS assets (either by decompiling your
application or using debugging tools like chrome://inspect), this validation
should also be performed on your server, especially before handing the data off
to any backend service.
diff --git a/www/docs/en/dev/guide/cli/index.md
b/www/docs/en/dev/guide/cli/index.md
index 66080706d1..e7e633b2a5 100644
--- a/www/docs/en/dev/guide/cli/index.md
+++ b/www/docs/en/dev/guide/cli/index.md
@@ -202,7 +202,6 @@ Use `plugin ls` (or `plugin list`, or `plugin` by itself)
to view currently inst
```bash
$ cordova plugin ls
cordova-plugin-camera 2.1.0 "Camera"
-cordova-plugin-whitelist 1.2.1 "Whitelist"
```
**See Also:**
diff --git a/www/docs/en/dev/guide/platforms/android/index.md
b/www/docs/en/dev/guide/platforms/android/index.md
index c19ca2560b..fd9409786d 100644
--- a/www/docs/en/dev/guide/platforms/android/index.md
+++ b/www/docs/en/dev/guide/platforms/android/index.md
@@ -31,19 +31,119 @@ Regardless of whether you intend to utilize
Android-specific command-line tools
The supported [Android API
Levels](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
(versions of Android) corresponding with the Cordova-Android released versions
are listed in the table below:
-cordova-android Version | Supported Android API-Levels | Equivalent Android
Version
-------------------------|------------------------------|-----------------------------
-12.X.X | 24 - 33 | 7.0 - 13.0.0
-11.X.X | 22 - 32 | 5.1 - 12.0.0 (L)
-10.X.X | 22 - 30 | 5.1 - 11.0.0
-9.X.X | 22 - 29 | 5.1 - 10.0.0
-8.X.X | 19 - 28 | 4.4 - 9.0.0
-7.X.X | 19 - 27 | 4.4 - 8.1
-6.X.X | 16 - 26 | 4.1 - 8.0.0
-5.X.X | 14 - 23 | 4.0 - 6.0.1
-4.1.X | 14 - 22 | 4.0 - 5.1
-4.0.X | 10 - 22 | 2.3.3 - 5.1
-3.7.X | 10 - 21 | 2.3.3 - 5.0.2
+<table>
+ <thead>
+ <tr>
+ <th>cordova-android Version</th>
+ <th>Android API-Levels (Android Version)</th>
+ <th>Library & Tooling Version</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>12.0.x</td>
+ <td>24 (7.0) - 33 (13.0)</td>
+ <td>
+ <ul>
+ <li>Build Tools: ^33.0.2</li>
+ <li>Kotlin: 1.7.21</li>
+ <li>Gradle: 7.6</li>
+ <li>Android Gradle Plugin: 7.4.2</li>
+ <li>AndroidX Compat Library: 1.6.1</li>
+ <li>AndroidX WebKit Library: 1.6.0</li>
+ <li>AndroidX Core SplashScreen: 1.0.0</li>
+ <li>Google Services Gradle Plugin: 4.3.15</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>11.0.x</td>
+ <td>22 (5.1) - 32 (12L)</td>
+ <td>
+ <ul>
+ <li>Build Tools: ^32.0.0</li>
+ <li>Kotlin: 1.7.21</li>
+ <li>Gradle: 7.4.2</li>
+ <li>Android Gradle Plugin: 7.2.1</li>
+ <li>AndroidX Compat Library: 1.4.2</li>
+ <li>AndroidX WebKit Library: 1.4.0</li>
+ <li>AndroidX Core SplashScreen: 1.0.0-rc01</li>
+ <li>Google Services Gradle Plugin: 4.3.10</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>10.1.x</td>
+ <td>22 (5.1) - 30 (11.0)</td>
+ <td>
+ <ul>
+ <li>Build Tools: ^30.0.3</li>
+ <li>Kotlin: 1.5.21</li>
+ <li>Gradle: 7.1.1</li>
+ <li>Android Gradle Plugin: 4.2.2</li>
+ <li>AndroidX Compat Library: 1.3.1</li>
+ <li>AndroidX WebKit Library: 1.4.0</li>
+ <li>Google Services Gradle Plugin: 4.3.8</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>10.0.x</td>
+ <td>22 (5.1) - 30 (11.0)</td>
+ <td>
+ <ul>
+ <li>Build Tools: ^30.0.3</li>
+ <li>Kotlin: 1.5.20</li>
+ <li>Gradle: 7.1.1</li>
+ <li>Android Gradle Plugin: 4.2.2</li>
+ <li>AndroidX Compat Library: 1.3.0</li>
+ <li>AndroidX WebKit Library: 1.4.0</li>
+ <li>Google Services Gradle Plugin: 4.3.5</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>9.X.X</td>
+ <td>22 (5.1) - 29 (10.0)</td>
+ <td>-</td>
+ </tr>
+ <tr>
+ <td>8.X.X</td>
+ <td>19 (4.4) - 28 (9.0)</td>
+ <td>-</td>
+ </tr>
+ <tr>
+ <td>7.X.X</td>
+ <td>19 (4.4) - 27 (8.1)</td>
+ <td>-</td>
+ </tr>
+ <tr>
+ <td>6.X.X</td>
+ <td>16 (4.1) - 26 (8.0)</td>
+ <td>-</td>
+ </tr>
+ <tr>
+ <td>5.X.X</td>
+ <td>14 (4.0) - 23 (6.0)</td>
+ <td>-</td>
+ </tr>
+ <tr>
+ <td>4.1.X</td>
+ <td>14 (4.0) - 22 (5.1)</td>
+ <td>-</td>
+ </tr>
+ <tr>
+ <td>4.0.X</td>
+ <td>10 (2.3.3) - 22 (5.1)</td>
+ <td>-</td>
+ </tr>
+ <tr>
+ <td>3.7.X</td>
+ <td>10 (2.3.3) - 21 (5.0)</td>
+ <td>-</td>
+ </tr>
+ </tbody>
+</table>
_**Note:** The [cordova-android](https://github.com/apache/cordova-android)
versions listed above are not the Cordova CLI versions._
@@ -485,8 +585,6 @@ For more resources, please see:
- [Meet Android Studio](https://developer.android.com/studio/intro)
- [Build and run your app](https://developer.android.com/studio/run/index.html)
-
-
<img src="{{ site.baseurl
}}/static/img/guide/platforms/android/android-studio-electric-eel-20220101-2/hello-cordova-main-activity.png"
style="width: 100%;" alt="Hello Cordova MainActivity" />
## Upgrading
diff --git a/www/docs/en/dev/guide/platforms/ios/plugin.md
b/www/docs/en/dev/guide/platforms/ios/plugin.md
index 9415e8a1d8..f1ba5c1c7f 100644
--- a/www/docs/en/dev/guide/platforms/ios/plugin.md
+++ b/www/docs/en/dev/guide/platforms/ios/plugin.md
@@ -260,8 +260,8 @@ For JavaScript, you can attach Safari to the app running
within the iOS Simulato
- Don't forget to add your plugin's mapping to `config.xml`. If you
forget, an error is logged in the Xcode console.
-- Don't forget to add any hosts you connect to in the whitelist, as
- described in Domain [Whitelist Guide](../../appdev/whitelist/index.html). If
you forget, an error is
+- Don't forget to add any hosts you connect to in the allow list, as
+ described in Domain [Allow List Guide](../../appdev/allowlist/index.html).
If you forget, an error is
logged in the Xcode console.
[plugin-dev]: ../../hybrid/plugins/index.html
diff --git a/www/docs/en/dev/guide/support/index.md
b/www/docs/en/dev/guide/support/index.md
index caf886cbc9..515490bcd8 100644
--- a/www/docs/en/dev/guide/support/index.md
+++ b/www/docs/en/dev/guide/support/index.md
@@ -24,10 +24,9 @@ description: Compatibility table for all major plugins and
features.
# Platform Support
-The following shows the set of development tools and device APIs
-available for each platform. The device APIs listed here are provided by
-the core plugins, additional APIs are available via
-[third-party plugins](http://plugins.cordova.io).
+The table below provides a comprehensive overview of the supported development
platforms, core plugins, and features for each platform.
+
+For additional functionality, you can explore a wide range of third-party
plugins available on the [npm
registry](https://www.npmjs.com/search?q=keywords:ecosystem:cordova).
<!-- START HTML -->
@@ -35,65 +34,48 @@ the core plugins, additional APIs are available via
<thead>
<tr>
- <th>Platform:</th>
+ <th></th>
+ <th colspan="3">Platforms</th>
+ </tr>
+ <tr>
+ <th></th>
<th><a href="../platforms/android/index.html">Android</a></th>
<th><a href="../platforms/ios/index.html">iOS</a></th>
- <th><a href="../platforms/osx/index.html">OS X</a></th>
- <th><a href="../platforms/windows/index.html">Windows<br>8.1, Phone
8.1, 10</a></th>
<th><a href="../platforms/electron/index.html">Electron</a></th>
</tr>
- <tr>
- <th>CLI shorthand:</th>
- <th>android</th>
- <th>ios</th>
- <th>osx</th>
- <th>windows</th>
- <th>electron</th>
- </tr>
-
</thead>
<tbody>
<tr>
- <th></th>
- <th colspan="20"><h2><a href="../cli/index.html">Cordova CLI</a>
Development Platform</h2></th>
+ <th colspan="4"><h2><a href="../cli/index.html">Cordova CLI</a>
Development Platform</h2></th>
</tr>
<tr>
<th>Mac</th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx" class="y"></td>
- <td data-col="windows" class="n"></td>
<td data-col="electron" class="y"></td>
</tr>
<tr>
<th>Windows</th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="n"></td>
- <td data-col="osx" class="n"></td>
- <td data-col="windows" class="y"></td>
<td data-col="electron" class="y"></td>
</tr>
<tr>
<th>Linux</th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="n"></td>
- <td data-col="osx" class="n"></td>
- <td data-col="windows" class="n"></td>
<td data-col="electron" class="y"></td>
</tr>
<tr>
- <th></th>
- <th colspan="20"><h2>Core Plugin APIs</h2></th>
+ <th colspan="4"><h2>Core Plugin APIs</h2></th>
</tr>
<tr>
<th><a
href="../../reference/cordova-plugin-battery-status/">BatteryStatus</a></th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx" class="n"></td>
- <td data-col="windows" class="y">Windows Phone 8.1 only</td>
<td data-col="electron" class="p">Tests Pending</td>
</tr>
@@ -101,8 +83,6 @@ the core plugins, additional APIs are available via
<th><a href="../../reference/cordova-plugin-camera/">Camera</a></th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx" class="n"></td>
- <td data-col="windows" class="y"></td>
<td data-col="electron" class="y"></td>
</tr>
@@ -110,8 +90,6 @@ the core plugins, additional APIs are available via
<th><a
href="../../reference/cordova-plugin-media-capture/">Capture</a></th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx" class="n"></td>
- <td data-col="windows" class="y"></td>
<td data-col="electron" class="p">Tests Pending</td>
</tr>
@@ -119,8 +97,6 @@ the core plugins, additional APIs are available via
<th><a
href="../../reference/cordova-plugin-network-information/">Connection</a></th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx" class="n"></td>
- <td data-col="windows" class="y"></td>
<td data-col="electron" class="p">Tests Pending</td>
</tr>
@@ -128,8 +104,6 @@ the core plugins, additional APIs are available via
<th><a href="../../reference/cordova-plugin-device/">Device</a></th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx" class="y"></td>
- <td data-col="windows" class="y"></td>
<td data-col="electron" class="p">Tests Pending</td>
</tr>
@@ -137,8 +111,6 @@ the core plugins, additional APIs are available via
<th><a href="../../cordova/events/events.html">Events</a></th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx" class="n"></td>
- <td data-col="windows" class="y"></td>
<td data-col="electron" class="p">Tests Pending</td>
</tr>
@@ -146,8 +118,6 @@ the core plugins, additional APIs are available via
<th><a href="../../reference/cordova-plugin-file">File</a></th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx" class="y"></td>
- <td data-col="windows" class="y"></td>
<td data-col="electron" class="p">Tests Pending</td>
</tr>
@@ -155,8 +125,6 @@ the core plugins, additional APIs are available via
<th><a
href="../../reference/cordova-plugin-geolocation/">Geolocation</a></th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx" class="n"></td>
- <td data-col="windows" class="y"></td>
<td data-col="electron" class="p">Tests Pending</td>
</tr>
@@ -164,8 +132,6 @@ the core plugins, additional APIs are available via
<th><a
href="../../reference/cordova-plugin-globalization/">Globalization</a></th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx" class="n"></td>
- <td data-col="windows" class="y"></td>
<td data-col="electron" class="p">Tests Pending</td>
</tr>
@@ -173,8 +139,6 @@ the core plugins, additional APIs are available via
<th><a
href="../../reference/cordova-plugin-inappbrowser/">InAppBrowser</a></th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx" class="n"></td>
- <td data-col="windows" class="p">uses iframe</td>
<td data-col="electron" class="p">Tests Pending</td>
</tr>
@@ -182,8 +146,6 @@ the core plugins, additional APIs are available via
<th><a href="../../reference/cordova-plugin-media/">Media</a></th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx"></td>
- <td data-col="windows" class="y"></td>
<td data-col="electron" class="p">Tests Pending</td>
</tr>
@@ -191,8 +153,6 @@ the core plugins, additional APIs are available via
<th><a
href="../../reference/cordova-plugin-dialogs/">Notification</a></th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx" class="n"></td>
- <td data-col="windows" class="y"></td>
<td data-col="electron" class="p">Tests Pending</td>
</tr>
@@ -200,8 +160,6 @@ the core plugins, additional APIs are available via
<th><a
href="../../reference/cordova-plugin-splashscreen/">Splashscreen</a></th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx" class="n"></td>
- <td data-col="windows" class="y"></td>
<td data-col="electron" class="p">Tests Pending</td>
</tr>
@@ -209,8 +167,6 @@ the core plugins, additional APIs are available via
<th><a href="../../reference/cordova-plugin-statusbar/">Status
Bar</a></th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx" class="n"></td>
- <td data-col="windows" class="y">WP 8.1 only</td>
<td data-col="electron" class="p">Tests Pending</td>
</tr>
@@ -218,8 +174,6 @@ the core plugins, additional APIs are available via
<th><a href="../../cordova/storage/storage.html">Storage</a></th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx" class="n"></td>
- <td data-col="windows" class="y">localStorage &<br> indexedDB</td>
<td data-col="electron" class="p">Tests Pending</td>
</tr>
@@ -227,30 +181,23 @@ the core plugins, additional APIs are available via
<th><a
href="../../reference/cordova-plugin-vibration/">Vibration</a></th>
<td data-col="android" class="y"></td>
<td data-col="ios" class="y"></td>
- <td data-col="osx" class="n"></td>
- <td data-col="windows" class="y">WP 8.1 only</td>
<td data-col="electron" class="n"></td>
</tr>
<tr>
- <th></th>
- <th colspan="20"><h2>Platform Features</h2></th>
+ <th colspan="4"><h2>Platform Features</h2></th>
</tr>
<tr>
<th><a
href="../hybrid/plugins/index.html">Plugin<br/>Interface</a></th>
<td data-col="android" class="y"><a
href="../platforms/android/plugin.html">(see details)</a></td>
<td data-col="ios" class="y"><a
href="../platforms/ios/plugin.html">(see details)</a></td>
- <td data-col="osx" class="y"></td>
- <td data-col="windows" class="y"></td>
- <td data-col="electron" class="p">Tests Pending</td>
+ <td data-col="electron"> - </td>
</tr>
<tr>
<th><a
href="../hybrid/webviews/index.html">Embedded<br/>WebView</a></th>
<td data-col="android" class="y"><a
href="../platforms/android/webview.html">(see details)</a></td>
<td data-col="ios" class="y"><a
href="../platforms/ios/webview.html">(see details)</a></td>
- <td data-col="osx" class="y"></td>
- <td data-col="windows" class="n"></td>
- <td data-col="electron" class="p">Tests Pending</td>
+ <td data-col="electron"> - </td>
</tr>
</tbody>
</table>
diff --git a/www/docs/en/dev/plugin_ref/spec.md
b/www/docs/en/dev/plugin_ref/spec.md
index 2898a50424..4d1ce952e7 100644
--- a/www/docs/en/dev/plugin_ref/spec.md
+++ b/www/docs/en/dev/plugin_ref/spec.md
@@ -32,11 +32,11 @@ Plugin.xml file defines the structure and settings required
for your plugin. It
The `plugin` element is the plugin manifest's top-level element.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
-xmlns(string) | *Required* <br/> The plugin namespace,
`http://apache.org/cordova/ns/plugins/1.0`. If the document contains XML from
other namespaces, such as tags to be added to the `AndroidManifest.xml` file in
the case of Android, those namespaces should also be included in the <plugin>
element.
-id(string) | *Required* <br/> A npm-style identifier for the plugin.
-version(string) | *Required* <br/> A version number for the plugin.
[Semver](https://semver.org/) syntax is supported.
+xmlns<br />{% cdv_vartype string %}| *Required* <br/> The plugin namespace,
`http://apache.org/cordova/ns/plugins/1.0`. If the document contains XML from
other namespaces, such as tags to be added to the `AndroidManifest.xml` file in
the case of Android, those namespaces should also be included in the <plugin>
element.
+id<br />{% cdv_vartype string %}| *Required* <br/> A npm-style identifier for
the plugin.
+version<br />{% cdv_vartype string %}| *Required* <br/> A version number for
the plugin. [Semver](https://semver.org/) syntax is supported.
Example:
```xml
@@ -55,12 +55,12 @@ The child elements of the `<engines>` element specify
versions of Apache Cordova
>is in a plugin's `package.json`. See [specifying Cordova
>dependencies](../guide/hybrid/plugins/index.html#specifying-cordova-dependencies)
>for more information
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
-name(string) | *Required* <br/> Name of the engine. Here are the default
engines that are supported : <ul><li> `cordova` </li> <li> `cordova-plugman`
</li> <li> `cordova-android` </li> <li> `cordova-browser` </li> <li>
`cordova-ios` </li> <li> `cordova-windows` </li> <li> `cordova-osx` </li> <li>
`windows-os` </li> <li> `android-sdk` (returns the highest Android api level
installed) </li> <li> `windows-sdk` (returns the native windows SDK version)
</li> <li> `apple-xcode` (returns the xc [...]
-version(string) | *Required* <br/> The version that your framework must have
in order to install. Semver syntax is supported.
-scriptSrc(string) | **For custom frameworks only** <br/> *Required* <br/> The
script file that tells plugman the version of the custom framework. Ideally,
this file should be within the top level directory of your plugin directory.
-platform(string) | **For custom frameworks only** <br/> *Required* <br/> The
platforms your framework supports. You may use the wildcard `*` to say
supported for all platforms, specify multiple with a pipe character like
`android|ios` or just a single platform like `android`.
+name<br />{% cdv_vartype string %}| *Required* <br/>Name of the engine. Here
are the default engines that are supported: `cordova`, `cordova-plugman`,
`cordova-android`, `cordova-browser`, `cordova-ios`, `windows-os`,
`android-sdk` (returns the highest Android api level installed) , `apple-xcode`
(returns the xcode version), `apple-ios` (returns the highest iOS version
installed), `apple-osx` (returns the macOS version). You can also specify a
custom framework apart from the default ones.
+version<br />{% cdv_vartype string %}| *Required* <br/> The version that your
framework must have in order to install. Semver syntax is supported.
+scriptSrc<br />{% cdv_vartype string %}| **For custom frameworks only** <br/>
*Required* <br/> The script file that tells plugman the version of the custom
framework. Ideally, this file should be within the top level directory of your
plugin directory.
+platform<br />{% cdv_vartype string %}| **For custom frameworks only** <br/>
*Required* <br/> The platforms your framework supports. You may use the
wildcard `*` to say supported for all platforms, specify multiple with a pipe
character like `android|ios` or just a single platform like `android`.
Examples:
```xml
@@ -143,10 +143,10 @@ Example:
This element is used to list the files or directories to be copied into a
Cordova app's `www` directory. Any `<asset>` elements that are nested within
`<platform>` elements specify platform-specific web assets.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
-src(string) | *Required* <br/> Where the file or directory is located in the
plugin package, relative to the `plugin.xml` document. If a file does not exist
at the specified src location, the CLI stops and reverses the installation
process, issues a notification about the conflict, and exits with a non-zero
code.
-target(string) | *Required* <br/> Where the file or directory should be
located in the Cordova app, relative to the `www` directory. If a file already
exists at the target location, the CLI stops and reverses the installation
process, issues a notification about the conflict, and exits with a non-zero
code.
+src<br />{% cdv_vartype string %}| *Required* <br/> Where the file or
directory is located in the plugin package, relative to the `plugin.xml`
document. If a file does not exist at the specified src location, the CLI stops
and reverses the installation process, issues a notification about the
conflict, and exits with a non-zero code.
+target<br />{% cdv_vartype string %}| *Required* <br/> Where the file or
directory should be located in the Cordova app, relative to the `www`
directory. If a file already exists at the target location, the CLI stops and
reverses the installation process, issues a notification about the conflict,
and exits with a non-zero code.
Examples:
```xml
@@ -165,10 +165,10 @@ Assets can be targeted to subdirectories as well. This
will create the `js/exper
Most plugins include one or more JavaScript files. Each `<js-module>` tag
corresponds to a JavaScript file, and prevents the plugin's users from having
to add a `<script>` tag for each file. Do not wrap the file with
cordova.define, as it is added automatically. The module is wrapped in a
closure, with module, exports, and require in scope, as is normal for AMD
modules. Nesting `<js-module>` elements within `<platform>` declares
platform-specific JavaScript module bindings.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
-src(string) | References a file in the plugin directory relative to the
`plugin.xml` file. If src does not resolve to an existing file, the CLI stops
and reverses the installation, issues a notification of the problem, and exits
with a non-zero code.
-name(string) | Provides the last part of the module name. It can generally be
whatever you like, and it only matters if you want to use cordova.require to
import other parts of your plugins in your JavaScript code. The module name for
a `<js-module>` is your plugin's id followed by the value of name.
+src<br />{% cdv_vartype string %}| References a file in the plugin directory
relative to the `plugin.xml` file. If src does not resolve to an existing file,
the CLI stops and reverses the installation, issues a notification of the
problem, and exits with a non-zero code.
+name<br />{% cdv_vartype string %}| Provides the last part of the module name.
It can generally be whatever you like, and it only matters if you want to use
cordova.require to import other parts of your plugins in your JavaScript code.
The module name for a `<js-module>` is your plugin's id followed by the value
of name.
Example:
@@ -184,9 +184,9 @@ Also for this example, with a plugin id of `chrome-socket`,
the module name will
Allowed within `<js-module>` element. Used to specify the namespace under
`window` object where module.exports gets inserted. You can have as many
`<clobbers>` as you
like. Any object not available on `window` is created.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
-target(string) | The namespace where module.exports gets inserted to.
+target<br />{% cdv_vartype string %}| The namespace where module.exports gets
inserted to.
Example:
```xml
@@ -200,9 +200,9 @@ Here module.exports gets inserted into the `window` object
as `window.chrome.soc
Allowed within `<js-module>` element. Used to specify the namespace under
`window` object where module.exports gets merged with any existing value. If
any key already exists, the module's version overrides the original. You can
have as many `<merges>` as you like. Any object not available on `window` is
created.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
-target(string) | The namespace which module.exports gets merged to.
+target<br />{% cdv_vartype string %}| The namespace which module.exports gets
merged to.
Example:
```xml
@@ -227,13 +227,13 @@ Example:
The `<dependency>` tag allows you to specify other plugins on which the
current plugin depends. The plugins are referenced by their unique npm ids or
by github url.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
-id(string) | Provides the ID of the plugin.
-url(string) | A URL for the plugin. This should reference a git repository,
which the CLI attempts to clone.
-commit(string) | This is any git reference understood by `git checkout`: a
branch or tag name (e.g., `master`, `0.3.1`), or a commit hash (e.g.,
`975ddb228af811dd8bb37ed1dfd092a3d05295f9`).
-subdir(string) | Specifies that the targeted plugin dependency exists as a
subdirectory of the git repository. This is helpful because it allows the
repository to contain several related plugins, each specified individually.
<br/> If you set the `url` of a `<dependency>` tag to `"."` and provide a
`subdir`, the dependent plugin is installed from the same local or remote git
repository as the parent plugin that specifies the `<dependency>` tag. <br/>
Note that the `subdir` always specifie [...]
-version(string) | The version of the plugin depended on. Semver syntax is
supported.
+id<br />{% cdv_vartype string %}| Provides the ID of the plugin.
+url<br />{% cdv_vartype string %}| A URL for the plugin. This should reference
a git repository, which the CLI attempts to clone.
+commit<br />{% cdv_vartype string %}| This is any git reference understood by
`git checkout`: a branch or tag name (e.g., `master`, `0.3.1`), or a commit
hash (e.g., `975ddb228af811dd8bb37ed1dfd092a3d05295f9`).
+subdir<br />{% cdv_vartype string %}| Specifies that the targeted plugin
dependency exists as a subdirectory of the git repository. This is helpful
because it allows the repository to contain several related plugins, each
specified individually. <br/> If you set the `url` of a `<dependency>` tag to
`"."` and provide a `subdir`, the dependent plugin is installed from the same
local or remote git repository as the parent plugin that specifies the
`<dependency>` tag. <br/> Note that the `su [...]
+version<br />{% cdv_vartype string %}| The version of the plugin depended on.
Semver syntax is supported.
Examples:
```xml
@@ -245,9 +245,9 @@ Examples:
Identifies platforms that have associated native code or require modifications
to their configuration files. Tools using this specification can identify
supported platforms and install the code into Cordova projects. Plugins without
`<platform>` tags are assumed to be JavaScript-only, and therefore installable
on any and all platforms.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
-name(string) | *Required* <br/> Allowed values: ios, android, windows,
browser, osx <br/> Identifies a platform as supported, associating the
element's children with that platform.
+name<br />{% cdv_vartype string %}| *Required* <br/> Allowed values: ios,
android, browser, electron <br/> Identifies a platform as supported,
associating the element's children with that platform.
Example:
```xml
@@ -260,12 +260,12 @@ Example:
Identifies executable source code that should be installed into a project.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
-src(string) | *Required* <br/> Location of the file relative to `plugin.xml`.
If the src file can't be found, the CLI stops and reverses the installation,
issues a notification about the problem, and exits with a non-zero code.
-target-dir(string) | A directory into which the files should be copied,
relative to the root of the Cordova project. In practice, this is most
important for Java-based platforms, where a file in the `com.alunny.foo`
package must be located within the `com/alunny/foo` directory. For platforms
where the source directory is not important, this attribute should be omitted.
-framework(boolean) <br/> {% cdv_platform ios %} | *Default: false* <br/> If
set to true, also adds the specified file as a framework to the project.
-compiler-flags(string) <br/> {% cdv_platform ios %} | If set, assigns the
specified compiler flags for the particular source file.
+src<br />{% cdv_vartype string %}| *Required* <br/> Location of the file
relative to `plugin.xml`. If the src file can't be found, the CLI stops and
reverses the installation, issues a notification about the problem, and exits
with a non-zero code.
+target-dir<br />{% cdv_vartype string %}| A directory into which the files
should be copied, relative to the root of the Cordova project. In practice,
this is most important for Java-based platforms, where a file in the
`com.alunny.foo` package must be located within the `com/alunny/foo` directory.
For platforms where the source directory is not important, this attribute
should be omitted.
+framework<br />{% cdv_vartype boolean %} {% cdv_platform ios %} | *Default:
false* <br/> If set to true, also adds the specified file as a framework to
the project.
+compiler-flags<br />{% cdv_vartype string %} {% cdv_platform ios %} | If set,
assigns the specified compiler flags for the particular source file.
Examples:
```xml
@@ -279,13 +279,13 @@ Examples:
## header-file
-This is like `<source-file>` element but specifically for platforms such as
iOS and Android that distinguish between source files, headers, and resources.
This is not supported by Windows.
+This is like `<source-file>` element but specifically for platforms such as
iOS and Android that distinguish between source files, headers, and resources.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
-src(string) | *Required* <br/> Location of the file relative to `plugin.xml`.
If the src file can't be found, the CLI stops and reverses the installation,
issues a notification about the problem, and exits with a non-zero code.
-target-dir(string) | A directory into which the files should be copied,
relative to the root of the Cordova project.
-type(string) <br/> {% cdv_platform ios %} | If this value is `BridgingHeader`,
the file is imported in the `Bridging-Header.h` and can be called from swift
program.
+src<br />{% cdv_vartype string %}| *Required* <br/> Location of the file
relative to `plugin.xml`. If the src file can't be found, the CLI stops and
reverses the installation, issues a notification about the problem, and exits
with a non-zero code.
+target-dir<br />{% cdv_vartype string %}| A directory into which the files
should be copied, relative to the root of the Cordova project.
+type<br />{% cdv_vartype string %} {% cdv_platform ios %} | If this value is
`BridgingHeader`, the file is imported in the `Bridging-Header.h` and can be
called from swift program.
Example:
@@ -299,45 +299,28 @@ For iOS:
This is like `<source-file>` element, but specifically for platforms such as
iOS and Android that distinguish between source files, headers, and resources.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
-src(string) | *Required* <br/> Location of the file relative to `plugin.xml`.
If the src file can't be found, the CLI stops and reverses the installation,
issues a notification about the problem, and exits with a non-zero code.
-target(string) | Path to where the file will be copied in your directory.
-arch(string) <br/> {% cdv_platform windows %} | Allowed values: `x86`, `x64`
or `ARM`. <br/> Indicates that the file should only be included when building
for the specified architecture.
-device-target <br/> {% cdv_platform windows %} | Allowed values: `win` (or
`windows`), `phone` or `all`. <br/> Indicates that the file should only be
included when building for the specified target device type.
-versions <br/> {% cdv_platform windows %} | Indicates that the file should
only be included when building for versions that match the specified version
string. Value can be any valid node semantic version range string.
-reference <br/> {% cdv_platform windows %} | Indicates that the file should be
referenced from the src rather than copied to the target destination. The file
will appear in Visual Studio with the file name specified by target, however
will point to the respective src, depending on the architecture.
+src<br />{% cdv_vartype string %}| *Required* <br/> Location of the file
relative to `plugin.xml`. If the src file can't be found, the CLI stops and
reverses the installation, issues a notification about the problem, and exits
with a non-zero code.
+target<br />{% cdv_vartype string %}| Path to where the file will be copied in
your directory.
-Examples:
+Android Examples:
-For Android:
```xml
<resource-file src="FooPluginStrings.xml"
target="res/values/FooPluginStrings.xml" />
```
-For Windows:
-```xml
-<resource-file src="src/windows/win81/MobServices.pri"
target="win81\MobServices.pri" device-target="windows" versions="8.1"
arch="x64"/>
-
-<!-- Example of referencing -->
-<resource-file src="x86/foo.dll" target="foo.dll" arch="x86" reference="true"
/>
-<resource-file src="x64/foo.dll" target="foo.dll" arch="x64" reference="true"
/>
-```
-__NOTE__: `target` should use backslashes to avoid DEP2100 deploy error in
Visual Studio.
-
## config-file
Identifies an XML-based configuration file to be modified, where in that
document the modification should take place, and what should be modified.
Two file types that have been tested for modification with this element are
`xml` and `plist` files.
The `config-file` element only allows you to append new children to an XML
document tree. The children are XML literals to be inserted in the target
document.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
-target(string) | The file to be modified, and the path relative to the root of
the Cordova project. If the specified file does not exist, the tool ignores the
configuration change and continues installation. <br/> The target can include
wildcard (`*`) elements. In this case, the CLI recursively searches through the
project directory structure and uses the first match. <br/> On iOS, the
location of configuration files relative to the project directory root is not
known, so specifying a ta [...]
-parent(string) | An XPath selector referencing the parent of the elements to
be added to the config file. If you use absolute selectors, you can use a
wildcard (`*`) to specify the root element, e.g., `/*/plugins`. If the selector
does not resolve to a child of the specified document, the tool stops and
reverses the installation process, issues a warning, and exits with a non-zero
code. <br/> For `plist` files, the `parent` determines under what parent key
the specified XML should be inserted.
-after(string) | A prioritized list of accepted siblings after which to add the
XML snippet. Useful for specifying changes in files which require strict
ordering of XML elements like
[this](https://msdn.microsoft.com/en-us/library/windowsphone/develop/ff769509%28v=vs.105%29.aspx#BKMK_EXTENSIONSelement).
-device-target(string) <br/> {% cdv_platform windows %} | Allowed values:
`win`, `phone`, `all`. <br/> Applicable when affecting the meta-name
`package.appxmanifest`, this attribute indicates that the file should only be
modified when building for the specified target device type.
-versions(string) <br/> {% cdv_platform windows %} | Applicable when affecting
the meta-name `package.appxmanifest`, this attribute indicates that app
manifests for specific Windows versions should only be altered for versions
that match the specified version string. Value can be any valid node semantic
version range string.
+target<br />{% cdv_vartype string %}| The file to be modified, and the path
relative to the root of the Cordova project. If the specified file does not
exist, the tool ignores the configuration change and continues installation.
<br/> The target can include wildcard (`*`) elements. In this case, the CLI
recursively searches through the project directory structure and uses the first
match. <br/> On iOS, the location of configuration files relative to the
project directory root is not know [...]
+parent<br />{% cdv_vartype string %}| An XPath selector referencing the parent
of the elements to be added to the config file. If you use absolute selectors,
you can use a wildcard (`*`) to specify the root element, e.g., `/*/plugins`.
If the selector does not resolve to a child of the specified document, the tool
stops and reverses the installation process, issues a warning, and exits with a
non-zero code. <br/> For `plist` files, the `parent` determines under what
parent key the specif [...]
+after<br />{% cdv_vartype string %}| A prioritized list of accepted siblings
after which to add the XML snippet. Useful for specifying changes in files
which require strict ordering of XML elements.
Examples:
@@ -363,26 +346,14 @@ For `plist`:
</config-file>
```
-For windows-specific attributes:
-```xml
-<config-file target="package.appxmanifest" parent="/Package/Capabilities"
versions="<8.1.0">
- <Capability Name="picturesLibrary" />
- <DeviceCapability Name="webcam" />
-</config-file>
-<config-file target="package.appxmanifest" parent="/Package/Capabilities"
versions=">=8.1.0" device-target="phone">
- <DeviceCapability Name="webcam" />
-</config-file>
-```
-The above example will set pre-8.1 platforms (Windows 8, specifically) to
require the `webcam` device capability and the `picturesLibrary` general
capability, and apply the `webcam` device capability only to Windows 8.1
projects that build for Windows Phone. Windows desktop 8.1 systems are
unmodified.
-
## edit-config
Similar to `config-file`, `edit-config` identifies an XML-based configuration
file to be modified, where in that document the modification should take place,
and what should be modified. Instead of appending new children to an XML
document tree, `edit-config` makes modifications to attributes of XML elements.
There are two modes which will determine what type of attribute modification
will be made, `merge` or `overwrite`. `edit-config` has one child and that
child will contain the attrib [...]
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
-file(string) | The file to be modified, and the path relative to the root of
the Cordova project. If the specified file does not exist, the tool ignores the
configuration change and continues installation. <br/> The target can include
wildcard (`*`) elements. In this case, the CLI recursively searches through the
project directory structure and uses the first match. <br/> On iOS, the
location of configuration files relative to the project directory root is not
known, so specifying a targ [...]
-target(string) | An XPath selector referencing the target element to make
attribute modifications to. If you use absolute selectors, you can use a
wildcard (`*`) to specify the root element, e.g., `/*/plugins`. If the selector
does not resolve to a child of the specified document, the tool stops and
reverses the installation process, issues a warning, and exits with a non-zero
code.
-mode(string) | The mode that determines what type of attribute modifications
will be made. <br/> `merge` - Adds the specified attributes to the target
element. Will replace the attribute values if the specified attributes already
exist in the target element. <br/> `overwrite` - Replaces all attributes in the
target element with the attributes specified.
+file<br />{% cdv_vartype string %}| The file to be modified, and the path
relative to the root of the Cordova project. If the specified file does not
exist, the tool ignores the configuration change and continues installation.
<br/> The target can include wildcard (`*`) elements. In this case, the CLI
recursively searches through the project directory structure and uses the first
match. <br/> On iOS, the location of configuration files relative to the
project directory root is not known, [...]
+target<br />{% cdv_vartype string %}| An XPath selector referencing the target
element to make attribute modifications to. If you use absolute selectors, you
can use a wildcard (`*`) to specify the root element, e.g., `/*/plugins`. If
the selector does not resolve to a child of the specified document, the tool
stops and reverses the installation process, issues a warning, and exits with a
non-zero code.
+mode<br />{% cdv_vartype string %}| The mode that determines what type of
attribute modifications will be made. <br/> `merge` - Adds the specified
attributes to the target element. Will replace the attribute values if the
specified attributes already exist in the target element. <br/> `overwrite` -
Replaces all attributes in the target element with the attributes specified.
Example:
@@ -490,56 +461,39 @@ Example:
<plugins-plist key="Foo" string="CDVFoo" />
```
-## lib-file
+## lib-file {% cdv_platform android %}
-Like source, resource, and header files, but specifically for platforms such
as BlackBerry 10 that use user-generated libraries. For the Windows platform,
the `<lib-file>` element allows the inclusion of an `<SDKReference>` in the
generated Windows project files.
+The `<lib-file>` element can be used for installing **.jar** files in the
project's **libs directory**.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
-src(string) | *Required* <br/> The location of the file relative to
`plugin.xml`. If `src` can't be found, the CLI stops and reverses the
installation, issues a warning about the problem, and exits with a non-zero
code. <br/> For Windows, it indicates the name of the SDK to include (which
will be used as value of the `Include` attribute of the generated
`<SDKReference>` element).
-arch(string) | The architecture for which the `.so` file has been built,
either `device` or `simulator`. <br/> For Windows, it indicates that the
`<SDKReference>` should only be included when building for the specified
architecture. Supported values are `x86`, `x64` or `ARM`.
-device-target(string) <br/> {% cdv_platform windows %} | Allowed values: `win`
(or `windows`), `phone` or `all`. <br/> Indicates that the `<SDKReference>`
should only be included when building for the specified target device type.
-versions(string) <br/> {% cdv_platform windows %} | Indicates that the
`<SDKReference>` should only be included when building for versions that match
the specified version string. Value can be any valid node semantic version
range string.
-
-For Android, the `<lib-file>` element is used for installing **.jar** files in
the project's **libs directory**. It supports only the `src` attribute which
contains the relative path to the .jar file.
+src<br />{% cdv_vartype string %}| *Required* <br/> The location of the `.jar`
file relative to `plugin.xml`. If `src` file can't be found, the CLI stops and
reverses the installation, issues a warning about the problem, and exits with a
non-zero code.
Examples:
-```xml
-<lib-file src="src/BlackBerry10/native/device/libfoo.so" arch="device" />
-<lib-file src="src/BlackBerry10/native/simulator/libfoo.so" arch="simulator" />
-```
-For Windows:
```xml
-<lib-file src="Microsoft.WinJS.2.0, Version=1.0" arch="x86" />
-<lib-file src="Microsoft.WinJS.2.0, Version=1.0" versions=">=8.1" />
-<lib-file src="Microsoft.WinJS.2.0, Version=1.0" target="phone" />
-<lib-file src="Microsoft.WinJS.2.0, Version=1.0" target="win" versions="8.0"
arch="x86" />
+<lib-file src="src/android/libs/foobar.jar"/>
```
## framework
Identifies a framework (usually part of the OS/platform) on which the plugin
depends.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
-src(string) | *Required* <br/> The name of the system framework or the
relative path to one which is included as part of your plugin files.
-custom(boolean) | Indicates whether the framework is included as part of your
plugin files.
-weak(boolean) | *Default: false* <br/> Indicates whether the framework should
be weakly linked.
-type(string) | Indicates the type of framework to add.
-parent(string) | *Default: .* <br/> Sets the relative path to the directory
containing the sub-project to which to add the reference. The default, `.`,
implies the application project.
-arch(string) <br/> {% cdv_platform windows %} | Allowed values: `x86`, `x64`
or `ARM`. <br/> Indicates that the framework should only be included when
building for the specified architecture.
-device-target(string) <br/> {% cdv_platform windows %} | Allowed values: `win`
(or `windows`), `phone` or `all`. <br/> Indicates that the framework should
only be included when building for the specified target device type.
-versions(string) <br/> {% cdv_platform windows %} | Indicates that the
framework should only be included when building for versions that match the
specified version string. Value can be any valid node semantic version range
string.
-target-dir(string) <br/> {% cdv_platform windows %} | Indicates a subdirectory
into which the framework should be copied. In practice, this is most important
when plugin contains different framework versions for different chip
architectures or device targets, but which have the same name. This allows you
to specify different subfolders for each framework version so that they don't
overlap each other.
-implementation(string) <br/> {% cdv_platform windows %} | Sets the relative
path to `.dll` file that contains implementation for WinMD component, written
in C++.
-spec(string) <br/> {% cdv_platform ios %} | Paired with `type="podspec"`, this
is the spec string for the CocoaPod you want to install (static library only).
CocoaPod support only exists in `cordova-ios 4.3.0` and `cordova-cli 6.4.0`.
For your plugin, make sure you add the appropriate `<engine>` tags and
`package.json`
[dependencies](../guide/hybrid/plugins/index.html#specifying-cordova-dependencies)
to ensure backwards-compatible support.
-embed(boolean) <br/> {% cdv_platform ios %} | *Default: false* <br/>Paired
with `custom="true"`, this is set to true if you want to embed your custom
framework into your app bundle, so it can be dynamically loaded at runtime
(dynamic framework). This puts your custom framework in the 'Embedded Binaries'
section of your Xcode Project Settings. Only supported with the combination of
`[email protected]` and `[email protected]`
-link(boolean) <br/> {% cdv_platform ios %} | *Default: !embed* <br/> Set this
to true if you want to link the framework. This puts the framework in the 'Link
Binaries with Libraries' section of your Xcode Project Settings.
+src<br />{% cdv_vartype string %}| *Required* <br/> The name of the system
framework or the relative path to one which is included as part of your plugin
files.
+custom<br />{% cdv_vartype boolean %}| Indicates whether the framework is
included as part of your plugin files.
+weak<br />{% cdv_vartype boolean %}| *Default: false* <br/> Indicates whether
the framework should be weakly linked.
+type<br />{% cdv_vartype string %}| Indicates the type of framework to add.
+parent<br />{% cdv_vartype string %}| *Default: .* <br/> Sets the relative
path to the directory containing the sub-project to which to add the reference.
The default, `.`, implies the application project.
+spec<br />{% cdv_vartype string %} {% cdv_platform ios %} | Paired with
`type="podspec"`, this is the spec string for the CocoaPod you want to install
(static library only). CocoaPod support only exists in `cordova-ios 4.3.0` and
`cordova-cli 6.4.0`. For your plugin, make sure you add the appropriate
`<engine>` tags and `package.json`
[dependencies](../guide/hybrid/plugins/index.html#specifying-cordova-dependencies)
to ensure backwards-compatible support.
+embed<br />{% cdv_vartype boolean %} {% cdv_platform ios %} | *Default: false*
<br/>Paired with `custom="true"`, this is set to true if you want to embed your
custom framework into your app bundle, so it can be dynamically loaded at
runtime (dynamic framework). This puts your custom framework in the 'Embedded
Binaries' section of your Xcode Project Settings. Only supported with the
combination of `[email protected]` and `[email protected]`
+link<br />{% cdv_vartype boolean %} {% cdv_platform ios %} | *Default: !embed*
<br/> Set this to true if you want to link the framework. This puts the
framework in the 'Link Binaries with Libraries' section of your Xcode Project
Settings.
Examples:
For iOS:
+
```xml
<framework src="libsqlite3.dylib" />
<framework src="social.framework" weak="true" />
@@ -548,6 +502,7 @@ For iOS:
```
On Android (as of [email protected]), framework tags are used to include
Maven dependencies, or to include bundled library projects.
+
```xml
<!-- Depend on latest version of GCM from play services -->
<framework src="com.google.android.gms:play-services-gcm:+" />
@@ -558,36 +513,12 @@ On Android (as of [email protected]), framework tags
are used to include Mav
```
Framework can also be used to have custom `.gradle` files sub-included into
the main project's `build.gradle` file:
-```xml
-<framework src="relative/path/rules.gradle" custom="true"
type="gradleReference" />
-```
-
-On Windows, using `custom='true'` and `type='projectReference'` will add a
reference to the project which will be added to the compile+link steps of the
cordova project. This essentially is the only way currently that a 'custom'
framework can target multiple architectures as they are explicitly built as a
dependency by the referencing cordova application.
-```xml
-<framework src="path/to/project/LibProj.csproj" custom="true"
type="projectReference"/>
-```
-
-Examples of using these Windows specific attributes:
-```xml
-<framework src="src/windows/example.dll" arch="x64" />
-<framework src="src/windows/example.dll" versions=">=8.0" />
-<framework src="src/windows/example.vcxproj" type="projectReference"
target="win" />
-<framework src="src/windows/example.vcxproj" type="projectReference"
target="all" versions="8.1" arch="x86" />
-<framework src="src/windows/example.dll" target-dir="bin/x64" arch="x64"
custom="true"/>
-```
-
-Another example of using Windows-specific attributes to add a reference to
WinMD components, written in C# and C++, whose API will be available at runtime:
```xml
-<!-- C# component that consists of one .winmd file -->
-<framework src="lib\windows\component.winmd" versions="<10.0" />
-<!-- C++ component with separated metadata and implementation-->
-<framework src="lib\windows\x86\cppcomponent.winmd"
- implementation="lib\windows\x86\cppcomponent.dll"
- target-dir="component\x86" arch="x86" versions=">=10.0" />
+<framework src="relative/path/rules.gradle" custom="true"
type="gradleReference" />
```
-## podspec ({% cdv_platform ios %})
+## podspec {% cdv_platform ios %}
Identifies the CocoaPods `Podfile` that provides the dependencies in which the
plugin depends on.
This element contains a `<config>` and a `<pods>` tag.
@@ -598,35 +529,36 @@ The `<config>` element identifies the source urls in
which the CocoaPods specs a
This element contains one or more `<source>` tags.
#### source
-Attributes(type) | Description
+
+Attributes | Description
---------------- | ------------
-url | *Required* <br> The source url of pods spec.
+url<br />{% cdv_vartype string %} | *Required* <br> The source url of pods
spec.
### pods
The `<pods>` element identifies CocoaPods libraries.
This element contains a `<pod>` tag for each CocoaPods libraries.
-Attributes(type) | Description
+Attributes | Description
---------------- | ------------
-use-frameworks(string) | Default: false <br/> If `true`, the `use_frameworks!`
attribute is declared in the Podfile.
-inhibit-all-warnings(string) | Default: false <br/> If `true`, the
`inhibit_all_warnings!` attribute is declared in the Podfile.
+use-frameworks<br />{% cdv_vartype boolean %}| Default: false <br/> If `true`,
the `use_frameworks!` attribute is declared in the Podfile.
+inhibit-all-warnings<br />{% cdv_vartype boolean %}| Default: false <br/> If
`true`, the `inhibit_all_warnings!` attribute is declared in the Podfile.
#### pod
Attributes(type) | Description
---------------- | ------------
-name | *Required*<br/> Pod name
-spec | Pod spec
-swift-version | Specify swift version of the CocoaPods library
-git | Pod `git` option.
-branch | Pod `branch` option.
-tag | Pod `tag` option.
-commit | Pod `commit` option.
-configurations | Pod `configurations` option. For multiple values, separate
them with a comma.
-http | Pod `http` option.
-path | Pod `path` option. Pod located on the local file system.
-options | Pod options declared in raw format. If declared, the other Pod
options are overwritten.<br/>Example: `options=":git =>
'https://github.com/Alamofire/Alamofire.git', :tag => '3.1.1'"`
+name<br />{% cdv_vartype string %} | *Required*<br/> Pod name
+spec<br />{% cdv_vartype string %} | Pod spec
+swift-version<br />{% cdv_vartype string %} | Specify swift version of the
CocoaPods library
+git<br />{% cdv_vartype string %} | Pod `git` option.
+branch<br />{% cdv_vartype string %} | Pod `branch` option.
+tag<br />{% cdv_vartype string %} | Pod `tag` option.
+commit<br />{% cdv_vartype string %} | Pod `commit` option.
+configurations<br />{% cdv_vartype string %} | Pod `configurations` option.
For multiple values, separate them with a comma.
+http<br />{% cdv_vartype string %} | Pod `http` option.
+path<br />{% cdv_vartype string %} | Pod `path` option. Pod located on the
local file system.
+options<br />{% cdv_vartype string %} | Pod options declared in raw format. If
declared, the other Pod options are overwritten.<br/>Example: `options=":git =>
'https://github.com/Alamofire/Alamofire.git', :tag => '3.1.1'"`
Examples:
@@ -725,10 +657,10 @@ a `<preference>` tag.
The CLI checks that these required preferences are passed in. If not, it
should warn the user how to pass the variable in and exit with a non-zero code.
Preferences can be referenced elsewhere in `plugin.xml` using the syntax
`$PREFERENCE_NAME`.
-Attributes(type) <br/> <span class="sub-header">Only for platform:</span> |
Description
+Attributes | Description
---------------- | ------------
-name(string) | *Required* <br/> Name of the variable. Can only contain capital
letters, digits, and underscores.
-default(string) | Default value of the variable. If present, its value will be
used and no error will be emitted in case user does not enter any value.
+name<br />{% cdv_vartype string %}| *Required* <br/> Name of the variable. Can
only contain capital letters, digits, and underscores.
+default<br />{% cdv_vartype string %}| Default value of the variable. If
present, its value will be used and no error will be emitted in case user does
not enter any value.
Example:
```xml
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
