You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by om...@apache.org on 2016/02/02 22:05:36 UTC
[03/11] docs commit: WIP: Reworked all the elements/attributes to a
table-based format
WIP: Reworked all the elements/attributes to a table-based format
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/00c7ec7c
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/00c7ec7c
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/00c7ec7c
Branch: refs/heads/master
Commit: 00c7ec7ced3bf04fa4b0bd79439b820ba9961c83
Parents: d58d014
Author: Omar Mefire <om...@gmail.com>
Authored: Mon Jan 25 16:59:58 2016 -0800
Committer: Omar Mefire <om...@gmail.com>
Committed: Tue Feb 2 12:49:27 2016 -0800
----------------------------------------------------------------------
www/docs/en/dev/config_ref/index.md | 311 ++++++++++---------------------
1 file changed, 99 insertions(+), 212 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/00c7ec7c/www/docs/en/dev/config_ref/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/dev/config_ref/index.md b/www/docs/en/dev/config_ref/index.md
index 143b6a8..11de501 100644
--- a/www/docs/en/dev/config_ref/index.md
+++ b/www/docs/en/dev/config_ref/index.md
@@ -81,54 +81,53 @@ This example shows the default `config.xml` generated by the CLI's
id(string) | *Required: true* <br/> Specifies the app's reverse-domain identifier, and the `version` its full version number expressed in major/minor/patch notation.
version(string) | *Required: true* <br/> Full version number expressed in major/minor/patch notation.
versionCode(string) | *Required: false* <br/> **Platforms supported: Android** <br/> Alternative version for Android.
- CFBundleVersion(string) | *Required: false* <br/> **Platforms supported: **iOS** <br/> Alternative version for iOS.
+ CFBundleVersion(string) | *Required: false* <br/> **Platforms supported: iOS** <br/> Alternative version for iOS.
packageVersion(string) | *Required: false* <br/> **Platforms supported: Windows** <br/> Alternative version for Windows.
xmlns(string) | *Required: true* <br/> namespace for the config.xml document.
xmlns:cdv(string) | *Required: true* <br/> namespace prefix.
-Examples:
-```
-<widget id="io.cordova.hellocordova">
-</widget>
+ Examples:
-<widget version="0.0.1">
-</widget>
+ <widget id="io.cordova.hellocordova">
+ </widget>
-<!-- Android -->
-<widget versionCode="0.1.3">
-</widget>
+ <widget version="0.0.1">
+ </widget>
-<!-- iOS -->
-<widget CFBundleVersion="0.1.3">
-</widget>
+ <!-- Android -->
+ <widget versionCode="0.1.3">
+ </widget>
-<!-- Windows -->
-<widget packageVersion="0.1.3">
-</widget>
+ <!-- iOS -->
+ <widget CFBundleVersion="0.1.3">
+ </widget>
+
+ <!-- Windows -->
+ <widget packageVersion="0.1.3">
+ </widget>
+
+ <widget xmlns="http://www.w3.org/ns/widgets">
+ </widget>
-<widget xmlns="http://www.w3.org/ns/widgets">
-</widget>
-```
## name
Specifies the app's formal name, as it appears on the device's home screen and within app-store interfaces.
- Example:
- ```
+ Example:
+
<widget ...>
<name>HelloCordova</name>
</widget>
- ```
## description
Specifies metadata that may appear within app-store listings.
- Example:
- ```
+ Example:
+
<widget ...>
<description>A sample Apache Cordova application</description>
</widget>
- ```
+
## author
Specifies contact information that may appear within app-store lisitngs.
@@ -138,12 +137,12 @@ Examples:
email(string) | *Required: true <br/>* Email of the author.
href(string) | *Required: true <br/>* Website of the author.
- Example:
- ```
+ Examples:
+
<widget ...>
<author email="dev@cordova.apache.org" href="http://cordova.io"></author>
</widget>
- ```
+
## content
Optional.
@@ -155,12 +154,12 @@ Examples:
src(string) | *Required: true <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.
- Example:
- ```
+ Example:
+
<widget ...>
<content src="startPage.html"></content>
</widget>
- ```
+
## 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.
@@ -172,8 +171,8 @@ Examples:
The default value shown above allows it to access any server.
See the Domain [Whitelist Guide](../guide/appdev/whitelist/index.html) for details.
- Example:
- ```
+ Examples:
+
<widget ...>
<access origin="*"></content>
</widget>
@@ -182,197 +181,85 @@ Examples:
<access origin="http://google.com"></content>
</widget>
- ```
## preference
Sets various optinos as pairs of name/value attributes. Each preference's name is case-insensitive. Many preferences are unique to specific platforms,
- as listed
-
-
-
-=================================
-The following configuration elements appear in the top-level
-`config.xml` file, and are supported across all supported Cordova
-platforms:
-
-- The `<widget>` element's `id` attribute provides the app's
- reverse-domain identifier, and the `version` its full version number
- expressed in major/minor/patch notation.
-
- The widget tag can also have attributes that specify alternative versions,
- namely `versionCode` for Android, `CFBundleVersion` for iOS, and
- `packageVersion` for Windows. See the Additional Versioning section below
- for details.
-
-- The `<name>` element specifies the app's formal name, as it appears
- on the device's home screen and within app-store interfaces.
-
-- The `<description>` and `<author>` elements specify metadata and
- contact information that may appear within app-store listings.
-
-- The optional `<content>` element 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.
-
-- `<access>` elements define 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/whitelist/index.html) for details.
-
-- The `<preference>` tag sets various options as pairs of
- `name`/`value` attributes. Each preference's `name` is
- case-insensitive. Many preferences are unique to specific
- platforms, as listed at the top of this page. The following sections
- detail preferences that apply to more than one platform.
-
-### Additional Versioning
-
-Android, iOS, and Windows support a second version string (or number) in
-addition to the one visible in app stores:
-
-- [versionCode](http://developer.android.com/tools/publishing/versioning.html)
- for Android
-- [CFBundleVersion](http://stackoverflow.com/questions/4933093/cfbundleversion-in-the-info-plist-upload-error)
- for iOS
-- [packageVersion](https://msdn.microsoft.com/en-us/library/windows/apps/br211441.aspx)
- for Windows
+ and will be indicated as such.
+
+ Attributes (type) | Description
+ ----------------- | ------------
+ DisallowOverscroll(boolean) | *Default: false* <br/> **Platforms supported: iOS, Android** <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/>
+ FullScreen(boolean) | *Default: false* <br/> Allows you to hide the status bar at the top of the screen.
+ BackgroundColor(string) | *Required: false* <br/> **Platforms supported: Android, BlackBerry** <br/> Supports a four-byte hex value, with the first byte representing the alpha channel, and standard RGB values for the following three bytes.
+ HideKeyboardFormAccessoryBar(boolean) | *Default: false* <br/> **Platforms supported: BlackBerry** <br/> set to true to hide the additional toolbar that appears above the keyboard, helping users navigate from one form input to another.
+ Orientation (string) | *Default: default* <br/> Allowed values: default, landscape, portait <br/> Allows you to lock orientation and prevent the interface from rotating in response to changes in orientation. <br/> **NOTE:** The default value means Cordova will strip the orientation preference entry from the platform's manifest/configuration file allowing the platform to fallback to its default behavior. For iOS, to specify both portrait & landscape mode you would use the platform specific value 'all'.
-Below is an example that explicitly sets these properties:
+ Examples:
- <widget id="io.cordova.hellocordova"
- version="0.0.1"
- android-versionCode="7"
- ios-CFBundleVersion="3.3.3"
- windows-packageVersion="1.0.1.2">
+ <preference name="DisallowOverscroll" value="true"/>
+ <preference name="Fullscreen" value="true" />
+ <preference name="BackgroundColor" value="0xff0000ff"/>
+ <preference name="HideKeyboardFormAccessoryBar" value="true"/>
+ <preference name="Orientation" value="landscape" />
-If alternative version is not specified, the following
-defaults will be used:
+
+## 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 specify each feature. See
+ the [Plugin Development Guide](../guide/hybrid/plugins/index.html) for more information on plugins.
- // assuming version = MAJOR.MINOR.PATCH-whatever
- versionCode = PATCH + MINOR * 100 + MAJOR * 10000
- CFBundleVersion = "MAJOR.MINOR.PATCH"
- packageVersion = "MAJOR.MINOR.PATCH.0"
+ Attributes (type) | Description
+ ----------------- | ------------
+ name(string) | *Required: true <br/>* The name of the plugin to enable.
-## Global Preferences
-The following global preferences apply to all platforms:
+### param
+ Used to specify what 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) | Description
+ ----------------- | ------------
+ name(string) | *Required: true* <br/> Allowed values: android-package, ios-package, onload. <br/> **Platforms supported: iOS, Android** <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) | *Required: true* <br/> **Platforms supported: iOS, Android** <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:
+
+ <!-- Here is how to specify the Device API for Android projects -->
+ <feature name="Device">
+ <param name="android-package" value="org.apache.cordova.device.Device" />
+ </feature>
+
+ <!-- Here's how the element appears for iOS projects -->
+ <feature name="Device">
+ <param name="ios-package" value="CDVDevice" />
+ <param name="onload" value="true" />
+ </feature>
-- `Fullscreen` allows you to hide the status bar at the top of the
- screen. The default value is `false`. Example:
+## 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) | Description
+ ----------------- | ------------
+ name(string) | *Required: true* <br/> The platform whose preferences are being defined.
+
+ Examples:
+
+ <platform name="android">
<preference name="Fullscreen" value="true" />
-
-## Multi-Platform Preferences
-
-The following preferences apply to more than one platform, but not to
-all of them:
-
-- `DisallowOverscroll` (boolean, defaults to `false`): set to `true`
- if you don't want the interface to display any feedback when users
- scroll past the beginning or end of content.
-
- <preference name="DisallowOverscroll" value="true"/>
-
- Applies to Android and iOS. 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.
-
-- `BackgroundColor`: Set 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. This
- example specifies blue:
-
- <preference name="BackgroundColor" value="0xff0000ff"/>
-
- Windows Quirk: CSS Color names are also supported:
-
- ```
- <platform name="windows">
- <preference name="BackgroundColor" value="turquoise"/>
</platform>
- ```
- __NOTE__: `transparent` value will cause black/white background color in case of Dark/Light theme accordingly.
-
- Applies to Android and BlackBerry. Overrides CSS otherwise available
- across _all_ platforms, for example: `body{background-color:blue}`.
-
-- `HideKeyboardFormAccessoryBar` (boolean, defaults to `false`): set
- to `true` to hide the additional toolbar that appears above the
- keyboard, helping users navigate from one form input to another.
-
- <preference name="HideKeyboardFormAccessoryBar" value="true"/>
-
- Applies to BlackBerry.
-
-- `Orientation` (string, defaults to `default`): allows you to lock
- orientation and prevent the interface from rotating in response to
- changes in orientation. Possible values are `default`, `landscape`
- or `portrait`. Example:
-
- <preference name="Orientation" value="landscape" />
-
- Additionally, you can specify any platform-specific orientation value
- if you place the `<preference>` element within a `<platform>` element:
-
- <platform name="android">
- <preference name="Orientation" value="sensorLandscape" />
- </platform>
-
- Applies to Android, iOS, WP8, Amazon Fire OS and Firefox OS.
-
- __NOTE__: The `default` value means Cordova will strip the orientation
- preference entry from the platform's manifest/configuration file
- allowing the platform to fallback to its default behavior.
-
- For iOS, to specify both portrait & landscape mode you would use the platform specific value `all`:
-
- <platform name="ios">
- <preference name="Orientation" value="all" />
- </platform>
-
-## The _feature_ Element
-
-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. For example, here is how to specify the
-Device API for Android projects:
-
- <feature name="Device">
- <param name="android-package" value="org.apache.cordova.device.Device" />
- </feature>
-
-Here is how the element appears for iOS projects:
-
- <feature name="Device">
- <param name="ios-package" value="CDVDevice" />
- </feature>
-
-See the API Reference for details on how to specify each feature. See
-the [Plugin Development Guide](../guide/hybrid/plugins/index.html) for more information on plugins.
-
-
-## The _platform_ Element
-
-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. For example, here is how to specify that only android should use the
-Fullscreen preference:
-
- <platform name="android">
- <preference name="Fullscreen" value="true" />
- </platform>
-
-## The _hook_ Element
-
-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.
+## 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) | Description
+ ----------------- | ------------
+ type(string) | *Required: true* <br/> Specifies the action during which the custom script is to be called.
+ src(string) | *Required: true* <br/> Specifies the location of the script to be called when a specific action occurs.
+
+ Examples:
+
<hook type="after_plugin_install" src="scripts/afterPluginInstall.js" />
+
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org