You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by st...@apache.org on 2016/03/23 08:07:29 UTC
[4/5] docs commit: updated 6.x docs from latest
updated 6.x docs from latest
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/3830f736
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/3830f736
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/3830f736
Branch: refs/heads/master
Commit: 3830f7366a67889b67d2f852940a190d0646e1df
Parents: 3bdf0c5
Author: Steve Gill <st...@gmail.com>
Authored: Tue Mar 22 23:56:41 2016 -0700
Committer: Steve Gill <st...@gmail.com>
Committed: Tue Mar 22 23:56:41 2016 -0700
----------------------------------------------------------------------
www/docs/en/6.x/guide/cli/index.md | 2 +-
www/docs/en/6.x/guide/hybrid/plugins/index.md | 101 ++++++++++++++
www/docs/en/6.x/reference/cordova-cli/index.md | 15 ++-
.../cordova-plugin-splashscreen/index.md | 130 ++++++++++++++-----
4 files changed, 210 insertions(+), 38 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/3830f736/www/docs/en/6.x/guide/cli/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/guide/cli/index.md b/www/docs/en/6.x/guide/cli/index.md
index 022a497..0d40281 100644
--- a/www/docs/en/6.x/guide/cli/index.md
+++ b/www/docs/en/6.x/guide/cli/index.md
@@ -119,7 +119,7 @@ applications for building, or when plugins are re-installed.
###See Also
- [Cordova platform command reference documentation][cdv_platform]
-##Install pre-requrisites for building
+##Install pre-requisites for building
To build and run apps, you need to install SDKs for each platform you wish to target. Alternatively, if you are using browser for development you can use `browser` platform which does not require any platform SDKs.
To check if you satisfy requirements for building the platform:
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/3830f736/www/docs/en/6.x/guide/hybrid/plugins/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/guide/hybrid/plugins/index.md b/www/docs/en/6.x/guide/hybrid/plugins/index.md
index e1f3cd8..ec6191f 100644
--- a/www/docs/en/6.x/guide/hybrid/plugins/index.md
+++ b/www/docs/en/6.x/guide/hybrid/plugins/index.md
@@ -245,4 +245,105 @@ For example, for a plugin that supports android, iOS & Windows, the keywords in
For more detailed example of a package.json, review the [package.json file of cordova-plugin-device](https://github.com/apache/cordova-plugin-device/blob/master/package.json).
+### Specifying Cordova Dependencies
+
+**Cordova 6.1.0** added support for specifying the Cordova-related dependencies of a plugin
+as part of the plugin's `package.json` file. Plugins may list the dependencies for multiple
+releases so as to provide guidance to the Cordova CLI when it is selecting the version of a
+plugin to fetch from npm. The CLI will choose the latest release of a plugin that is
+compatible with the local project's installed platforms and plugins as well as the
+the local Cordova CLI version. If no releases of the plugin are compatible, the CLI will warn
+the user about the failed requirements and fall back to the old behavior of fetching the
+latest release.
+
+This feature is intended to eventually replace the [engines element](../../../plugin_ref/spec.html#engines-and-engine) in plugin.xml.
+Listing dependencies is a good way to ensure that your plugin will not appear broken or cause
+build errors when fetched from npm. If the latest release of the plugin is not compatible with
+a project, the CLI will give the app developer a list of unmet project requirements so that
+they are aware of incompatibilites and can update their project to support your plugin. This
+allows your plugin to respond to breaking changes without fear of confusing devlopers who
+are building against old platforms and plugins.
+
+To specify Cordova-related dependencies for a plugin, alter the `engines` element in
+`package.json` to include a `cordovaDependencies` object using the following
+structure:
+
+```javascript
+engines: {
+ cordovaDependencies: {
+ PLUGIN_VERSION: {
+ DEPENDENCY: SEMVER_RANGE,
+ DEPENDENCY: SEMVER_RANGE,
+ ...
+ },
+ ...
+ }
+}
+```
+
+* `PLUGIN_VERSION` specifies a version of your plugin. It should adhere the syntax for a single version as defined by [npm's semver package][npm-semver] or an upper bound (see [below](#upper-bounds))
+* `DEPENDENCY` may be one of the following:
+ * The Cordova CLI, `"cordova"`
+ * A Cordova platform (e.g. `"cordova-android"`, `"cordova-ios"`, `"cordova-windows"`, etc.)
+ * Another Cordova plugin (e.g. `"cordova-plugin-camera"`, etc.)
+* `SEMVER_RANGE` should adhere to the syntax for a range as defined by [npm's semver package][npm-semver]
+
+**NOTE:** A Cordova platform `DEPENDENCY` refers to the Cordova platform and not
+the OS (i.e. `cordova-android` rather than the Android OS)
+
+Your `cordovaDependencies` may list any number of `PLUGIN_VERSION` requirements
+and any number of `DEPENDENCY` constraints within them. Versions of your plugin
+that do not have their dependencies listed will be assumed to have the same
+dependency information as the highest `PLUGIN_VERSION` listed below them. For
+example, consider the following entry:
+
+```javascript
+engines: {
+ cordovaDependencies: {
+ "1.0.0": { "cordova-android": "<3.0.0"},
+ "2.1.0": { "cordova-android": ">4.0.0"}
+ }
+}
+```
+All plugin versions below the lowest entry (1.0.0 in this example) are assumed
+to have no dependencies. Any version of the plugin between 1.0.0 and 2.1.0 is
+assumed to have the same dependencies as version 1.0.0 (a cordova-android
+version less than 3.0.0). This lets you only update your `cordovaDependencies`
+information when there are breaking changes.
+
+#### Upper Bounds
+
+In addition to a single version, a `PLUGIN_VERSION` in `cordovaDependencies`
+may also specify an upper bound to amend entries for older releases
+of your plugin. This is useful when a breaking change occurs in a `DEPENDENCY`
+and a new constraint must be added for all older versions of a plugin that do
+not support it. These bounds should be written as, a `<` followed by a single
+[semver][npm-semver] version (**Not an arbitrary range!**). This will apply
+whatever `DEPENDENCY` values are given to all versions of the plugin below the
+specified version. For example, consider the following entry:
+
+```javascript
+engines: {
+ cordovaDependencies: {
+ "0.0.1": { "cordova-ios": ">1.0.0" },
+ "<1.0.0": { "cordova-ios": "<2.0.0" },
+ "<2.0.0": { "cordova-ios": "<5.0.0" }
+ }
+}
+```
+
+Here we specify one plugin version (0.0.1) and two upper bounds (<1.0.0 and <2.0.0)
+that constrain cordova-ios. The two upper bounds do not override the constraint
+of 0.0.1, they are combined via AND at evaluation time. When the CLI checks the
+cordova-ios version of the project, the constraint that will be evaluated for
+plugin version 0.0.1 will be the combination of these three:
+
+```
+ cordova-ios >1.0.0 AND cordova-ios <2.0.0 AND cordova-ios <5.0.0
+```
+
+Please note that the only `PLUGIN_VERSION` values allowed are single versions or
+upper bounds; no other semver ranges are supported.
+
[cdv_plugin]: ../../../reference/cordova-cli/index.html#cordova-plugin-command
+[npm-semver]: https://www.npmjs.com/package/semver
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/3830f736/www/docs/en/6.x/reference/cordova-cli/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/reference/cordova-cli/index.md b/www/docs/en/6.x/reference/cordova-cli/index.md
index 23d0abb..8fe7c38 100644
--- a/www/docs/en/6.x/reference/cordova-cli/index.md
+++ b/www/docs/en/6.x/reference/cordova-cli/index.md
@@ -73,11 +73,11 @@ These options apply to all cordova-cli commands.
## Platform-specific options
-Certain commands have options (`platformOpts`) that are specific to a particular platform. They can be provided to the cordova-cli with a '--' separator that stops the command parsing within the cordova-lib module and passes through rest of the options for platforms to parse.
+Certain commands have options (`platformOpts`) that are specific to a particular platform. They can be provided to the cordova-cli with a '--' separator that stops the command parsing within the cordova-lib module and passes through rest of the options for platforms to parse.
## Examples
- This example demonstrates how cordova-cli can be used to create a project with the `camera` plugin and run it for `android` platform. In particular, platform specific options like `--keystore` can be provided:
-
+
# Create a cordova project
cordova create myApp com.myCompany.myApp myApp
cd myApp
@@ -341,6 +341,16 @@ There are a number of ways to specify a plugin:
| commit-ish | Commit/tag/branch reference. If none is specified, 'master' is used
| subdir | Sub-directory to find plugin.xml for the specified plugin.
+### Algorithm for resolving plugins
+
+When adding a plugin to a project, the CLI will resolve the plugin
+based on the following criteria (listed in order of precedence):
+
+1. The `plugin-spec` given in the command (e.g. `cordova plugin add pluginID@version`)
+2. The `plugin-spec` saved in `config.xml` (i.e. if the plugin was previously added with `--save`)
+3. As of Cordova version 6.1, the latest plugin version published to npm that the current project can support (only applies to plugins that list their [Cordova dependencies] in their `package.json`)
+4. The latest plugin version published to npm
+
### Examples
- Add `cordova-plugin-camera` and `cordova-plugin-file` to the project and save it to `config.xml`. Use `../plugins` directory to search for the plugins.
@@ -587,3 +597,4 @@ cordova -h [command]
[Hooks guide]: http://cordova.apache.org/docs/en/latest/guide_appdev_hooks_index.md.html
[config.xml ref]: http://cordova.apache.org/docs/en/latest/config_ref/index.html
+[Cordova dependencies]: http://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html#specifying-project-requirements
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/3830f736/www/docs/en/6.x/reference/cordova-plugin-splashscreen/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/6.x/reference/cordova-plugin-splashscreen/index.md b/www/docs/en/6.x/reference/cordova-plugin-splashscreen/index.md
index db451ee..acda36c 100644
--- a/www/docs/en/6.x/reference/cordova-plugin-splashscreen/index.md
+++ b/www/docs/en/6.x/reference/cordova-plugin-splashscreen/index.md
@@ -30,7 +30,7 @@ plugin_version: master
# cordova-plugin-splashscreen
-This plugin displays and hides a splash screen during application launch.
+This plugin is required to work with splash screens. This plugin displays and hides a splash screen during application launch.
Report issues with this plugin on the [Apache Cordova issue tracker][Apache Cordova issue tracker].
@@ -53,34 +53,81 @@ Report issues with this plugin on the [Apache Cordova issue tracker][Apache Cord
- Windows
- Browser
+## Example Configuration
+In the top-level `config.xml` file (not the one in `platforms`), add configuration elements like those specified here.
+
+Please notice that the value of the "src" attribute is relative to the project directory and not to the www directory. You can name the source image whatever you like. The internal name in the app is determined by Cordova.
+
+```xml
+<platform name="android">
+ <!-- you can use any density that exists in the Android project -->
+ <splash src="res/screen/android/splash-land-hdpi.png" density="land-hdpi"/>
+ <splash src="res/screen/android/splash-land-ldpi.png" density="land-ldpi"/>
+ <splash src="res/screen/android/splash-land-mdpi.png" density="land-mdpi"/>
+ <splash src="res/screen/android/splash-land-xhdpi.png" density="land-xhdpi"/>
+
+ <splash src="res/screen/android/splash-port-hdpi.png" density="port-hdpi"/>
+ <splash src="res/screen/android/splash-port-ldpi.png" density="port-ldpi"/>
+ <splash src="res/screen/android/splash-port-mdpi.png" density="port-mdpi"/>
+ <splash src="res/screen/android/splash-port-xhdpi.png" density="port-xhdpi"/>
+</platform>
+
+<platform name="ios">
+ <!-- images are determined by width and height. The following are supported -->
+ <splash src="res/screen/ios/Default~iphone.png" width="320" height="480"/>
+ <splash src="res/screen/ios/Default@2x~iphone.png" width="640" height="960"/>
+ <splash src="res/screen/ios/Default-Portrait~ipad.png" width="768" height="1024"/>
+ <splash src="res/screen/ios/Default-Portrait@2x~ipad.png" width="1536" height="2048"/>
+ <splash src="res/screen/ios/Default-Landscape~ipad.png" width="1024" height="768"/>
+ <splash src="res/screen/ios/Default-Landscape@2x~ipad.png" width="2048" height="1536"/>
+ <splash src="res/screen/ios/Default-568h@2x~iphone.png" width="640" height="1136"/>
+ <splash src="res/screen/ios/Default-667h.png" width="750" height="1334"/>
+ <splash src="res/screen/ios/Default-736h.png" width="1242" height="2208"/>
+ <splash src="res/screen/ios/Default-Landscape-736h.png" width="2208" height="1242"/>
+</platform>
+
+<platform name="windows">
+ <!-- images are determined by width and height. The following are supported -->
+ <splash src="res/screen/windows/splashscreen.png" width="620" height="300"/>
+ <splash src="res/screen/windows/splashscreenphone.png" width="1152" height="1920"/>
+</platform>
+
+<platform name="blackberry10">
+ <!-- Add a rim:splash element for each resolution and locale you wish -->
+ <!-- http://developer.blackberry.com/html5/documentation/rim_splash_element.html -->
+ <rim:splash src="res/screen/blackberry/splashscreen.png"/>
+</platform>
+
+<preference name="SplashScreenDelay" value="10000" />
+```
+
## Preferences
#### config.xml
-- __SplashScreen__ (string). The resource name which is used for the displaying splash screen. Different platforms use values for this.
-
- <preference name="SplashScreen" value="resourcename" />
-
- __AutoHideSplashScreen__ (boolean, default to `true`). Indicates wherether hide splash screen automatically or not. Splash screen hidden after amount of time specified in the `SplashScreenDelay` preference.
- <preference name="AutoHideSplashScreen" value="true" />
+```xml
+ <preference name="AutoHideSplashScreen" value="true" />
+```
- __SplashScreenDelay__ (number, default to 3000). Amount of time in milliseconds to wait before automatically hide splash screen.
- <preference name="SplashScreenDelay" value="3000" />
-
+```xml
+ <preference name="SplashScreenDelay" value="3000" />
+```
### Android Quirks
In your `config.xml`, you need to add the following preferences:
- <preference name="SplashScreen" value="foo" />
- <preference name="SplashScreenDelay" value="3000" />
- <preference name="SplashMaintainAspectRatio" value="true|false" />
- <preference name="SplashShowOnlyFirstTime" value="true|false" />
+```xml
+<preference name="SplashScreenDelay" value="3000" />
+<preference name="SplashMaintainAspectRatio" value="true|false" />
+<preference name="SplashShowOnlyFirstTime" value="true|false" />
+```
-Where foo is the name of the splashscreen file, preferably a 9 patch file. Make sure to add your splashcreen files to your res/xml directory under the appropriate folders. The second parameter represents how long the splashscreen will appear in milliseconds. It defaults to 3000 ms. See [Icons and Splash Screens](http://cordova.apache.org/docs/en/edge/config_ref_images.md.html)
-for more information.
+The first parameter represents how long the splashscreen will appear in milliseconds. It defaults to 3000 ms.
"SplashMaintainAspectRatio" preference is optional. If set to true, splash screen drawable is not stretched to fit screen, but instead simply "covers" the screen, like CSS "background-size:cover". This is very useful when splash screen images cannot be distorted in any way, for example when they contain scenery or text. This setting works best with images that have large margins (safe areas) that can be safely cropped on screens with different aspect ratios.
@@ -92,29 +139,37 @@ The plugin reloads splash drawable whenever orientation changes, so you can spec
You can use the following preferences in your `config.xml`:
- <platform name="browser">
- <preference name="SplashScreen" value="/images/browser/splashscreen.jpg" /> <!-- defaults to "/img/logo.png" -->
- <preference name="SplashScreenDelay" value="3000" /> <!-- defaults to "3000" -->
- <preference name="SplashScreenBackgroundColor" value="green" /> <!-- defaults to "#464646" -->
- <preference name="ShowSplashScreen" value="false" /> <!-- defaults to "true" -->
- <preference name="SplashScreenWidth" value="600" /> <!-- defaults to "170" -->
- <preference name="SplashScreenHeight" value="300" /> <!-- defaults to "200" -->
- </platform>
+```xml
+<platform name="browser">
+ <preference name="SplashScreen" value="/images/browser/splashscreen.jpg" /> <!-- defaults to "/img/logo.png" -->
+ <preference name="SplashScreenDelay" value="3000" /> <!-- defaults to "3000" -->
+ <preference name="SplashScreenBackgroundColor" value="green" /> <!-- defaults to "#464646" -->
+ <preference name="ShowSplashScreen" value="false" /> <!-- defaults to "true" -->
+ <preference name="SplashScreenWidth" value="600" /> <!-- defaults to "170" -->
+ <preference name="SplashScreenHeight" value="300" /> <!-- defaults to "200" -->
+</platform>
+```
-__Note__: `SplashScreen` value should be absolute in order to work in a sub-page.
+__Note__: `SplashScreen` value should be absolute in order to work in a sub-page. The `SplashScreen` value is used only for the browser platform. The value will be ignored for other platforms.
### Android and iOS Quirks
+- In iOS, the splashscreen images are called launch images. These images are mandatory on iOS.
+
- `FadeSplashScreen` (boolean, defaults to `true`): Set to `false` to
prevent the splash screen from fading in and out when its display
state changes.
- <preference name="FadeSplashScreen" value="false"/>
+```xml
+ <preference name="FadeSplashScreen" value="false"/>
+```
- `FadeSplashScreenDuration` (float, defaults to `3000`): Specifies the
number of milliseconds for the splash screen fade effect to execute.
- <preference name="FadeSplashScreenDuration" value="3000"/>
+```xml
+ <preference name="FadeSplashScreenDuration" value="3000"/>
+```
Note also that this value used to be seconds, and not milliseconds, so values less than 30 will still be treated as seconds. ( Consider this a deprecated patch that will disapear in some future version. )
@@ -138,7 +193,9 @@ window.setTimeout(function () {
- `ShowSplashScreenSpinner` (boolean, defaults to `true`): Set to `false`
to hide the splash-screen spinner.
- <preference name="ShowSplashScreenSpinner" value="false"/>
+```xml
+ <preference name="ShowSplashScreenSpinner" value="false"/>
+```
## Methods
@@ -149,7 +206,9 @@ window.setTimeout(function () {
Dismiss the splash screen.
- navigator.splashscreen.hide();
+```js
+navigator.splashscreen.hide();
+```
### BlackBerry 10, WP8, iOS Quirk
@@ -158,16 +217,19 @@ The `config.xml` file's `AutoHideSplashScreen` setting must be
`false`. To delay hiding the splash screen for two seconds, add a
timer such as the following in the `deviceready` event handler:
- setTimeout(function() {
- navigator.splashscreen.hide();
- }, 2000);
+```js
+setTimeout(function() {
+ navigator.splashscreen.hide();
+}, 2000);
+```
## splashscreen.show
Displays the splash screen.
- navigator.splashscreen.show();
-
+```js
+navigator.splashscreen.show();
+```
Your application cannot call `navigator.splashscreen.show()` until the app has
started and the `deviceready` event has fired. But since typically the splash
@@ -175,9 +237,7 @@ screen is meant to be visible before your app has started, that would seem to
defeat the purpose of the splash screen. Providing some configuration in
`config.xml` will automatically `show` the splash screen immediately after your
app launch and before it has fully started and received the `deviceready`
-event. See [Icons and Splash Screens](http://cordova.apache.org/docs/en/edge/config_ref_images.md.html)
-for more information on doing this configuration. For this reason, it is
-unlikely you need to call `navigator.splashscreen.show()` to make the splash
+event. For this reason, it is unlikely you need to call `navigator.splashscreen.show()` to make the splash
screen visible for app startup.
[Apache Cordova issue tracker]: https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20Splashscreen%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org