cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From agri...@apache.org
Subject docs commit: [CB-2443] Add docs for pluginInitialize and for onload="true"
Date Fri, 15 Feb 2013 19:06:45 GMT
Updated Branches:
  refs/heads/master 7dbbb336a -> 3099f36df


[CB-2443] Add docs for pluginInitialize and for onload="true"

Applies to the iOS plugin guide.


Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/3099f36d
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/3099f36d
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/3099f36d

Branch: refs/heads/master
Commit: 3099f36dfb0afb2bb522c0eac35e9c002ac328ac
Parents: 7dbbb33
Author: Andrew Grieve <agrieve@chromium.org>
Authored: Fri Feb 15 14:05:38 2013 -0500
Committer: Andrew Grieve <agrieve@chromium.org>
Committed: Fri Feb 15 14:05:38 2013 -0500

----------------------------------------------------------------------
 docs/en/edge/guide/plugin-development/ios/index.md |   17 +++++++++++---
 1 files changed, 13 insertions(+), 4 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/3099f36d/docs/en/edge/guide/plugin-development/ios/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/plugin-development/ios/index.md b/docs/en/edge/guide/plugin-development/ios/index.md
index 0d77c26..e5bfa88 100644
--- a/docs/en/edge/guide/plugin-development/ios/index.md
+++ b/docs/en/edge/guide/plugin-development/ios/index.md
@@ -31,14 +31,23 @@ The JavaScript portion of a plugin always uses the `cordova.exec` method
as foll
 
 This will marshal a request from the UIWebView to the iOS native side, more or less boiling
down to calling the `action` method on the `service` class, with the arguments passed in the
`args` Array. 
 
-Plugins with long-running requests, background activity (e.g. playing media), listeners or
internal state should implement the `onReset` method and stop or clean up those activities.
This method is run when the `UIWebView` navigates to a new page or refreshes, which reloads
the Javascript.
-
 The plugin must be added under the `<plugins>` tag of the `config.xml` file in your
Cordova-iOS application's project folder.
 
     <plugin name="service_name" value="PluginClassName" />
 
 The key `service_name` should match what you use in the JavaScript `exec` call, and the value
will be the name of the Objective-C class of the plugin. Without this added, the plugin may
compile but will not be 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.:
+
+    <plugin name="Echo" value="Echo" onload="true" />
+
+There is *no* designated initializer for plugins. Instead, plugins should use the `pluginInitialize`
method for their start-up logic.
+
+Plugins with long-running requests, background activity (e.g. playing media), listeners or
internal state should implement the `onReset` method and stop or clean up those activities.
This method is run when the `UIWebView` navigates to a new page or refreshes, which reloads
the Javascript.
+
+
 ## Writing an iOS Cordova Plugin
 
 We have JavaScript fire off a plugin request to the native side. We have the iOS Objective-C
plugin mapped properly via the `config.xml` file. So what does the final iOS Objective-C Plugin
class look like?
@@ -128,7 +137,7 @@ Finally, we send the result to `self.commandDelegate`, which will execute
the Ja
 
 ## Threading
 
-Although UIWebViews run on a dedicated thread, plugin methods are executed on the UI thread.
If your plugin requires a non-trivial amount of processing or requires a blocking call, you
should make use of a background thread. An example:
+Plugin methods are executed on the UI thread. If your plugin requires a non-trivial amount
of processing or requires a blocking call, you should make use of a background thread. An
example:
 
     - (void)myPluginMethod:(CDVInvokedUrlCommand*)command
     {
@@ -169,4 +178,4 @@ The **old (deprecated)** signature is:
 
         - (void) myMethod:(NSMutableArray*)arguments withDict:(NSMutableDictionary*)options;
 
-The options parameter for the Objective-C plugin method is being deprecated, and it should
not be used. For legacy reasons - the last JavaScript object passed in the args Array will
be passed in as the options dictionary of the method in Objective-C. You must make sure that
any JavaScript object that is passed in as an element in the args array occurs as the last
item in the Array, if not it will throw off the array index of all subsequent parameters of
the Array in Objective-C. Only one JavaScript object is supported for the options dictionary,
and only the last one encountered will be passed to the native method. It is because of these
error-prone reasons that they are being deprecated.
+The options parameter for the Objective-C plugin method is deprecated, and it should not
be used. For legacy reasons - the last JavaScript object passed in the args Array will be
passed in as the options dictionary of the method in Objective-C. You must make sure that
any JavaScript object that is passed in as an element in the args array occurs as the last
item in the Array, if not it will throw off the array index of all subsequent parameters of
the Array in Objective-C. Only one JavaScript object is supported for the options dictionary,
and only the last one encountered will be passed to the native method. It is because of these
error-prone reasons that they are being deprecated.


Mime
View raw message