You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by mw...@apache.org on 2013/09/13 20:10:47 UTC
[03/17] docs commit: stage PGBuild content for platforms' config.xml
stage PGBuild content for platforms' config.xml
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/0820ebcf
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/0820ebcf
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/0820ebcf
Branch: refs/heads/master
Commit: 0820ebcff070fa4f97089936463420b5de55082f
Parents: 6e61648
Author: Mike Sierra <ms...@adobe.com>
Authored: Thu Sep 12 14:17:11 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Fri Sep 13 11:10:30 2013 -0700
----------------------------------------------------------------------
docs/en/edge/config_ref/index.md | 298 +++++++++++++++++++
.../file/localfilesystem/localfilesystem.md | 1 -
docs/en/edge/guide/platforms/android/config.md | 59 ++++
.../edge/guide/platforms/blackberry/config.md | 17 ++
docs/en/edge/guide/platforms/ios/config.md | 117 +++++++-
5 files changed, 489 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0820ebcf/docs/en/edge/config_ref/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/config_ref/index.md b/docs/en/edge/config_ref/index.md
index e65bdf6..49849e4 100644
--- a/docs/en/edge/config_ref/index.md
+++ b/docs/en/edge/config_ref/index.md
@@ -154,3 +154,301 @@ Here is how the element appears for iOS projects:
See the API Reference for details on how to access each feature. See
the Plugin Development Guide for more information about plugins.
+
+<!-- !!!
+
+ # Using config.xml
+
+Apps built using Adobe® PhoneGap™ Build can be set up either through
+our web interface, or by using a `config.xml`. The `config.xml` file,
+as specified in the [W3C widget
+specification](http://www.w3.org/TR/widgets/), allows developers to
+easily specify metadata about their applications. You can see a sample
+`config.xml` with our [PhoneGap
+Start](https://github.com/phonegap/phonegap-start/blob/master/www/config.xml)
+application.
+
+One thing to note: please ensure that your `config.xml` file is at the
+top level of your application (the same level as your `index.html`
+file). Otherwise it will not be loaded correctly.
+
+We're continually adding features to cour `config.xml` support, to
+give PhoneGap Build developers more power to customize their apps. If
+there are any specific features you'd like to see support for, [please
+let us
+know](http://getsatisfaction.com/nitobi/products/nitobi_phonegap_build).
+
+ ## Other Useful Elements
+
+ ### Icon Support
+
+* `<icon>`: You can have zero or more of these elements present in
+ your `config.xml`. If you do not specify a icon then the PhoneGap
+ logo will be used as your application's icon.
+
+ * `src`: (required) specifies the location of the image file,
+ relative to your `www` directory
+
+ * `width`: (optional) but recommended to include, width in pixels
+
+ * `height`: (optional) but recommended to include, height in pixels
+
+ #### Usage and Additional Information:
+
+Unless otherwise specified in a config.xml, each platform will try to
+use the default `icon.png` during compilation. To define platform
+specific icons please use the guide provided below.
+
+Icon files should be the file formats specified in the examples below,
+other file types are not guaranteed to work across platforms.
+
+ #### Default
+
+The default icon must be named `icon.png` and must reside in the root
+of your application folder.
+
+ <icon src="icon.png" />
+
+ #### iOS
+
+We support classic, retina, iPad displays (and retina iPad displays in
+PhoneGap 2.5.0+). The following will define icons for each specific
+screen type.
+
+ <icon src="icons/ios/icon.png" gap:platform="ios" width="57" height="57" />
+ <icon src="icons/ios/icon-72.png" gap:platform="ios" width="72" height="72" />
+ <icon src="icons/ios/icon_at_2x.png" gap:platform="ios" width="114" height="114" />
+
+ <!-- retina iPad support: PhoneGap 2.5.0+ only -->
+ <icon src="icons/ios/icon-72_at_2x.png" gap:platform="ios" width="144" height="144" />
+
+ #### Android
+
+We support ldpi, mdpi, hdpi, and xhdpi displays; the following will
+define icons for each specific screen type.
+
+ <icon src="icons/android/ldpi.png" gap:platform="android" gap:density="ldpi" />
+ <icon src="icons/android/mdpi.png" gap:platform="android" gap:density="mdpi" />
+ <icon src="icons/android/hdpi.png" gap:platform="android" gap:density="hdpi" />
+ <icon src="icons/android/xhdpi.png" gap:platform="android" gap:density="xhdpi" />
+
+ #### BlackBerry
+
+BlackBerry icons __must be smaller__ then 16kb. BlackBerry also
+defines an optional hover state; this state allows for a separate icon
+to be displayed when a user uses the trackpad to roll over your icon
+image. By default the non-hover icon will be used as the hover state.
+
+ <icon src="icons/bb/icon.png" gap:platform="blackberry" />
+ <icon src="icons/bb/icon_hover.png" gap:platform="blackberry" gap:state="hover"/>
+
+ #### Windows Phone
+
+We support two icons for Windows Phone, a regular icon and a tile
+image.
+
+ <icon src="icons/winphone/icon.png" gap:platform="winphone" />
+ <icon src="icons/winphone/tileicon.png" gap:platform="winphone" gap:role="background" />
+
+ #### WebOS
+
+WebOs supports a default icon and a mini icon which can be used for
+notifications.
+
+ <icon src="icons/webos/icon.png" gap:platform="webos" />
+ <icon src="icons/webos/miniicon.png" gap:platform="webos" gap:role="mini" />
+
+ ### Splash Screens
+
+You can have zero or more of these elements present in your
+`config.xml`. This element can have `src`, `gap:platform`, `width` and
+`height` attributes, just like the `<icon>` element above. Like icon
+files, your splash screens should be saved as `png` files.
+
+ <gap:splash src="splash/ios/Default-568h@2x~iphone.png" gap:platform="ios" width="320" height="480" />
+
+ #### Usage and Additional Information:
+
+Unless otherwise specified in a config.xml, each platform will try to
+use the default `splash.png` during compilation. To define platform
+specific splash screens please use the guide provided below.
+
+Splash files should be the file formats specified in the examples
+below. Any other file type is not guaranteed to work across platforms.
+
+ ##### Warning:
+
+If you do not supply the `gap:platform` attribute, the referenced
+image will be copied to ALL platforms, increasing the size of their
+application packages.
+
+ #### Default
+
+The default splash must be named `splash.png` and must reside in the
+root of your application folder.
+
+ <gap:splash src="splash.png" />
+
+ #### iOS
+
+We support classic, retina, iPhone 5 and iPad displays; the following
+will define splash screens for each of those. Standard iPads have two
+different splash screens, portrait, landscape. Retina iPads have two
+additional splash screens, retina portrait and retina landscape
+(PhoneGap 2.5.0+ only).
+
+ <gap:splash src="splash/ios/Default.png" gap:platform="ios" width="320" height="480" />
+ <gap:splash src="splash/ios/Default_at_2x.png" gap:platform="ios" width="640" height="960" />
+ <gap:splash src="splash/ios/Default_iphone5.png" gap:platform="ios" width="640" height="1136" />
+ <gap:splash src="splash/ios/Default-Landscape.png" gap:platform="ios" width="1024" height="748" />
+ <gap:splash src="splash/ios/Default-Portrait.png" gap:platform="ios" width="768" height="1004" />
+
+ <!-- retina iPad support: PhoneGap 2.5.0+ only -->
+ <gap:splash src="splash/ios/Default-Landscape_at_2x.png" gap:platform="ios" width="2048" height="1496" />
+ <gap:splash src="splash/ios/Default-Portrait_at_2x.png" gap:platform="ios" width="1536" height="2008" />
+
+ #### Android
+
+We support ldpi, mdpi, hdpi and xhdpi displays; the following will
+define splash screens for each specific screen type.
+
+ <gap:splash src="splash/android/ldpi.png" gap:platform="android" gap:density="ldpi" />
+ <gap:splash src="splash/android/mdpi.png" gap:platform="android" gap:density="mdpi" />
+ <gap:splash src="splash/android/hdpi.png" gap:platform="android" gap:density="hdpi" />
+ <gap:splash src="splash/android/xhdpi.png" gap:platform="android" gap:density="xhdpi" />
+
+ #### BlackBerry
+
+BlackBerry supports a single splash image and can be defined as below.
+
+ <gap:splash src="splash/bb/splash.png" gap:platform="blackberry" />
+
+ #### Windows Phone
+
+Windows Phone supports a single splash image and can be defined as
+below. Unlike the other supported platforms, Windows Phone splash
+screen should be in `jpg` format
+
+ <gap:splash src="splash/winphone/splash.jpg" gap:platform="winphone" />
+
+ ### Custom URL Schemes
+
+iOS Only. Allows registration of [custom URL
+schemes](https://developer.apple.com/library/ios/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/AdvancedAppTricks/AdvancedAppTricks.html#//apple_ref/doc/uid/TP40007072-CH7-SW50).
+
+ <gap:url-scheme name="com.acme.myscheme" role="None">
+ <scheme>pgbr</scheme>
+ <scheme>pgbw</scheme>
+ </gap:url-scheme>
+
+* multiple `gap:url-scheme` elements can be present.
+
+* `name`, optional, defaults to the application bundle id. This has to
+ be unique. If a duplicate is found the build will fail.
+
+* `role` must be `Editor`, `Viewer`, `Shell` or `None`, optional,
+ defaults to `None`.
+
+* at least one `scheme` must be present.
+
+ ### Features
+
+* `<feature>`: the feature element can be used to specify which
+features your application is using. If you specify features of the
+PhoneGap API, those will be expanded to the appropriate permissions
+for you application.
+
+ #### Custom Debug Server
+
+The `debug-server` feature allows you to use a custom Weinre instance
+for your application. By default PhoneGap Build uses
+`http://debug.build.phonegap.com` however this can be changed by
+adding the following to your `config.xml`.
+
+ <feature name="debug-server" required="true">
+ <param name="domain" value="http://debug.custom.com"/>
+ <param name="key" value="some_unique_key"/>
+ </feature>
+
+Don't forget to change the domain and key to the appropriate values.
+
+ #### API Features
+
+Currently supported through this interface are the following feature names:
+
+* `http://api.phonegap.com/1.0/battery`
+
+ * maps to `android:BROADCAST_STICKY` permission
+
+* `http://api.phonegap.com/1.0/camera`
+
+ * maps to `android:CAMERA`, `winphone:ID_CAP_ISV_CAMERA`, and
+ `winphone:ID_HW_FRONTCAMERA` permissions
+
+* `http://api.phonegap.com/1.0/contacts`
+
+ * maps to `android:READ_CONTACTS`, `android:WRITE_CONTACTS`,
+ `android:GET_ACCOUNTS`, and `winphone:ID_CAP_CONTACTS` permissions
+
+* `http://api.phonegap.com/1.0/file`
+
+ * maps to `WRITE_EXTERNAL_STORAGE` permission
+
+* `http://api.phonegap.com/1.0/geolocation`
+
+ * maps to `android:ACCESS_COARSE_LOCATION`,
+ `android:ACCESS_FINE_LOCATION`,
+ `android:ACCESS_LOCATION_EXTRA_COMMANDS`, and
+ `winphone:ID_CAP_LOCATION` permissions
+
+* `http://api.phonegap.com/1.0/media`
+
+ * maps to `android:RECORD_AUDIO`, `android:RECORD_VIDEO`,
+ `android:MODIFY_AUDIO_SETTINGS`, and `winphone:ID_CAP_MICROPHONE`
+ permissions
+
+* `http://api.phonegap.com/1.0/network`
+
+ * maps to `android:ACCESS_NETWORK_STATE`, and
+ `winphone:ID_CAP_NETWORKING` permissions
+
+* `http://api.phonegap.com/1.0/notification`
+
+ * maps to `VIBRATE` permission
+
+* `http://api.phonegap.com/1.0/device`
+
+ * maps to `winphone:ID_CAP_IDENTITY_DEVICE` permission
+
+ #### Usage
+
+ <!-- If you do not want any permissions to be added to your app, add the
+ following tag to your config.xml; you will still have the INTERNET
+ permission on your app, which PhoneGap requires. -->
+ <preference name="permissions" value="none"/>
+
+ <!-- to enable individual permissions use the following examples -->
+ <feature name="http://api.phonegap.com/1.0/battery"/>
+ <feature name="http://api.phonegap.com/1.0/camera"/>
+ <feature name="http://api.phonegap.com/1.0/contacts"/>
+ <feature name="http://api.phonegap.com/1.0/file"/>
+ <feature name="http://api.phonegap.com/1.0/geolocation"/>
+ <feature name="http://api.phonegap.com/1.0/media"/>
+ <feature name="http://api.phonegap.com/1.0/network"/>
+ <feature name="http://api.phonegap.com/1.0/notification"/>
+
+ ### Plugins
+
+* `<gap:plugin>`: specifies a PhoneGap plugin for PhoneGap Build to
+ include in your generated apps.
+
+At present, to include a plugin, you will to ensure:
+
+* the plugin is supported by PhoneGap Build; and
+
+* any JavaScript script tags are present in your `index.html` file.
+
+More details, including a list of available plugins, are in our
+[plugins documentation](/docs/plugins).
+
+-->
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0820ebcf/docs/en/edge/cordova/file/localfilesystem/localfilesystem.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/cordova/file/localfilesystem/localfilesystem.md b/docs/en/edge/cordova/file/localfilesystem/localfilesystem.md
index 438ae03..9de9110 100644
--- a/docs/en/edge/cordova/file/localfilesystem/localfilesystem.md
+++ b/docs/en/edge/cordova/file/localfilesystem/localfilesystem.md
@@ -103,7 +103,6 @@ The `LocalFileSystem` object methods are defined on the `window` object.
</body>
</html>
-
# requestFileSystem
> Request a file system in which to store application data.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0820ebcf/docs/en/edge/guide/platforms/android/config.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/android/config.md b/docs/en/edge/guide/platforms/android/config.md
index 9b42ee0..1d67c7c 100644
--- a/docs/en/edge/guide/platforms/android/config.md
+++ b/docs/en/edge/guide/platforms/android/config.md
@@ -63,3 +63,62 @@ breaking existing apps. The available preferences are:
Android supports using `<feature>` as analogues to `<plugin>` elements.
+<!--
+
+ ### Android Specific
+
+ #### Minimum and Maximum SDK Version
+
+* `android-minSdkVersion` and/or `android-maxSdkVersion`, with integer
+ values
+
+ * minSdkVersion example: `<preference name="android-minSdkVersion" value="10" />`
+
+ * maxSdkVersion example: `<preference name="android-maxSdkVersion" value="15" />`
+
+ * corresponds to the `usesSdk` attributes in the
+ `AndroidManifest.xml` file - more details are in [the Android
+ documentation](http://developer.android.com/guide/topics/manifest/uses-sdk-element.html)
+
+ * minSdkVersion defaults to 7 (Android 2.1); maxSdkVersion is unset
+ by default
+
+ #### Install Location
+
+* `android-installLocation` with values `internalOnly`, `auto` or `preferExternal`
+
+ * example: `<preference name="android-installLocation" value="auto"
+ />`
+
+ * where an app can be installed - defaults to `internalOnly` (as the
+ Android SDK)
+
+ * `auto` or `preferExternal` allow the app to be installed on an SD
+ card - this can lead to unexpected behavior
+
+ * more details available in [the Android
+ documentation](http://developer.android.com/guide/appendix/install-location.html)
+
+ #### Splash Screen Duration
+
+ * `splash-screen-duration` with a value in milliseconds
+
+ * defaults to 5000 (5 seconds)
+
+ * example: `<preference name="splash-screen-duration" value="10000"
+ />`
+
+ * for auto-hide behaviour call `navigator.splashscreen.hide();` in
+ the device-ready method
+
+ * supported on PhoneGap 2.1.0 and above
+
+ #### Load URL timeout
+
+ * `load-url-timeout` with a value in milliseconds
+
+ * defaults to 20000 (20 seconds)
+
+ * example: `<preference name="load-url-timeout" value="15000" />`
+
+-->
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0820ebcf/docs/en/edge/guide/platforms/blackberry/config.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/blackberry/config.md b/docs/en/edge/guide/platforms/blackberry/config.md
index 399b553..a07195e 100644
--- a/docs/en/edge/guide/platforms/blackberry/config.md
+++ b/docs/en/edge/guide/platforms/blackberry/config.md
@@ -24,3 +24,20 @@ BlackBerry fully supports the
as well as proprietary RIM extensions. Please see the full
[BlackBerry WebWorks documentation regarding config.xml](https://developer.blackberry.com/html5/documentation/working_with_config_xml_file_1866970_11.html)
for details.
+
+<!--
+
+ #### Disable Cursor
+
+* `disable-cursor` with values `true` or `false`
+
+ * example: `<preference name="disable-cursor" value="true" />`
+
+ * prevents a mouse-icon/cursor from being displayed on the app -
+ desugars to `<rim:navigation />`. See [the BlackBerry
+ documentation](https://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/rim_navigation_element_1582456_11.html)
+ for more details
+
+ * default is _false_
+
+-->
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0820ebcf/docs/en/edge/guide/platforms/ios/config.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/ios/config.md b/docs/en/edge/guide/platforms/ios/config.md
index d3f6e38..cfc5459 100644
--- a/docs/en/edge/guide/platforms/ios/config.md
+++ b/docs/en/edge/guide/platforms/ios/config.md
@@ -21,8 +21,8 @@ license: Licensed to the Apache Software Foundation (ASF) under one
The `config.xml` settings file controls various Cordova settings.
This is application wide, and not set per CDVViewController instance.
-The `config.xml` file is located in your `<project folder>/<appname>`
-directory.
+The `config.xml` file is located within the `<project
+folder>/<appname>` directory.
## `<preference>`
@@ -91,3 +91,116 @@ existing apps. The available preferences are:
applies to apps that position their elements relative to the bottom
of the WebView. This is the default behaviour on Android, and makes
a lot of sense when building apps as opposed to webpages.
+
+<!--
+
+ #### Target a Specific Device
+
+* `target-device` with possible values `handset`, `tablet`, or
+ `universal`
+
+ * example: `<preference name="target-device" value="universal" />`
+
+ * please note that this currently only applies to iOS builds; by
+ default all builds are universal
+
+ #### WebView Bounce
+
+* `webviewbounce` with values `true` or `false`
+
+ * example: `<preference name="webviewbounce" value="false" />`
+
+ * controls whether the screen "bounces" when scrolled beyond the top
+ or bottom on iOS. By default, the bounce is _on_
+
+ #### Prerendered Icon
+
+* `prerendered-icon` with values `true` or `false`
+
+ * example: `<preference name="prerendered-icon" value="true" />`
+
+ * if icon is prerendered, iOS will not apply it's gloss to the app's
+ icon on the user's home screen
+
+ * default is _false_
+
+ #### Open all links in WebView
+
+* __Deprecated__ -- use <a
+ href="http://docs.phonegap.com/en/2.9.0/cordova_inappbrowser_inappbrowser.md.html#InAppBrowser">InAppBrowser</a>
+ with target equal to '_self' (webview), '_blank' (InAppBrowser),
+ '_system' (system web browser)
+
+* `stay-in-webview` with values `true` or `false`
+
+ * example: `<preference name="stay-in-webview" value="true" />`
+
+ * if set to true, all links (even with target set to blank) will
+ open in the app's webview
+
+ * only use this preference if you want pages from your server to
+ take over your entire app
+
+ * default is _false_
+
+ #### Status Bar Style
+
+* `ios-statusbarstyle` with values `default`, `black-opaque` or
+ `black-translucent`
+
+ * example: `<preference name="ios-statusbarstyle" value="black-opaque" />`
+
+ * default is a grey status bar, `black-opaque` will appear black
+
+ * although `black-translucent` is supported, the PhoneGap webview
+ does not extend beneath the status bar, so it will appear
+ identical to `black-opaque` once your app is running
+
+ #### Detect Data Types
+
+* `detect-data-types` with values `true` or `false`
+
+ * example: `<preference name="detect-data-types" value="false" />`
+
+ * controls whether certain data types (such as phone numbers and
+ dates) are automatically turned into links by the system. Defaults
+ to "true" (as does the system web view)
+
+ * supported on PhoneGap 2.0.0 and above
+
+ #### Exit On Suspend
+
+* `exit-on-suspend` with values `true` or `false`
+
+ * example: `<preference name="exit-on-suspend" value="true" />`
+
+ * if set to true, app will terminate when suspended, for example
+ when home button is pressed
+
+ * default is _false_
+
+ #### Show Splash Screen Spinner
+
+* `show-splash-screen-spinner` with values `true` or `false`
+
+ * example: `<preference name="show-splash-screen-spinner"
+ value="false" />`
+
+ * if set to false, the spinner won't appear on the splash screen
+ during app loading
+
+ * default is _true_
+
+ #### Auto-Hide Splash Screen
+
+* `auto-hide-splash-screen` with values `true` or `false`
+
+ * example: `<preference name="auto-hide-splash-screen" value="false"
+ />`
+
+ * if set to false, the splash screen must be hidden using a
+ JavaScript API
+
+ * default is _true_
+
+-->
\ No newline at end of file