cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mwbro...@apache.org
Subject [03/17] docs commit: stage PGBuild content for platforms' config.xml
Date Fri, 13 Sep 2013 18:10:47 GMT
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 <msierra@adobe.com>
Authored: Thu Sep 12 14:17:11 2013 -0400
Committer: Michael Brooks <michael@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


Mime
View raw message