http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/5ad93d20/www/docs/en/7.x/guide/platforms/blackberry10/plugin.md ---------------------------------------------------------------------- diff --git a/www/docs/en/7.x/guide/platforms/blackberry10/plugin.md b/www/docs/en/7.x/guide/platforms/blackberry10/plugin.md new file mode 100644 index 0000000..6ec4133 --- /dev/null +++ b/www/docs/en/7.x/guide/platforms/blackberry10/plugin.md @@ -0,0 +1,283 @@ +--- +license: > + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +title: BlackBerry 10 Plugins +toc_title: Blackberry 10 +--- + +# BlackBerry 10 Plugins + +This section provides details for how to implement native plugin code +on the BlackBerry 10 platform. Before reading this, see Application +Plugins for an overview of the plugin's structure and its common +JavaScript interface. This section continues to demonstrate the sample +_echo_ plugin that communicates from the Cordova webview to the native +platform and back. + +The Echo plugin basically returns whatever string the `window.echo` +function sends from JavaScript: + +```javascript +window.echo = function(str, callback) { + cordova.exec(callback, function(err) { + callback('Nothing to echo.'); + }, "Echo", "echo", [str]); +}; +``` + +A Cordova plugin for BlackBerry 10 contains both JavaScript and native +code, which communicate with each other through a framework provided +by JNEXT. Every plugin must also include a `plugin.xml` file. + +## Creating the Native Class + +To create the native portion of your plugin, open the BlackBerry 10 +NDK IDE and select __File → New → BlackBerry Project → +Native Extension → BlackBerry 10__. Enter the desired +project name and location, then press __Finish__. + +The project created by the IDE contains sample code for a memory +plugin. You may replace or modify these files to implement your own +functionality: + +- `*name*_js.hpp`: C++ header for the JNEXT code. + +- `*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 project's public directory. It also +features constants and utility functions available from within native +code. The plugin must be derived from `JSExt`, which is defined in +`plugin.h`. That is, you must implement the following class: + +```cpp +class JSExt +{ +public: + virtual ~JSExt() {}; + virtual string InvokeMethod( const string& strCommand ) = 0; + virtual bool CanDelete( void ) = 0; +private: + std::string m_id; +}; +``` + +The extension should include the `plugin.h` header file. In the `Echo` +example, you use `JSExt` as follows in the `echo_js.hpp` file: + +```cpp +#include "../public/plugin.h" +#include <string> + +#ifndef ECHO_JS_H_ +#define ECHO_JS_H_ + +class Echo : public JSExt +{ +public: + explicit Echo(const std::string& id); + virtual ~Echo(); + virtual std::string InvokeMethod(const std::string& command); + virtual bool CanDelete(); +private: + std::string m_id; +}; + +#endif // ECHO_JS_H_ +``` + +The `m_id` attribute contains the `JNEXT` id for the object, which is +passed to the class as an argument to the constructor. It is needed +for the native side to trigger events on the JavaScript side. The +`CanDelete` method determines whether the native object can be +deleted. The `InvokeMethod` function is called as a result from a +request from JavaScript to invoke a method of this particular +object. The only argument to this function is a string passed from +JavaScript that this method parses to determine which of the native +object's methods should execute. These methods are implemented in +`echo_js.cpp`. Here is the `InvokeMethod` function for the `Echo` +example: + +```cpp +string Echo::InvokeMethod(const string& command) { + + //parse command and args from string + int index = command.find_first_of(" "); + string strCommand = command.substr(0, index); + string strValue = command.substr(index + 1, command.length()); + + // Determine which function should be executed + if (strCommand == "echo") { + return strValue; + } else { + return "Unsupported Method"; + } +} +``` + +The 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. The `Echo` plugin implements the +following in `echo_js.cpp`: + +```cpp +char* onGetObjList() { + static char name[] = "Echo"; + return name; +} +``` + +The `onCreateObject ` function takes two parameters. The first is the +name of the requested class to be created from the JavaScript side, +with valid names as those returned in `onGetObjList`. The second +parameter is the class's unique object id. This method returns a +pointer to the created plugin object. The `Echo` plugin implements the +following in `echo_js.cpp`: + +```cpp +JSExt* onCreateObject(const string& className, const string& id) { + if (className == "Echo") { + return new Echo(id); + } + return NULL; +} +``` + +## Creating the Plugin's JavaScript + +The plugin must contain the following JavaScript files: + +- `client.js`: This is considered the client side and contains the API + available to a Cordova application. 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. + +The client and server side (`client.js` and `index.js`) interacts +through the `Cordova.exec` function. The `client.js` needs to invoke +the `exec` function and provide the necessary arguments. The `Echo` +plugin implements the following in the `client.js` file: + +```javascript +var service = "org.apache.cordova.blackberry.echo", + exec = cordova.require("cordova/exec"); + +module.exports = { + echo: function (data, success, fail) { + exec(success, fail, service, "echo", { data: data }); + } +}; +``` + +The `index.js` component uses JNEXT to interact with the native +side. Attaching a constructor function named `Echo` to JNEXT allows +you to 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): + + ```javascript + JNEXT.require("libecho") + ``` + +- Create an object by using an acquired module and save the ID that's + returned by the call: + + ```javascript + self.m_id = JNEXT.createObject("libecho.Echo"); + ``` + + When the application calls the `echo` function in `client.js`, that + call in turn calls the `echo` function in `index.js`, where the + `PluginResult` object sends data as a response 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: + +```javascript +data = JSON.parse(decodeURIComponent(args.data)); +``` + +You can now send the data back, as in the following: + +```javascript +module.exports = { + echo: function (success, fail, args, env) { + var result = new PluginResult(args, env), + data = JSON.parse(decodeURIComponent(args.data)), + response = echo.getInstance().echo(data); + result.ok(response, false); + } +}; +``` + +## Plugin Architecture + +You can place the plugin's artifacts, including the `plugin.xml` file, +the JavaScript and C++ source files, and the `.so` binary files within +any directory structure, as long as you correctly specify the file +locations in the `plugin.xml` file. Here is a typical structure: + +***project_directory*** (>plugin.xml) + +- **www** (>client.js) +- **src** + - **blackberry10** (>index.js, **native** >*.cpp, *.hpp) + - **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 directory. All +directory names appear in bold text. File names are preceded by the `>` +sign. + +## The _plugin.xml_ file + +The `plugin.xml` file contains the extension's namespace and other +metadata. Set up the `Echo` plugin as follows: + +```xml +<plugin xmlns="http://www.phonegap.com/ns/plugins/1.0"; + id="org.apache.cordova.blackberry.echo" + version="1.0.0"> + <js-module src="www/client.js"> + <merges target="navigator" /> + </js-module> + <platform name="blackberry10"> + <source-file src="src/blackberry10/index.js" /> + <lib-file src="src/blackberry10/native/device/libecho.so" arch="device" /> + <lib-file src="src/blackberry10/native/simulator/libecho.so" arch="simulator" /> + <config-file target="www/config.xml" parent="/widget"> + <feature name="org.apache.cordova.blackberry.echo" value="org.apache.cordova.blackberry.echo" /> + </config-file> + </platform> +</plugin> +```
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/5ad93d20/www/docs/en/7.x/guide/platforms/blackberry10/tools.md ---------------------------------------------------------------------- diff --git a/www/docs/en/7.x/guide/platforms/blackberry10/tools.md b/www/docs/en/7.x/guide/platforms/blackberry10/tools.md new file mode 100644 index 0000000..b209e10 --- /dev/null +++ b/www/docs/en/7.x/guide/platforms/blackberry10/tools.md @@ -0,0 +1,205 @@ +--- +license: > + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +title: BlackBerry 10 Shell Tool Guide +--- + +# BlackBerry 10 Shell Tool Guide + +The `cordova` command-line utility is a high-level tool that allows +you to build applications across several platforms at once. An older +version of the Cordova framework provides sets of command-line tools +specific to each platform. To use them as an alternative to the CLI, +you need to download this version of Cordova from +[cordova.apache.org](http://cordova.apache.org). The download contains +separate archives for each platform. Expand the platform you wish to +target. The tools described here are typically available in the +top-level `bin` directory, otherwise consult the __README__ file for +more detailed directions. + +For information on the low-level command-line interface that enables +plugins, see [Using Plugman to Manage Plugins](../../../plugin_ref/plugman.html). See Application Plugins +for details on how to develop plugins. + +If you need help with any command listed below, type the command along +with the `-h` or `-help` arguments, which are supported by all +commands and which provide descriptions for each of the available +arguments. + +## Create an App + +The `create` command creates a new project: + +``` +bin/create <path-to-project> <project-package> <project-name> +``` + +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 the installation +directory and system permissions, this may require administrator +privileges. If there's problem on OSX/Linux, run `sudo npm install` +before using the `create` command. On Windows, run `npm install` in a +command-line utility opened with administrator privileges. + +## Create a Target + +The `target` command allows you to manage the emulator or BlackBerry +devices that you use to test the app. You can add or remove a target, +or set a target as the default target. + +### Add a Target + +``` +<path-to-project>/cordova/target add <name> <ip-address> [-t | --type <device | simulator>] [-p | --password <password>] [--pin <device-pin>] +``` + +where + +- `<name>` specifies a unique name for the target. + +- `<ip-address>` specifies the ip address of the BlackBerry device or + simulator. + +- `-p | --password <password>` specifies the password for the device or + emulator. This is required only if the device or emulator is + password protected. + +- `--pin <device-pin>` specifies the PIN of the BlackBerry device, + which identifies that device as a valid host for the debug + token. This argument is required only when creating a debug + token. + +### Remove a Target + +``` +<path-to-project>/cordova/target remove <name> +``` + +### Set a Target as the Default + +``` +<path-to-project>/cordova/target default <name> +``` + +## Build the App + +The `build` command builds the project as a .bar file. You can build +the app in either release mode (which produces a signed .bar file) or +in debug mode (which produces an unsigned .bar file). + +### Build the App in Release Mode + +``` +<path-to-project>/cordova/build release [-k | --keystorepass <password>] [-b | --buildId <number>] [-p | --params <params-JSON-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 the Project in Debug Mode + +``` +<path-to-project>/cordova/build debug [<target>] [-k | --keystorepass <password>] [-p | --params <params-JSON-file>] [-ll | --loglevel <error|warn|verbose>] +``` + +where + +- `<target>` specifies the name of a previously added target. If + `<target>` is not specified, the default target is used, if one has + been created. This argument is only required if you want the script + to deploy the app to a BlackBerry device or emulator and you have + not created a default target. Additionally, if `<target>` is a + device, then that device must be connected to your computer by USB + connection or be connected to the same Wi-Fi network as your + computer. + +- `-k | --keystorepass <password>` specifies the password you defined + when you configured your computer to sign applications. This + password is also used to create your debug token. This argument is + only required if you want the script to create and install the debug + token for you. + +- `-p | --params <params-JSON-file>` specifies a JSON file containing + additional parameters to pass to downstream tools. + +- `-ll | --loglevel <level>` specifies the log level. The log level may + be one of `error`, `warn`, or `verbose`. + +If you have previously defined a default target (and previously +installed a debug token, if that target is a BlackBerry device), you +can run the script with no arguments, and the script packages your +app and deploys it to the default target. For example: + +``` +<path-to-project>/cordova/build debug +``` + +## Run the App + +The `run` command deploys the app's most recent build on the specified +BlackBerry device or an emulator. To deploy your app, you need to +specify a target for the device or emulator: + +``` +<path-to-project>/cordova/run <target> +``` + +...where `<target> `specifies the name of a previously added target. +If `<target>` is a device, then it must be connected to your computer +via USB cable, or else over the same Wi-Fi network as your computer. + +## Handle Plugins + +The `target` command allows you to add and remove plugins. To fetch a +locally hosted plugin: + +``` +<path-to-project>/cordova/plugin fetch <path-to-plugin> +``` + +View a list of installed plugins: + +``` +<path-to-project>/cordova/plugin ls +``` + +Add a plugin: + +``` +<path-to-project>/cordova/plugin add <name> +``` + +Remove a plugin: + +``` +<path-to-project>/cordova/plugin rm <name> +``` http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/5ad93d20/www/docs/en/7.x/guide/platforms/blackberry10/upgrade.md ---------------------------------------------------------------------- diff --git a/www/docs/en/7.x/guide/platforms/blackberry10/upgrade.md b/www/docs/en/7.x/guide/platforms/blackberry10/upgrade.md new file mode 100644 index 0000000..fe9f282 --- /dev/null +++ b/www/docs/en/7.x/guide/platforms/blackberry10/upgrade.md @@ -0,0 +1,516 @@ +--- +license: > + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +title: Upgrading BlackBerry 10 +--- + +# Upgrading BlackBerry 10 + +This guide shows how to modify BlackBerry projects to upgrade from older versions of Cordova. +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](../../cli/index.html) for information how to update the +version of the CLI. + +## Upgrading 3.6.0 Projects to 4.0.0 + +For non-CLI projects, run: + + bin/update path/to/project + +For CLI projects: + +1. Update the `cordova` CLI version. See [The Command-Line Interface](../../cli/index.html). + +2. Run `cordova platform update blackberry` in your existing projects. + +## Upgrading to 3.2.0 from 3.1.0 + +For projects that were created with the cordova CLI: + +1. Update the `cordova` CLI version. See [The Command-Line Interface](../../cli/index.html). + +2. Run `cordova platform update blackberry` + +For projects not created with the cordova CLI, run: + + bin/update <project_path> + +## Upgrade to 3.1.0 from 3.0.0 + +1. Create a new Apache Cordova 3.1.0 project using the cordova CLI, as + described in [The Command-Line Interface](../../cli/index.html). + +2. Add your platforms to the cordova project, for example: `cordova + platform add blackberry10`. + +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 + (`Resources`, etc.) + +5. Copy the `config.xml` file into the `www` directory, and remove any + plugin definitions. You need to modify settings here rather than + within 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 plugins marked 3.0.0 and above are compatible with the CLI. + +7. Build and test. + +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 + described in [The Command-Line Interface](../../cli/index.html). + +2. Add your platforms to the cordova project, for example: `cordova + platform add blackberry10`. + +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 + (`Resources`, etc.) + +5. Copy the `config.xml` file into the `www` directory, and remove any + plugin definitions. You need to modify settings here rather than + within 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. + +## Upgrading 2.8.0 Projects to 2.9.0 + +For BlackBerry 10: + +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 Shell Tool Guide. 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 the `www/index.html` file (and any other files that contain the script reference) to point to the new `cordova.js` file. + +For BlackBerryOS/Playbook: + +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 Shell Tool Guide. You need the assets from this new project. + +5. Copy the `www/cordova.js` file from the new project into the `www` directory, and delete the `www/cordova.js` file. + +6. Update the Cordova script reference in the `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 + +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 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 Shell Tool Guide. 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 the `www/index.html` file (and any other files that contain the script reference) to point to the new `cordova.js` file. + +For BlackBerryOS/Playbook: + +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 Shell Tool Guide. You need the assets from this new project. + +5. Copy the `www/cordova.js` file from the new project into the `www` directory, and delete the `www/cordova.js` file. + +6. Update the Cordova script reference in the `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 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 Shell Tool Guide. You need the assets from this new project. + +5. Copy the `www/cordova-2.7.0.js` file from the new project into the `www` directory, and delete the `www/cordova-2.6.0.js` file. + +6. Update the Cordova script reference in the `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 directory: + +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` 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 the `www` directory, which contains the 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 directory: + +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` 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 the `www` directory, which contains the 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` directory: + +1. Open the `www` directory, which contains the app. + +2. Remove and update the .jar file in the `ext/` directory. + +3. Update the contents of the `ext-air/` directory. + +4. Copy the new `cordova-2.4.0.js` into your project. + - 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 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/`. + +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` directory: + +1. Open the `www` directory, which contains the app. + +2. Remove and update the .jar file in the `ext/` directory. + +3. Update the contents of the `ext-air/` directory. + +4. Copy the new `cordova-2.3.0.js` into your project. + - 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 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. + +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 directory: + +1. Open the `www` directory, which contains the app. + +2. Remove and update the .jar file in the `ext/` directory. + +3. Update the contents of the `ext-air/` directory. + +4. Copy the new `cordova-2.2.0.js` into your project. + - 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 directory (i.e., updating using the ant tools): + +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` directory: + +1. Open the `www` directory, which contains the app. + +2. Remove and update the .jar file in the `ext/` directory. + +3. Update the contents of the `ext-air/` directory. + +4. Copy the new `cordova-2.1.0.js` into your project. + - 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 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. + +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` directory: + +1. Open the `www` directory, which contains the app. + +2. Remove and update the .jar file in the `ext/` directory. + +3. Update the contents of the `ext-air/` directory. + +4. Copy the new `cordova-2.0.0.js` into your project. + - 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 the `www/plugins.xml` file. Two plugins changed their + namespace/service label. Change the old entries for the Capture and + Contact plugins from: + + <plugin name="Capture" value="org.apache.cordova.media.MediaCapture"/> + <plugin name="Contact" value="org.apache.cordova.pim.Contact"/> + + To: + + <plugin name="Capture" value="org.apache.cordova.capture.MediaCapture"/> + <plugin name="Contacts" value="org.apache.cordova.pim.Contact"/> + +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. + +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: + + ```xml + <plugin name="Capture" value="org.apache.cordova.media.MediaCapture"/> + <plugin name="Contact" value="org.apache.cordova.pim.Contact"/> + ``` + + To: + + ```xml + <plugin name="Capture" value="org.apache.cordova.capture.MediaCapture"/> + <plugin name="Contacts" value="org.apache.cordova.pim.Contact"/> + ``` + +- To upgrade to 1.8.0, please go from 1.7.0 + +## Upgrade to 1.8.0 from 1.7.0 + +Updating just the `www` directory: + +1. Open the `www` directory, which contains the app. + +2. Remove and update the .jar file in the `ext/` directory. + +3. Update the contents of the `ext-air/` directory. + +4. Copy the new `cordova-1.8.0.js` into your project. + - 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 the `www/plugins.xml` file. Two plugins changed their + namespace/service label. Change the old entries for the Capture and + Contact plugins from: + + ```xml + <plugin name="Capture" value="org.apache.cordova.media.MediaCapture"/> + <plugin name="Contact" value="org.apache.cordova.pim.Contact"/> + ``` + + To: + + ```xml + <plugin name="Capture" value="org.apache.cordova.capture.MediaCapture"/> + <plugin name="Contacts" value="org.apache.cordova.pim.Contact"/> + ``` + +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. + +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: + + ```xml + <plugin name="Capture" value="org.apache.cordova.media.MediaCapture"/> + <plugin name="Contact" value="org.apache.cordova.pim.Contact"/> + ``` + + To: + + ```xml + <plugin name="Capture" value="org.apache.cordova.capture.MediaCapture"/> + <plugin name="Contacts" value="org.apache.cordova.pim.Contact"/> + ``` http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/5ad93d20/www/docs/en/7.x/guide/platforms/ios/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/7.x/guide/platforms/ios/index.md b/www/docs/en/7.x/guide/platforms/ios/index.md new file mode 100644 index 0000000..de400e6 --- /dev/null +++ b/www/docs/en/7.x/guide/platforms/ios/index.md @@ -0,0 +1,309 @@ +--- +license: > + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +title: iOS Platform Guide +toc_title: iOS +--- + +# iOS Platform Guide + +This guide shows how to set up your SDK development environment to +deploy Cordova apps for iOS devices such as iPhone and iPad, +and how to optionally use iOS-centered command-line tools in your +development workflow. You need to install the SDK tools regardless of +whether you want to use these platform-centered shell tools +or cross-platform Cordova CLI for development. For a comparison of the two +development paths, see the [Overview](../../overview/index.html#development-paths). +For details on the CLI, see [Cordova CLI Reference][cli]. + +## Requirements and Support + +Apple® tools required to build iOS applications only run on the OS X +operating system on Intel-based Macs. Xcode® 7.0 (the minimum required +version) runs only on OS X version 10.10.4 (Yosemite) or greater, and +includes the iOS 9 SDK (Software Development Kit). To submit apps to +the Apple App Storeâ requires the latest versions of the Apple tools. + +You can test many of the Cordova features using the iOS simulator +installed with the iOS SDK and Xcode, but you need an actual device to +fully test all of the app's device features before submitting to the +App Store. The device must have at least iOS 8 installed, the +minimum iOS version supported as of Cordova 4.0.0. Supported devices +include iPhone 4S, iPhone 5, iPhone 5C, iPhone 5S, iPhone 6, +iPhone 6 Plus, iPhone 6S, iPhone 6S Plus, iPhone SE, iPad 2, +iPad 3, iPad 4, iPad Air, iPad Air 2, iPad Pro, iPad Mini, +iPad Mini 2, iPad Mini 3, iPod Touch 5th gen and iPod Touch 6th gen or later. + +## Installing the Requirements + +### Xcode + +There are two ways to download Xcode: + +* from the [App Store](https://itunes.apple.com/us/app/xcode/id497799835?mt=12), + available by searching for "Xcode" in the __App Store__ application. + +* from [Apple Developer Downloads](https://developer.apple.com/downloads/index.action), + which requires registration as an Apple Developer. + +Once Xcode is installed, several command-line tools need to be enabled +for Cordova to run. From the command line, run: +```bash +$ xcode-select --install +``` + +### Deployment Tools + +The [ios-deploy](https://www.npmjs.org/package/ios-deploy) tools allow you +to launch iOS apps on an iOS Device from the command-line. + +To install it, run the following from command-line terminal: + +```bash +$ npm install -g ios-deploy +``` + +## Project Configuration + +Installing Xcode will mostly set everything needed to get started with the native side of things. +You should now be able to create and build a cordova project. +For more details on installing and using the CLI, refer to [Create your first app](../../cli/index.html) guide. + +### Deploying to Simulator + +To preview the app in the iOS simulator: + +1. Open the workspace file (`platforms/ios/HelloWorld.xcworkspace`) from Xcode, _or_ from the command line: + + ```bash + $ open ./platforms/ios/HelloWorld.xcworkspace/ + ``` + +2. Make sure the `HelloWorld` project is selected in the left panel (1). + +  + +3. Select the intended device from the toolbar's __Scheme__ menu, such + as the iPhone 7 Plus Simulator as highlighted in (2) + +4. Press the __Run__ button (3) in the same toolbar to the + left of the __Scheme__. That builds, deploys, and runs the + application in the simulator. A separate simulator application opens + to display the app: + +  + + Only one simulator may run at a time, so if you want to test the app + in a different simulator, you need to quit the simulator application + and run a different target within Xcode. + +Xcode comes bundled with simulators for the latest versions of iPhone +and iPad. Older versions may be available from the __Xcode → +Preferences... → Components__ panel. + +### Deploying to Device + +For details about various requirements to deploy to a device, refer +to the _Launch Your App On Devices_ section of +Apple's +[About App Distribution Workflows](https://developer.apple.com/library/prerelease/ios/documentation/IDEs/Conceptual/AppDistributionGuide/Introduction/Introduction.html). +Briefly, you need to do the following before deploying: + +1. Create a _Provisioning Profile_ within the + [iOS Provisioning Portal](https://developer.apple.com/ios/manage/overview/index.action). + You can use its _Development Provisioning Assistant_ to create and + install the profile and certificate Xcode requires. + +2. Verify that the _Code Signing Identity_ setting within the _Code Signing_ section + within the build settings is set to your provisioning profile + name. + +To deploy to the device: + +1. Use the USB cable to plug the device into your Mac. + +2. Select the name of the project in the Xcode window's __Scheme__ + drop-down list. + +3. Select your device from the __Device__ drop-down list. If it is + plugged in via USB but still does not appear, press the + __Organizer__ button to resolve any errors. + +4. Press the __Run__ button to build, deploy and run the application + on your device. + +## Signing an App + +First, you should read through the [Code Signing Support Page](https://developer.apple.com/support/code-signing/) +and the [App Distribution Workflows](https://developer.apple.com/library/prerelease/ios/documentation/IDEs/Conceptual/AppDistributionGuide/Introduction/Introduction.html). + +### Using Flags + +To sign an app, you need the following parameters: + +| Parameter | Flag | Description +|--------------------------|--------------------------|----------------------------------- +| Code Sign Identity | `--codeSignIdentity` | Code signing identity to use for signing. It can be created with Xcode and added to your keychain. Starting with Xcode 8 you should use `--codeSignIdentity="iPhone Developer"` both for `debug` and `release`. +| Provisioning Profile | `--provisioningProfile` | GUID of the provisioning profile to be used for signing. It is copied here on your Mac: ```~/Library/MobileDevice/Provisioning\ Profiles/```. Opening it in a text editor, you can find the GUID which needs to be specified here. +| Code Sign Resource Rules | `--codesignResourceRules`| (Optional) Used to control which files in a bundle should be sealed by a code signature. For more details, read [The OS X Code Signing In Depth article](https://developer.apple.com/library/mac/technotes/tn2206/_index.html#//apple_ref/doc/uid/DTS40007919-CH1-TNTAG206) +| Development Team | `--developmentTeam` | This is new for Xcode 8. The development team ([Team ID](https://developer.apple.com/account/#/membership/)) to use for code signing. You would use this setting and a simplified Code Sign Identity (i.e. just 'iPhone Developer') to sign your apps, you do not need to provide a Provisioning Profile. +| Packaging Type | `--packageType` | This will determine what type of build is generated by Xcode. Valid options are `development` (the default), `enterprise`, `ad-hoc`, and `app-store`. + +### Using build.json + +Alternatively, you could specify them in a build configuration file (`build.json`) +using the `--buildConfig` argument to the same commands. Here's a sample of a +build configuration file: + +Xcode 8 and iOS 10: + +```json +{ + "ios": { + "debug": { + "codeSignIdentity": "iPhone Developer", + "developmentTeam": "FG35JLLMXX4A", + "packageType": "development", + "buildFlag": [ + "EMBEDDED_CONTENT_CONTAINS_SWIFT = YES", + "ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES=NO", + "LD_RUNPATH_SEARCH_PATHS = \"@executable_path/Frameworks\"" + ] + }, + "release": { + "codeSignIdentity": "iPhone Developer", + "developmentTeam": "FG35JLLMXX4A", + "packageType": "app-store", + "buildFlag": [ + "EMBEDDED_CONTENT_CONTAINS_SWIFT = YES", + "ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES=NO", + "LD_RUNPATH_SEARCH_PATHS = \"@executable_path/Frameworks\"" + ] + } + } +} +``` + +Earlier versions: + +```json +{ + "ios": { + "debug": { + "codeSignIdentity": "iPhone Development", + "provisioningProfile": "926c2bd6-8de9-4c2f-8407-1016d2d12954", + "developmentTeam": "FG35JLLMXX4A", + "packageType": "development" + }, + "release": { + "codeSignIdentity": "iPhone Distribution", + "provisioningProfile": "70f699ad-faf1-4adE-8fea-9d84738fb306", + "developmentTeam": "FG35JLLMXX4A", + "packageType": "app-store" + } + } +} +``` + +## Xcode Build Flags + +If you have a custom situation where you need to pass additional build flags to Xcode -- you would use one or more `--buildFlag` options to pass these flags to `xcodebuild`. If you use an `xcodebuild` built-in flag, it will show a warning. You can also specify a `buildFlag` option in `build.json` above (the value for the `buildFlag` key is a string or an array of strings). + + cordova build --device --buildFlag="MYSETTING=myvalue" --buildFlag="MY_OTHER_SETTING=othervalue" + cordova run --device --buildFlag="DEVELOPMENT_TEAM=FG35JLLMXX4A" --buildFlag="-scheme TestSchemeFlag" + +## Debugging + +For details on the debugging tools that come with Xcode, see this [article](https://developer.apple.com/support/debugging) +and this [video](https://developer.apple.com/videos/play/wwdc2014-413/). + +### Open a Project within Xcode + +Cordova for iOS projects can be opened in Xcode. This can be useful if +you wish to use Xcode built in debugging/profiling tools or if you are +developing iOS plugins. Please note that when opening your project in Xcode, +it is recommended that you do NOT edit your code in the IDE. This will edit the code +in the ```platforms``` folder of your project (not ```www```), and changes are liable to be overwritten. +Instead, edit the ```www``` folder and copy over your changes by running ```cordova build```. + +Plugin developers wishing to edit their native code in the IDE should use the ```--link``` flag when adding their +plugin to the project via cordova plugin add. This will link the files so that changes to the plugin files in the +platforms folder are reflected in your plugin's source folder (and vice versa). + +Once the ios platform is added to your project and built using ```cordova build```, you can open it from +within Xcode. Double-click to open the `${PROJECT_NAME}/platforms/ios/${PROJECT_NAME}.xcworkspace` +file or open Xcode from your terminal: + +```bash +$ open -a Xcode platforms/ios +``` + +The screen should look like this: + + + +## Platform Centered Workflow + +cordova-ios includes a number of scripts that allow the platform to be used +without the full Cordova CLI. This development path may offer you a greater +range of development options in certain situations than the cross-platform cordova CLI. +For example, you need to use shell tools when deploying a custom +Cordova WebView alongside native components. Before using this +development path, you must still configure the SDK environment +as described in [Requirements and Support](#link-requirements-and-support) +above. + +For each of the scripts discussed below, refer to + [Cordova CLI Reference][cli] for more information on their +arguments and usage. Each script has a name that matches the corresponding CLI +command. For example, `cordova-ios/bin/create` is equivalent to +`cordova create`. + +To get started, either download the cordova-ios package from +[npm](https://www.npmjs.com/package/cordova-ios) or +[Github](https://github.com/apache/cordova-ios). + +To create a project using this package, run the `create` script in the `bin` +folder: + +```bash +$ cordova-ios/bin/create ... +``` + +To run the app, use the `run` script in the `bin` folder: + +```bash +$ cordova-ios/bin/run +``` + +The created project will have a folder named `cordova` inside that contains +scripts for the project-specific Cordova commands (e.g. `run`, `build`, etc.). +Additionally, The project will feature a structure different from that of a +normal Cordova project. Notably, `/www` is moved to `/assets/www`. + +To install plugins in this project, use the [Cordova Plugman Utility](../../../plugin_ref/plugman.html). + +## Upgrading + +Refer to [this](./upgrade.html) article for instructions to upgrade your ```cordova-ios``` version. + + +(Mac®, OS X®, Apple®, Xcode®, App Storeâ , iPad®, iPhone®, iPod® and Finder® are Trademarks of Apple Inc.) + +[cli]: ../../../reference/cordova-cli/index.html http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/5ad93d20/www/docs/en/7.x/guide/platforms/ios/plugin.md ---------------------------------------------------------------------- diff --git a/www/docs/en/7.x/guide/platforms/ios/plugin.md b/www/docs/en/7.x/guide/platforms/ios/plugin.md new file mode 100644 index 0000000..ff5cbba --- /dev/null +++ b/www/docs/en/7.x/guide/platforms/ios/plugin.md @@ -0,0 +1,267 @@ +--- +license: > + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +title: iOS Plugin Development Guide +toc_title: iOS +--- + +# iOS Plugin Development Guide + +This section provides details for how to implement native plugin code +on the iOS platform. Before reading this, see [Plugin Development Guide][plugin-dev] for +an overview of the plugin's structure and its common JavaScript +interface. This section continues to demonstrate the sample _echo_ +plugin that communicates from the Cordova webview to the native +platform and back. + +An iOS plugin is implemented as an Objective-C class that extends the +`CDVPlugin` class. For JavaScript's `exec` method's `service` +parameter to map to an Objective-C class, each plugin class must be +registered as a `<feature>` tag in the named application directory's +`config.xml` file. + +## Plugin Class Mapping + +The JavaScript portion of a plugin uses the `cordova.exec` method as +follows: + +```javascript +exec(<successFunction>, <failFunction>, <service>, <action>, [<args>]); +``` + +This marshals a request from the `UIWebView` to the iOS native side, +effectively calling the `action` method on the `service` class, with +the arguments passed in the `args` array. + +Specify the plugin as a `<feature>` tag in your Cordova-iOS +application's project's `config.xml` file, using the `plugin.xml` file +to inject this markup automatically, as described in [Plugin Development Guide][plugin-dev]: + +```xml +<feature name="LocalStorage"> + <param name="ios-package" value="CDVLocalStorage" /> +</feature> +``` + +The feature's `name` attribute should match what you specify as the +JavaScript `exec` call's `service` parameter. The `value` attribute +should match the name of the plugin's Objective-C class. The `<param>` +element's `name` should always be `ios-package`. If you do not follow +these guidelines, the plugin may compile, but Cordova may still not be +able to access it. + +## Plugin Initialization and Lifetime + +One instance of a plugin object is created for the life of each +`UIWebView`. Plugins are not instantiated until they are first +referenced by a call from JavaScript, unless `<param>` with an `onload` +`name` attribute is set to `"true"` in `config.xml`. For example, + +```xml +<feature name="Echo"> + <param name="ios-package" value="Echo" /> + <param name="onload" value="true" /> +</feature> +``` + +Plugins should use the `pluginInitialize` method for their startup logic. + +Plugins with long-running requests or background activities such as media +playback, listeners, or that maintain internal state should implement +the `onReset` method to cancel those long-running requests or to clean up +after those activities. +The method runs when the `UIWebView` navigates to a new page or refreshes, which +reloads the JavaScript. + +## Writing an iOS Cordova Plugin + +A JavaScript call fires off a plugin request to the native side, and +the corresponding iOS Objective-C plugin is mapped properly in the +`config.xml` file, but what does the final iOS Objective-C plugin +class look like? Whatever is dispatched to the plugin with +JavaScript's `exec` function is passed into the corresponding plugin +class's `action` method. A plugin method has this signature: + +```objective_c +- (void)myMethod:(CDVInvokedUrlCommand*)command +{ + CDVPluginResult* pluginResult = nil; + NSString* myarg = [command.arguments objectAtIndex:0]; + + if (myarg != nil) { + pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK]; + } else { + pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR messageAsString:@"Arg was null"]; + } + [self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId]; +} +``` + +For more details, see + [CDVInvokedUrlCommand.h][CDVInvokedUrlCommand.h], [CDVPluginResult.h][CDVPluginResult.h], +and [CDVCommandDelegate.h][CDVCommandDelegate.h]. + +## iOS CDVPluginResult Message Types + +You can use `CDVPluginResult` to return a variety of result types back to +the JavaScript callbacks, using class methods that follow this pattern: + +```objective_c ++ (CDVPluginResult*)resultWithStatus:(CDVCommandStatus)statusOrdinal messageAs... +``` + +You can create `String`, `Int`, `Double`, `Bool`, `Array`, +`Dictionary`, `ArrayBuffer`, and `Multipart` types. You can also leave +out any arguments to send a status, or return an error, or even choose +not to send any plugin result, in which case neither callback fires. + +Note the following for complex return values: + +- `messageAsArrayBuffer` expects `NSData*` and converts to an + `ArrayBuffer` in the JavaScript callback. Likewise, any + `ArrayBuffer` the JavaScript sends to a plugin are converted to + `NSData*`. + +- `messageAsMultipart` expects an `NSArray*` containing any of the + other supported types, and sends the entire array as the `arguments` + to your JavaScript callback. This way, all of the arguments are + serialized or deserialized as necessary, so it is safe to return + `NSData*` as multipart, but not as `Array`/`Dictionary`. + +## Echo iOS Plugin Example + +To match the JavaScript interface's _echo_ feature described in +Application Plugins, use the `plugin.xml` to inject a `feature` +specification to the local platform's `config.xml` file: + +```xml +<platform name="ios"> + <config-file target="config.xml" parent="/*"> + <feature name="Echo"> + <param name="ios-package" value="Echo" /> + </feature> + </config-file> +</platform> +``` + + +Then we would add the following `Echo.h` and `Echo.m` files to the +`Plugins` folder within the Cordova-iOS application directory: + + +```objective_c +/********* Echo.h Cordova Plugin Header *******/ + +#import <Cordova/CDVPlugin.h> + +@interface Echo : CDVPlugin + +- (void)echo:(CDVInvokedUrlCommand*)command; + +@end + +/********* Echo.m Cordova Plugin Implementation *******/ + +#import "Echo.h" +#import <Cordova/CDVPlugin.h> + +@implementation Echo + +- (void)echo:(CDVInvokedUrlCommand*)command +{ + CDVPluginResult* pluginResult = nil; + NSString* echo = [command.arguments objectAtIndex:0]; + + if (echo != nil && [echo length] > 0) { + pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK messageAsString:echo]; + } else { + pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR]; + } + + [self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId]; +} + +@end +``` + +The necessary imports at the top of the file extends the class from +`CDVPlugin`. In this case, the plugin only supports a single `echo` +action. It obtains the echo string by calling the `objectAtIndex` +method get the first parameter of the `arguments` array, which +corresponds to the arguments passed in by the JavaScript `exec()` +function. + +It checks the parameter to make sure it is not `nil` or an empty +string, returning a `PluginResult` with an `ERROR` status if so. If +the parameter passes the check, it returns a `PluginResult` with an +`OK` status, passing in the original `echo` string. Finally, it sends +the result to `self.commandDelegate`, which executes the `exec` +method's success or failure callbacks on the JavaScript side. If the +success callback is called, it passes in the `echo` parameter. + +## iOS Integration + +The `CDVPlugin` class features other methods that your plugin can +override. For example, you can capture the [pause][PauseEvent], [resume][ResumeEvent], app +terminate and `handleOpenURL` events. See the +[CDVPlugin.h][CDVPlugin.h] and [CDVPlugin.m][CDVPlugin.m] +classes for guidance. + +## Threading + +Plugin methods ordinarily execute in the same thread as the main +interface. If your plugin requires a great deal of processing or +requires a blocking call, you should use a background thread. For +example: + +```objective_c +- (void)myPluginMethod:(CDVInvokedUrlCommand*)command +{ + // Check command.arguments here. + [self.commandDelegate runInBackground:^{ + NSString* payload = nil; + // Some blocking logic... + CDVPluginResult* pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK messageAsString:payload]; + // The sendPluginResult method is thread-safe. + [self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId]; + }]; +} +``` + +## Debugging iOS Plugins + +To debug on the Objective-C side, you need Xcode's built-in debugger. +For JavaScript, you can attach Safari to the app running within the iOS Simulator/Device. + +## 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](../../appdev/whitelist/index.html). If you forget, an error is + logged in the Xcode console. + +[CDVInvokedUrlCommand.h]: https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/Public/CDVInvokedUrlCommand.h +[CDVPluginResult.h]: https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/Public/CDVPluginResult.h +[CDVCommandDelegate.h]: https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/Public/CDVCommandDelegate.h +[CDVPlugin.h]: https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/Public/CDVPlugin.h +[CDVPlugin.m]: https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/Public/CDVPlugin.m +[ResumeEvent]: ../../../cordova/events/events.html#resume +[PauseEvent]: ../../../cordova/events/events.html#pause --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@cordova.apache.org For additional commands, e-mail: commits-h...@cordova.apache.org
