http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/7e5cc869/docs/en/edge/guide/platforms/blackberry10/plugin.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/guide/platforms/blackberry10/plugin.md b/docs/en/edge/guide/platforms/blackberry10/plugin.md index aceb335..8e86ff8 100644 --- a/docs/en/edge/guide/platforms/blackberry10/plugin.md +++ b/docs/en/edge/guide/platforms/blackberry10/plugin.md @@ -27,7 +27,7 @@ This is a continuation of the Plugin Development Guide for Cordova. Once you hav }, "Echo", "echo", [str]); }; -A native BlackBerry 10 plugin for Cordova contains JavaScript code and may also contain native code. The Echo plugin example demonstrates how to invoke native functionality from JavaScript. The native and JavaScript code communicate with each other through a framework provided by JNEXT. Every plugin must also include a plugin.xml file. +A native BlackBerry 10 plugin for Cordova contains JavaScript code and may also contain native code. The Echo plugin example demonstrates how to invoke native functionality from JavaScript. The native and JavaScript code communicate with each other through a framework provided by JNEXT. Every plugin must also include a `plugin.xml` file. ## Creating the native part of your plugin ## @@ -35,10 +35,11 @@ To create the native portion of your plugin, open the BlackBerry 10 NDK IDE and The project created by the IDE contains sample code for a memory plugin. You may replace or modify these files to include your own functionality. -- ***name*_js.hpp**: C++ header for the JNEXT code. -- ***name*_js.cpp**: C++ code for JNEXT. +- `*name*_js.hpp`: C++ header for the JNEXT code. -The native interface for the JNEXT extension can be viewed in the plugin header file located in the public folder of your project. It also contains constants and utility functions that can be used in your native code. Your plugin must be derived from JSExt which is defined in plugin.h. That is, you must implement the following class: +- `*name*_js.cpp`: C++ code for JNEXT. + +The native interface for the JNEXT extension can be viewed in the plugin header file located in the public directory of your project. It also contains constants and utility functions that can be used in your native code. Your plugin must be derived from JSExt which is defined in plugin.h. That is, you must implement the following class: class JSExt { @@ -94,6 +95,7 @@ Now we implement these functions in echo_js.cpp. For the Echo example, we implem Your native plugin must also implement the following callback functions: - `extern char* onGetObjList( void );` + - `extern JSExt* onCreateObject( const string& strClassName, const string& strObjId );` The `onGetObjList` function returns a comma separated list of classes supported by JNEXT. JNEXT uses this function to determine the set of classes that JNEXT can instantiate. In our Echo plugin, we have the following in `echo_js.cpp`: @@ -116,11 +118,11 @@ The `onCreateObject ` function takes two parameters. The first parameter is the The JavaScript portion of your plugin must contain the following files: -- **client.js**: This is considered the client side and contains the API that a Cordova application can call. The API in client.js calls makes calls to index.js. The API in client.js also connects callback functions to the events that fire the callbacks. +- `client.js`: This is considered the client side and contains the API that a Cordova application can call. The API in `client.js` calls makes calls to `index.js`. The API in `client.js` also connects callback functions to the events that fire the callbacks. -- **index.js**: Cordova loads index.js and makes it accessible through the cordova.exec bridge. The client.js file makes calls to the API in the index.js file, which in turn makes call to JNEXT to communicate with the native side. +- `index.js`: Cordova loads `index.js` and makes it accessible through the cordova.exec bridge. The `client.js` file makes calls to the API in the `index.js` file, which in turn makes call to JNEXT to communicate with the native side. -The client and server side (client.js and index.js) interacts through the `Cordova.exec `function. So, in client.js you invoke the exec function and provide the necessary arguments. In the Echo plugin, we have the following in the client.js file: +The client and server side (`client.js` and `index.js`) interacts through the `Cordova.exec `function. So, in `client.js` you invoke the `exec` function and provide the necessary arguments. In the Echo plugin, we have the following in the `client.js` file: var service = "org.apache.cordova.blackberry.echo", exec = cordova.require("cordova/exec"); @@ -131,7 +133,7 @@ The client and server side (client.js and index.js) interacts through the `Cordo } }; -Now, index.js interacts with the native side using JNEXT. So you attach a constructor function named Echo to JNEXT. Within the constructor you perform the following key operations using the init function: +Now, `index.js` interacts with the native side using JNEXT. So you attach a constructor function named Echo to JNEXT. Within the constructor you perform the following key operations using the init function: - Specify the required module exported by the native side. The name of the required module must match the name of a shared library file (.so file). @@ -139,7 +141,7 @@ Now, index.js interacts with the native side using JNEXT. So you attach a constr - Create an object by using an acquired module and save the ID that's returned by the call. self.m_id = JNEXT.createObject("libecho.Echo"); -When your application calls the echo function in client.js, that call in turn calls the echo function in index.js, where the PluginResult object sends a response (data) back to client.js. Since the args argument passed into the functions was converted by JSON.stringfy() and encoded as a URIcomponent, you must call the following: +When your application calls the echo function in `client.js`, that call in turn calls the echo function in `index.js`, where the PluginResult object sends a response (data) back to `client.js`. Since the args argument passed into the functions was converted by JSON.stringfy() and encoded as a URIcomponent, you must call the following: `data = JSON.parse(decodeURIComponent(args.data));` @@ -158,20 +160,30 @@ You can now send the data back. Letâs put it all together: ## Architecture of the plugin ## -You can place the artifacts of the plugin, which includes the plugin.xml file, the source files (JavaScript, C++), and the binary files (.so) within any directory structure, as long as you correctly specify the file locations in the plugin.xml file. Below we show a typical structure that you can follow: +You can place the artifacts of the plugin, which includes the +`plugin.xml` file, the source files (JavaScript, C++), and the binary +files (`.so`) within any directory structure, as long as you correctly +specify the file locations in the `plugin.xml` file. A typical structure +looks like this: -***your_project_folder*** (>plugin.xml) +***your_project_directory*** (>plugin.xml) - **www** (>client.js) - **src** - **blackberry10** (>index.js, **native** >*.cpp, *.hpp) - - **device** (>*biary file* *.so) + - **device** (>*binary file* *.so) - **simulator** (>*binary file* *.so) -(The list shows the hierarchical relationship among the top level folders. The parenthesis shows the contents of a given folder. All folder names appear in bold text. File names are preceded by the '>' sign.) +(The list shows the hierarchical relationship among the top-level +folders. The parenthesis shows the contents of a given directory. All +directory names appear in bold text. File names are preceded by the `>` +sign.) + +## Contents of the `plugin.xml` file## -## Contents of the plugin.xml file## -The plugin.xml file contains the namespace of the extension and other metadata. Define the namespace and specify other metadata for the Echo plugin as follows: +The `plugin.xml` file contains the namespace of the extension and other +metadata. Define the namespace and specify other metadata for the Echo +plugin as follows: <plugin xmlns="http://www.phonegap.com/ns/plugins/1.0"; id="org.apache.cordova.blackberry.echo"
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/7e5cc869/docs/en/edge/guide/platforms/blackberry10/tools.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/guide/platforms/blackberry10/tools.md b/docs/en/edge/guide/platforms/blackberry10/tools.md index eb64baa..cf8c65a 100644 --- a/docs/en/edge/guide/platforms/blackberry10/tools.md +++ b/docs/en/edge/guide/platforms/blackberry10/tools.md @@ -44,7 +44,9 @@ The 'create' command creates a new project: where - '<path-to-project>' specifies the directory you want the project created in + - '<project-package>' specifies a reverse domain style identifier + - '<project-name>' specifies the apps display name *Note*: the create command bootstraps dependency installation through the 'npm install' command. Depending on installation directory and system permissions, this may require admin privileges. @@ -97,7 +99,9 @@ in debug mode (which produces an unsigned .bar file). where - `-k | --keystorepass <password>` specifies the password you defined when you configured your computer to sign applications. + - `-b | --buildId <number>` specifies the build version number of your application. Typically, this number should be incremented from the previous signed version. This argument is optional. + - `-p | --params <params-JSON-file>` specifies a JSON file containing additional parameters to pass to downstream tools. This argument is optional. ### Build your project in debug mode http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/7e5cc869/docs/en/edge/guide/platforms/blackberry10/upgrading.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/guide/platforms/blackberry10/upgrading.md b/docs/en/edge/guide/platforms/blackberry10/upgrading.md index 9c2c16b..85165f8 100644 --- a/docs/en/edge/guide/platforms/blackberry10/upgrading.md +++ b/docs/en/edge/guide/platforms/blackberry10/upgrading.md @@ -24,47 +24,65 @@ Most of these instructions apply to projects created with an older set of command-line tools that precede the `cordova` CLI utility. See The Command-line Interface for information how to update the version of the CLI. - Please note that the CLI supports the BlackBerry10 platform exclusively. For PlayBook and BBOS, please see Cordova version 2.9.0 and below. ## Upgrade to the CLI (3.0.0) from 2.9.0 ## -1. **Create a new Apache Cordova 3.0.0 project using the cordova CLI**, as +1. Create a new Apache Cordova 3.0.0 project using the cordova CLI, as described in The Command-line Interface. -2. **Add your platforms the the cordova project**, for example: `cordova + +2. Add your platforms the the cordova project, for example: `cordova platform add blackberry10`. -3. **Copy the contents of the original project's `www` folder** to the `www` folder + +3. Copy the contents of the original project's `www` directory to the `www` directory at the root of the cordova project you just created. -4. **Copy or overwrite any native assets from your original project** + +4. Copy or overwrite any native assets from your original project (`Resources`, etc.) -5. **Copy your config.xml into the www folder, and remove any plugin definitions**. You will modify settings here instead of the platform folder. -6. **Use the cordova CLI tool to install any plugins you need.** Note that + +5. Copy your `config.xml` into the `www` directory, and remove any plugin definitions. You will modify settings here instead of the platform directory. + +6. Use the cordova CLI tool to install any plugins you need. Note that the CLI handles all core APIs as plugins, so they may need to be added. Only 3.0.0 plugins are compatible with the CLI. -7. **Build and test.** + +7. Build and test. ## Upgrading 2.8.0 projects to 2.9.0 ## BlackBerry 10: -1. **Download and extract the Cordova 2.9.0 source** to a **permanent folder location** on your hard drive (say to ~/Cordova-2.9.0) -2. **Quit any running SDK tools**: Eclipse, Momentics and the like. -3. **Navigate** to the directory where you put the downloaded source above, using a unix like terminal: **Terminal.app**, **Bash**, **Cygwin**, etc. -4. **Create a new project**, as described in BlackBerry Command-line Tools. This becomes the home of your updated project. -5. **Copy** your projects source from the old project's /www folder to the new project's /www folder -6. **Update** the Cordova script reference in your **www/index.html** file (and any other files that contain the script reference) to point to the new **cordova.js** file +1. Download and extract the Cordova 2.9.0 source to a permanent directory location on your hard drive, for example to `~/Cordova-2.9.0`. + +2. Quit any running SDK tools: Eclipse, Momentics and the like. + +3. Navigate to the directory where you put the downloaded source above, using a unix like terminal: Terminal.app, Bash, Cygwin, etc. + +4. Create a new project, as described in BlackBerry Command-line Tools. This becomes the home of your updated project. + +5. Copy your projects source from the old project's `/www` directory to the new project's `/www` directory. + +6. Update the Cordova script reference in your `www/index.html` file (and any other files that contain the script reference) to point to the new `cordova.js` file. ### BlackBerryOS/Playbook ### -1. **Download and extract the Cordova 2.9.0 source** to a **permanent folder location** on your hard drive (say to ~/Cordova-2.9.0) -2. **Quit any running SDK tools**: Eclipse, Momentics and the like. -3. **Navigate** to the directory where you put the downloaded source above, using a unix like terminal: **Terminal.app**, **Bash**, **Cygwin**, etc. -4. **Create a new project**, as described in iOS Command-line Tools. You need the assets from this new project. -5. **Copy** the **www/cordova.js** file from the new project into your **www** folder, and delete your **www/cordova.js** file -6. **Update** the Cordova script reference in your **www/index.html** file (and any other files that contain the script reference) to point to the new **cordova.js** file -7. **Copy** the **native** folder from the new project into the existing project, overwriting the old **native** folder -8. **Copy** the **lib** folder from the new project into the existing project, overwriting the old **lib** folder -9. **Copy** the **cordova** folder from the new project into the existing project, overwriting the old **cordova** folder +1. Download and extract the Cordova 2.9.0 source to a permanent directory location on your hard drive, for example to `~/Cordova-2.9.0`. + +2. Quit any running SDK tools: Eclipse, Momentics and the like. + +3. Navigate to the directory where you put the downloaded source above, using a unix like terminal: Terminal.app, Bash, Cygwin, etc. + +4. Create a new project, as described in iOS Command-line Tools. You need the assets from this new project. + +5. Copy the `www/cordova.js` file from the new project into your `www` directory, and delete your `www/cordova.js` file. + +6. Update the Cordova script reference in your `www/index.html` file (and any other files that contain the script reference) to point to the new `cordova.js` file. + +7. Copy the `native` directory from the new project into the existing project, overwriting the old `native` directory. + +8. Copy the `lib` directory from the new project into the existing project, overwriting the old `lib` directory. + +9. Copy the `cordova` directory from the new project into the existing project, overwriting the old `cordova` directory. ## Upgrading 2.7.0 projects to 2.8.0 ## @@ -73,181 +91,270 @@ BlackBerry 10: BlackBerry 10 uses the new CLI tooling and manages core APIs as plugins. The instructions migrate your project to a new project, rather than updating an existing project, due to the complexity of updating an old project. Also note that the cordova js script file is now called 'cordova.js' and no longer contains a version string. -1. **Download and extract the Cordova 2.8.0 source** to a **permanent folder location** on your hard drive (say to ~/Cordova-2.8.0) -2. **Quit any running SDK tools**: Eclipse, Momentics and the like. -3. **Navigate** to the directory where you put the downloaded source above, using a unix like terminal: **Terminal.app**, **Bash**, **Cygwin**, etc. -4. **Create a new project**, as described in BlackBerry Command-line Tools. This becomes the home of your updated project. -5. **Copy** your projects source from the old project's /www folder to the new project's /www folder -6. **Update** the Cordova script reference in your **www/index.html** file (and any other files that contain the script reference) to point to the new **cordova.js** file +1. Download and extract the Cordova 2.8.0 source to a permanent directory location on your hard drive, for example to `~/Cordova-2.8.0`. + +2. Quit any running SDK tools: Eclipse, Momentics and the like. + +3. Navigate to the directory where you put the downloaded source above, using a unix like terminal: Terminal.app, Bash, Cygwin, etc. + +4. Create a new project, as described in BlackBerry Command-line Tools. This becomes the home of your updated project. + +5. Copy your projects source from the old project's `/www` directory to the new project's `/www` directory. + +6. Update the Cordova script reference in your `www/index.html` file (and any other files that contain the script reference) to point to the new `cordova.js` file. BlackBerryOS/Playbook: -1. **Download and extract the Cordova 2.8.0 source** to a **permanent folder location** on your hard drive (say to ~/Cordova-2.8.0) -2. **Quit any running SDK tools**: Eclipse, Momentics and the like. -3. **Navigate** to the directory where you put the downloaded source above, using a unix like terminal: **Terminal.app**, **Bash**, **Cygwin**, etc. -4. **Create a new project**, as described in iOS Command-line Tools. You need the assets from this new project. -5. **Copy** the **www/cordova.js** file from the new project into your **www** folder, and delete your **www/cordova.js** file -6. **Update** the Cordova script reference in your **www/index.html** file (and any other files that contain the script reference) to point to the new **cordova.js** file -7. **Copy** the **native** folder from the new project into the existing project, overwriting the old **native** folder -8. **Copy** the **lib** folder from the new project into the existing project, overwriting the old **lib** folder -9. **Copy** the **cordova** folder from the new project into the existing project, overwriting the old **cordova** folder +1. Download and extract the Cordova 2.8.0 source to a permanent directory location on your hard drive, for example to `~/Cordova-2.8.0`. + +2. Quit any running SDK tools: Eclipse, Momentics and the like. + +3. Navigate to the directory where you put the downloaded source above, using a unix like terminal: Terminal.app, Bash, Cygwin, etc. + +4. Create a new project, as described in iOS Command-line Tools. You need the assets from this new project. + +5. Copy the `www/cordova.js` file from the new project into your `www` directory, and delete your `www/cordova.js` file. + +6. Update the Cordova script reference in your `www/index.html` file (and any other files that contain the script reference) to point to the new `cordova.js` file. + +7. Copy the `native` directory from the new project into the existing project, overwriting the old `native` directory. + +8. Copy the `lib` directory from the new project into the existing project, overwriting the old `lib` directory. + +9. Copy the `cordova` directory from the new project into the existing project, overwriting the old `cordova` directory. ## Upgrading 2.6.0 projects to 2.7.0 ## -1. **Download and extract the Cordova 2.7.0 source** to a **permanent folder location** on your hard drive (say to ~/Cordova-2.7.0) -2. **Quit any running SDK tools**: Eclipse, Momentics and the like. -3. **Navigate** to the directory where you put the downloaded source above, using a unix like terminal: **Terminal.app**, **Bash**, **Cygwin**, etc. -4. **Create a new project**, as described in BlackBerry Command-line Tools. You need the assets from this new project. -5. **Copy** the **www/cordova-2.7.0.js** file from the new project into your **www** folder, and delete your **www/cordova-2.6.0.js** file -6. **Update** the Cordova script reference in your **www/index.html** file (and any other files that contain the script reference) to point to the new **cordova-2.7.0.js** file -7. **Copy** the **native** folder from the new project into the existing project, overwriting the old **native** folder -8. **Copy** the **lib** folder from the new project into the existing project, overwriting the old **lib** folder -9. **Copy** the **cordova** folder from the new project into the existing project, overwriting the old **cordova** folder +1. Download and extract the Cordova 2.7.0 source to a permanent directory location on your hard drive, for example to `~/Cordova-2.7.0`. + +2. Quit any running SDK tools: Eclipse, Momentics and the like. + +3. Navigate to the directory where you put the downloaded source above, using a unix like terminal: Terminal.app, Bash, Cygwin, etc. + +4. Create a new project, as described in BlackBerry Command-line Tools. You need the assets from this new project. + +5. Copy the `www/cordova-2.7.0.js` file from the new project into your `www` directory, and delete your `www/cordova-2.6.0.js` file. + +6. Update the Cordova script reference in your `www/index.html` file (and any other files that contain the script reference) to point to the new `cordova-2.7.0.js` file. + +7. Copy the `native` directory from the new project into the existing project, overwriting the old `native` directory. + +8. Copy the `lib` directory from the new project into the existing project, overwriting the old `lib` directory. + +9. Copy the `cordova` directory from the new project into the existing project, overwriting the old `cordova` directory. ## Upgrade to 2.6.0 from 2.5.0 ## -Updating the PhoneGap download folder: +Updating the PhoneGap download directory: -It is recommended that you download a fresh copy of the entire folder. +It is recommended that you download a fresh copy of the entire directory. However, here are the new parts needed for the piecemeal update: -1. Update the cordova.blackberry.js file in the âPhonegap-2.6.0/lib/blackberry/javascriptâ folder -2. Update the âextâ, âext-airâ, and âext-qnxâ in the âPhonegap-2.6.0/lib/blackberry/frameworkâ folder -3. Update the âbuild.xmlâ file in the âPhonegap-2.6.0/lib/blackberryâ folder -4. Update the âPhonegap-2.6.0/lib/blackberry/binâ folder -5. Update the âVERSIONâ file in the âPhonegap-2.6.0/lib/blackberryâ folder - -Updating the example/ folder or migrating an existing project: - -1. Open your `www/` folder, which contains your app. -2. Remove and update the .jar file in the `ext/` folder. -3. Update the contents of the `ext-air/` folder. -4. Update the contents of the `ext-qnx/` folder. + +1. Update the cordova.blackberry.js file in the `Phonegap-2.6.0/lib/blackberry/javascript` directory. + +2. Update the `ext`, `ext-air`, and `ext-qnx` in the `Phonegap-2.6.0/lib/blackberry/framework` directory. + +3. Update the `build.xml` file in the `Phonegap-2.6.0/lib/blackberry` directory. + +4. Update the `Phonegap-2.6.0/lib/blackberry/bin` directory. + +5. Update the `VERSION` file in the `Phonegap-2.6.0/lib/blackberry` directory. + +Updating the example/ directory or migrating an existing project: + +1. Open your `www/` directory, which contains your app. + +2. Remove and update the .jar file in the `ext/` directory. + +3. Update the contents of the `ext-air/` directory. + +4. Update the contents of the `ext-qnx/` directory. + 4. Copy the new `cordova-2.6.0.js` into your project. + 5. Update your HTML to use the new `cordova-2.6.0.js` file. ## Upgrade to 2.5.0 from 2.4.0 ## -Updating the PhoneGap download folder: +Updating the PhoneGap download directory: -It is recommended that you download a fresh copy of the entire folder. +It is recommended that you download a fresh copy of the entire directory. However, here are the new parts needed for the piecemeal update: -1. Update the cordova.blackberry.js file in the âPhonegap-2.5.0/lib/blackberry/javascriptâ folder -2. Update the âextâ, âext-airâ, and âext-qnxâ in the âPhonegap-2.5.0/lib/blackberry/frameworkâ folder -3. Update the âbuild.xmlâ file in the âPhonegap-2.5.0/lib/blackberryâ folder -4. Update the âPhonegap-2.5.0/lib/blackberry/binâ folder -5. Update the âVERSIONâ file in the âPhonegap-2.5.0/lib/blackberryâ folder - -Updating the example/ folder or migrating an existing project: - -1. Open your `www/` folder, which contains your app. -2. Remove and update the .jar file in the `ext/` folder. -3. Update the contents of the `ext-air/` folder. -4. Update the contents of the `ext-qnx/` folder. + +1. Update the cordova.blackberry.js file in the `Phonegap-2.5.0/lib/blackberry/javascript` directory. + +2. Update the `ext`, `ext-air`, and `ext-qnx` in the `Phonegap-2.5.0/lib/blackberry/framework` directory. + +3. Update the `build.xml` file in the `Phonegap-2.5.0/lib/blackberry` directory. + +4. Update the `Phonegap-2.5.0/lib/blackberry/bin` directory. + +5. Update the `VERSION` file in the `Phonegap-2.5.0/lib/blackberry` directory. + +Updating the example/ directory or migrating an existing project: + +1. Open your `www/` directory, which contains your app. + +2. Remove and update the .jar file in the `ext/` directory. + +3. Update the contents of the `ext-air/` directory. + +4. Update the contents of the `ext-qnx/` directory. + 4. Copy the new `cordova-2.5.0.js` into your project. + 5. Update your HTML to use the new `cordova-2.5.0.js` file. ## Upgrade to 2.4.0 from 2.3.0 ## -Updating just the `www` folder: +Updating just the `www` directory: + +1. Open your `www/` directory, which contains your app. + +2. Remove and update the .jar file in the `ext/` directory. + +3. Update the contents of the `ext-air/` directory. -1. Open your `www/` folder, which contains your app. -2. Remove and update the .jar file in the `ext/` folder. -3. Update the contents of the `ext-air/` folder. 4. Copy the new `cordova-2.4.0.js` into your project. - - If playbook, then update the .js file in the `playbook/` folder. - - If BlackBerry 10, then update the .js file in the `qnx/` folder. + - If playbook, then update the .js file in the `playbook/` directory. + - If BlackBerry 10, then update the .js file in the `qnx/` directory. + 5. Update your HTML to use the new `cordova-2.4.0.js` file. -Updating the sample folder (ie, updating using the ant tools): +Updating the sample directory (i.e., updating using the ant tools): + +1. Open the `sample/lib/` directory. + +2. Update the .jar file in the `cordova.2.3.0/ext/` directory. + +3. Update the contents of the `cordova.2.3.0/ext-air/` directory. + +4. Update the contents of the `cordova.2.3.0/ext-qnx/` directory. + +5. Update the .js file in the `cordova.2.3.0/javascript/` directory. + +6. Open the `sample/lib/` directory and rename the `cordova.2.3.0/` directory to `cordova.2.4.0/`. -1. Open the `sample/lib/` folder. -2. Update the .jar file in the `cordova.2.3.0/ext/` folder. -3. Update the contents of the `cordova.2.3.0/ext-air/` folder. -4. Update the contents of the `cordova.2.3.0/ext-qnx/` folder. -5. Update the .js file in the `cordova.2.3.0/javascript/` folder. -6. Open the `sample/lib/` folder and rename the `cordova.2.3.0/` folder to `cordova.2.4.0/`. -7. Type `ant blackberry build` or `ant playbook build` to update the `www/` folder with updated Cordova. -8. Open the `www/` folder and update your HTML to use the new `cordova-2.4.0.js` file +7. Type `ant blackberry build` or `ant playbook build` to update the `www/` directory with updated Cordova. + +8. Open the `www/` directory and update your HTML to use the new `cordova-2.4.0.js` file. ## Upgrade to 2.3.0 from 2.2.0 ## -Updating just the `www` folder: +Updating just the `www` directory: + +1. Open your `www/` directory, which contains your app. + +2. Remove and update the .jar file in the `ext/` directory. + +3. Update the contents of the `ext-air/` directory. -1. Open your `www/` folder, which contains your app. -2. Remove and update the .jar file in the `ext/` folder. -3. Update the contents of the `ext-air/` folder. 4. Copy the new `cordova-2.3.0.js` into your project. - - If playbook, then update the .js file in the `playbook/` folder. - - If BlackBerry 10, then update the .js file in the `qnx/` folder. + - If playbook, then update the .js file in the `playbook/` directory. + - If BlackBerry 10, then update the .js file in the `qnx/` directory. + 5. Update your HTML to use the new `cordova-2.3.0.js` file. -Updating the sample folder (ie, updating using the ant tools): +Updating the sample directory (i.e., updating using the ant tools): + +1. Open the `sample/lib/` directory. + +2. Update the .jar file in the `cordova.2.2.0/ext/` directory. + +3. Update the contents of the `cordova.2.2.0/ext-air/` directory. -1. Open the `sample/lib/` folder. -2. Update the .jar file in the `cordova.2.2.0/ext/` folder. -3. Update the contents of the `cordova.2.2.0/ext-air/` folder. -4. Update the contents of the `cordova.2.2.0/ext-qnx/` folder. -5. Update the .js file in the `cordova.2.2.0/javascript/` folder. -6. Open the `sample/lib/` folder and rename the `cordova.2.2.0/` folder to `cordova.2.3.0/`. -7. Type `ant blackberry build` or `ant playbook build` to update the `www/` folder with updated Cordova. -8. Open the `www/` folder and update your HTML to use the new `cordova-2.3.0.js` file +4. Update the contents of the `cordova.2.2.0/ext-qnx/` directory. + +5. Update the .js file in the `cordova.2.2.0/javascript/` directory. + +6. Open the `sample/lib/` directory and rename the `cordova.2.2.0/` directory to `cordova.2.3.0/`. + +7. Type `ant blackberry build` or `ant playbook build` to update the `www/` directory with updated Cordova. + +8. Open the `www/` directory and update your HTML to use the new `cordova-2.3.0.js` file. ## Upgrade to 2.2.0 from 2.1.0 ## -Updating just the www folder: +Updating just the www directory: + +1. Open your `www/` directory, which contains your app. + +2. Remove and update the .jar file in the `ext/` directory. + +3. Update the contents of the `ext-air/` directory. -1. Open your `www/` folder, which contains your app. -2. Remove and update the .jar file in the `ext/` folder. -3. Update the contents of the `ext-air/` folder. 4. Copy the new `cordova-2.2.0.js` into your project. - - If playbook, then update the .js file in the `playbook/` folder. - - If BlackBerry 10, then update the .js file in the `qnx/` folder. + - If playbook, then update the .js file in the `playbook/` directory. + - If BlackBerry 10, then update the .js file in the `qnx/` directory. + 5. Update your HTML to use the new `cordova-2.2.0.js` file. -Updating the sample folder (ie, updating using the ant tools): +Updating the sample directory (i.e., updating using the ant tools): -1. Open the `sample/lib/` folder. -2. Update the .jar file in the `cordova.2.1.0/ext/` folder. -3. Update the contents of the `cordova.2.1.0/ext-air/` folder. -4. Update the contents of the `cordova.2.1.0/ext-qnx/` folder. -5. Update the .js file in the `cordova.2.1.0/javascript/` folder. -6. Open the `sample/lib/` folder and rename the `cordova.2.1.0/` folder to `cordova.2.2.0/`. -7. Type `ant blackberry build` or `ant playbook build` to update the `www/` folder with updated Cordova. -8. Open the `www/` folder and update your HTML to use the new `cordova-2.2.0.js` file. +1. Open the `sample/lib/` directory. + +2. Update the .jar file in the `cordova.2.1.0/ext/` directory. + +3. Update the contents of the `cordova.2.1.0/ext-air/` directory. + +4. Update the contents of the `cordova.2.1.0/ext-qnx/` directory. + +5. Update the .js file in the `cordova.2.1.0/javascript/` directory. + +6. Open the `sample/lib/` directory and rename the `cordova.2.1.0/` directory to `cordova.2.2.0/`. + +7. Type `ant blackberry build` or `ant playbook build` to update the `www/` directory with updated Cordova. + +8. Open the `www/` directory and update your HTML to use the new `cordova-2.2.0.js` file. ## Upgrade to 2.1.0 from 2.0.0 ## -Updating just the `www` folder: +Updating just the `www` directory: + +1. Open your `www/` directory, which contains your app. + +2. Remove and update the .jar file in the `ext/` directory. + +3. Update the contents of the `ext-air/` directory. -1. Open your `www/` folder, which contains your app. -2. Remove and update the .jar file in the `ext/` folder. -3. Update the contents of the `ext-air/` folder. 4. Copy the new `cordova-2.1.0.js` into your project. - - If playbook, then update the .js file in the `playbook/` folder. + - If playbook, then update the .js file in the `playbook/` directory. + 5. Update your HTML to use the new `cordova-2.1.0.js` file. -Updating the sample folder (ie, updating using the ant tools): +Updating the sample directory (i.e., updating using the ant tools): + +1. Open the `sample/lib/` directory. + +2. Update the .jar file in the `cordova.2.0.0/ext/` directory. + +3. Update the contents of the `cordova.2.0.0/ext-air/` directory. + +4. Update the .js file in the `cordova.2.0.0/javascript/` directory. + +5. Open the `sample/lib/` directory and rename the `cordova.2.0.0/` directory to `cordova.2.1.0/`. + +6. Type `ant blackberry build` or `ant playbook build` to update the `www/` directory with updated Cordova. -1. Open the `sample/lib/` folder. -2. Update the .jar file in the `cordova.2.0.0/ext/` folder. -3. Update the contents of the `cordova.2.0.0/ext-air/` folder. -4. Update the .js file in the `cordova.2.0.0/javascript/` folder. -5. Open the `sample/lib/` folder and rename the `cordova.2.0.0/` folder to `cordova.2.1.0/`. -6. Type `ant blackberry build` or `ant playbook build` to update the `www/` folder with updated Cordova. -7. Open the `www/` folder and update your HTML to use the new `cordova-2.1.0.js` file. +7. Open the `www/` directory and update your HTML to use the new `cordova-2.1.0.js` file. ## Upgrade to 2.0.0 from 1.9.0 ## -Updating just the `www` folder: +Updating just the `www` directory: + +1. Open your `www/` directory, which contains your app. + +2. Remove and update the .jar file in the `ext/` directory. + +3. Update the contents of the `ext-air/` directory. -1. Open your `www/` folder, which contains your app. -2. Remove and update the .jar file in the `ext/` folder. -3. Update the contents of the `ext-air/` folder. 4. Copy the new `cordova-2.0.0.js` into your project. - - If playbook, then update the .js file in the `playbook/` folder. + - If playbook, then update the .js file in the `playbook/` directory. + 5. Update your HTML to use the new `cordova-2.0.0.js` file. + 6. Update your `www/plugins.xml` file. Two plugins changed their namespace/service label. Change the old entries for the Capture and Contact plugins from: @@ -260,16 +367,23 @@ Updating just the `www` folder: <plugin name="Capture" value="org.apache.cordova.capture.MediaCapture"/> <plugin name="Contacts" value="org.apache.cordova.pim.Contact"/> -Updating the sample folder (ie, updating using the ant tools): +Updating the sample directory (i.e., updating using the ant tools): + +1. Open the `sample/lib/` directory. + +2. Update the .jar file in the `cordova.1.9.0/ext/` directory. + +3. Update the contents of the `cordova.1.9.0/ext-air/` directory. -1. Open the `sample/lib/` folder. -2. Update the .jar file in the `cordova.1.9.0/ext/` folder. -3. Update the contents of the `cordova.1.9.0/ext-air/` folder. -4. Update the .js file in the `cordova.1.9.0/javascript/` folder. -5. Open the `sample/lib/` folder and rename the `cordova.1.9.0/` folder to `cordova.2.0.0/`. -6. Type `ant blackberry build` or `ant playbook build` to update the `www/` folder with updated Cordova. -7. Open the `www/` folder and update your HTML to use the new `cordova-2.0.0.js` file. -8. Open the `www/` folder and update the `plugins.xml` file. Two plugins +4. Update the .js file in the `cordova.1.9.0/javascript/` directory. + +5. Open the `sample/lib/` directory and rename the `cordova.1.9.0/` directory to `cordova.2.0.0/`. + +6. Type `ant blackberry build` or `ant playbook build` to update the `www/` directory with updated Cordova. + +7. Open the `www/` directory and update your HTML to use the new `cordova-2.0.0.js` file. + +8. Open the `www/` directory and update the `plugins.xml` file. Two plugins changed their namespace/service label. Change the old entries for the Capture and Contact plugins from: @@ -285,14 +399,19 @@ Updating the sample folder (ie, updating using the ant tools): ## Upgrade to 1.8.0 from 1.7.0 ## -Updating just the `www` folder: +Updating just the `www` directory: + +1. Open your `www/` directory, which contains your app. + +2. Remove and update the .jar file in the `ext/` directory. + +3. Update the contents of the `ext-air/` directory. -1. Open your `www/` folder, which contains your app. -2. Remove and update the .jar file in the `ext/` folder. -3. Update the contents of the `ext-air/` folder. 4. Copy the new `cordova-1.8.0.js` into your project. - - If playbook, then update the .js file in the `playbook/` folder. + - If playbook, then update the .js file in the `playbook/` directory. + 5. Update your HTML to use the new `cordova-1.8.0.js` file. + 6. Update your `www/plugins.xml` file. Two plugins changed their namespace/service label. Change the old entries for the Capture and Contact plugins from: @@ -305,16 +424,23 @@ Updating just the `www` folder: <plugin name="Capture" value="org.apache.cordova.capture.MediaCapture"/> <plugin name="Contacts" value="org.apache.cordova.pim.Contact"/> -Updating the sample folder (ie, updating using the ant tools): +Updating the sample directory (i.e., updating using the ant tools): + +1. Open the `sample/lib/` directory. + +2. Update the .jar file in the `cordova.1.7.0/ext/` directory. + +3. Update the contents of the `cordova.1.7.0/ext-air/` directory. + +4. Update the .js file in the `cordova.1.7.0/javascript/` directory. + +5. Open the `sample/lib/` directory and rename the `cordova.1.7.0/` directory to `cordova.1.8.0/`. + +6. Type `ant blackberry build` or `ant playbook build` to update the `www/` directory with updated Cordova. + +7. Open the `www/` directory and update your HTML to use the new `cordova-1.8.0.js` file. -1. Open the `sample/lib/` folder. -2. Update the .jar file in the `cordova.1.7.0/ext/` folder. -3. Update the contents of the `cordova.1.7.0/ext-air/` folder. -4. Update the .js file in the `cordova.1.7.0/javascript/` folder. -5. Open the `sample/lib/` folder and rename the `cordova.1.7.0/` folder to `cordova.1.8.0/`. -6. Type `ant blackberry build` or `ant playbook build` to update the `www/` folder with updated Cordova. -7. Open the `www/` folder and update your HTML to use the new `cordova-1.8.0.js` file. -8. Open the `www/` folder and update the `plugins.xml` file. Two plugins +8. Open the `www/` directory and update the `plugins.xml` file. Two plugins changed their namespace/service label. Change the old entries for the Capture and Contact plugins from: http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/7e5cc869/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 ba79cf8..0dcfe23 100644 --- a/docs/en/edge/guide/platforms/ios/config.md +++ b/docs/en/edge/guide/platforms/ios/config.md @@ -19,39 +19,75 @@ license: Licensed to the Apache Software Foundation (ASF) under one # iOS Configuration -The `config.xml` settings file controls various settings of Cordova. This is application wide, and not set per CDVViewController instance. -The `config.xml` file is located in your `<project folder>/<appname>` directory. - -## <preference> - -Various preferences (as **<preference>** tags) default on not breaking existing apps. The available preferences are: - -1. **DisallowOverscroll (boolean, defaults to false)** - set to true if you don't want the WebView to rubber-band - -2. **TopActivityIndicator (string, defaults to 'gray')** - this is the top spinning throbber in the status/battery bar, valid values are `whiteLarge`, `white`, and `gray` - -3. **EnableLocation (boolean, defaults to false)** - set to true, to initialize the Geolocation plugin at start-up (so the fix on your location can be more accurate) **DEPRECATED**: please set the **onload** attribute of the **Geolocation** plugin to **true** instead. - -4. **EnableViewportScale (boolean, defaults to false)** - set to true to prevent viewport scaling through a meta tag - -5. **AutoHideSplashScreen (boolean, defaults to true)** - set to false to control when the splashscreen is hidden through a JavaScript API - -6. **FadeSplashScreen (boolean, defaults to true)** - set to false to prevent the splash-screen to fade in and out when showing or hiding it. - -7. **FadeSplashScreenDuration (float, defaults to 2)** - The splash-screen Fade duration in seconds. - -8. **ShowSplashScreenSpinner (boolean, defaults to true)** - set to false to hide the splash-screen spinner - -9. **MediaPlaybackRequiresUserAction (boolean, defaults to false)** - set to true to not allow autoplayed HTML5 video - -10. **AllowInlineMediaPlayback (boolean, defaults to false)** - set to true to allow inline HTML5 media playback, also, the video element in the HTML document must also include the webkit-playsinline attribute - -11. **BackupWebStorage (string, defaults to 'cloud')** - valid values are 'none', 'cloud' and 'local'. Set to 'cloud' to allow the web storage data to be backed up to iCloud, and set to 'local' to only allow local backups (iTunes sync). Set to 'none' to not allow any backups of web storage. - -12. **KeyboardDisplayRequiresUserAction (boolean, defaults to true)** - set to false to open the keyboard when form elements get focus via the JavaScript focus() call. - -13. **SuppressesIncrementalRendering (boolean, defaults to false)** - set to true to wait until all new view content has been received before it is rendered. - -14. **HideKeyboardFormAccessoryBar (boolean, defaults to false)** - set to true to hide the additional toolbar that is on top of the keyboard (this is the toolbar that has the Prev, Next and Done buttons) - -15. **KeyboardShrinksView (boolean, defaults to false)** - set to true to shrink the WebView when the keyboard comes up. The WebView shrinks instead of the viewport shrinking and the page scrollable. This 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. +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. + +## `<preference>` + +Various preferences (as `<preference>` tags) default on not breaking +existing apps. The available preferences are: + +* `DisallowOverscroll` (boolean, defaults to false): set to `true` if + you don't want the WebView to rubber-band. + +* `TopActivityIndicator` (string, defaults to `gray`): this is the top + spinning throbber in the status/battery bar, valid values are + `whiteLarge`, `white`, and `gray`. + +* `EnableLocation` (boolean, defaults to false): set to true, to + initialize the Geolocation plugin at start-up (so the fix on your + location can be more accurate) **DEPRECATED**: please set the + `onload` attribute of the `Geolocation` plugin to `true` + instead. + +* `EnableViewportScale` (boolean, defaults to false): set to true to + prevent viewport scaling through a meta tag. + +* `AutoHideSplashScreen` (boolean, defaults to true): set to false to + control when the splashscreen is hidden through a JavaScript API. + +* `FadeSplashScreen` (boolean, defaults to true): set to false to + prevent the splash-screen to fade in and out when showing or hiding + it. + +* `FadeSplashScreenDuration` (float, defaults to 2): The splash-screen + Fade duration in seconds. + +* `ShowSplashScreenSpinner` (boolean, defaults to true): set to false + to hide the splash-screen spinner. + +* `MediaPlaybackRequiresUserAction` (boolean, defaults to false): set + to true to not allow autoplayed HTML5 video. + +* `AllowInlineMediaPlayback` (boolean, defaults to false): set to + true to allow inline HTML5 media playback, also, the video element + in the HTML document must also include the webkit-playsinline + attribute. + +* `BackupWebStorage` (string, defaults to `cloud`): valid values are + `none`, `cloud` and `local`. Set to `cloud` to allow the web + storage data to be backed up to iCloud, and set to `local` to only + allow local backups (iTunes sync). Set to `none` to not allow any + backups of web storage. + +* `KeyboardDisplayRequiresUserAction` (boolean, defaults to true): + set to false to open the keyboard when form elements get focus via + the JavaScript focus() call. + +* `SuppressesIncrementalRendering` (boolean, defaults to false): set + to true to wait until all new view content has been received + before it is rendered. + +* `HideKeyboardFormAccessoryBar` (boolean, defaults to false): set to + true to hide the additional toolbar that is on top of the + keyboard. This toolbar features the __Prev__, __Next__, and __Done__ + buttons. + +* `KeyboardShrinksView` (boolean, defaults to false): set to `true` to + shrink the WebView when the keyboard comes up. The WebView shrinks + instead of the viewport shrinking and the page scrollable. This + 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. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/7e5cc869/docs/en/edge/guide/platforms/ios/plugin.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/guide/platforms/ios/plugin.md b/docs/en/edge/guide/platforms/ios/plugin.md index 1d7e5e8..c76bd86 100644 --- a/docs/en/edge/guide/platforms/ios/plugin.md +++ b/docs/en/edge/guide/platforms/ios/plugin.md @@ -21,7 +21,7 @@ license: Licensed to the Apache Software Foundation (ASF) under one A plugin is an Objective-C class that extends the `CDVPlugin` class. -Each plugin class must be registered using the config.xml file, as a <plugin> tag under the <plugins> key. +Each plugin class must be registered using the config.xml file, as a `<plugin>` tag under the `<plugins>` key. ## Plugin Class Mapping @@ -48,7 +48,7 @@ reachable by Cordova. ## Plugin Initialization and Lifetime -There is one instance of a plugin object that is created per-UIWebView, and the lifetime of the instance is tied to the UIWebView. Plugins are not instantiated until they are first referenced by a call from JS, unless the `onload` attribute set within config.xml. E.g.: +There is one instance of a plugin object that is created per-UIWebView, and the lifetime of the instance is tied to the UIWebView. Plugins are not instantiated until they are first referenced by a call from JavaScript, unless the `onload` attribute set within config.xml. E.g.: <plugin name="Echo" value="Echo" onload="true" /> @@ -76,7 +76,9 @@ What gets dispatched to the plugin via JavaScript's `exec` function gets passed } 1. [CDVInvokedUrlCommand.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVInvokedUrlCommand.h) + 2. [CDVPluginResult.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVPluginResult.h) + 3. [CDVCommandDelegate.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVCommandDelegate.h) ## iOS CDVPluginResult message types @@ -183,6 +185,7 @@ call, you should use a background thread. For example: See other methods that you can override in: 1. [CDVPlugin.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVPlugin.h) + 2. [CDVPlugin.m](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVPlugin.m) For example, you can hook into the `pause`, `resume`, app terminate and `handleOpenURL` events. @@ -200,4 +203,5 @@ running in the iOS 6 Simulator. ## Common Pitfalls * 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. If you forget, an error is logged in the Xcode console.
