Github user jsoref commented on a diff in the pull request:
https://github.com/apache/cordova-plugin-globalization/pull/18#discussion_r15603025
--- Diff: src/blackberry10/native/readme.txt ---
@@ -0,0 +1,406 @@
+Template for BlackBerry 10 Cordova Plugins
+==========================================
+
+BlackBerry 10 Cordova Plugins create a bridge between JavaScript code in
an HTML5 application and C/C++ and/or Qt code in the plugin, allowing access to
native libraries, which are not part of the HTML5 specification. The BlackBerry
10 Plugins included with the Cordova SDK also follow the same or similar format
as shown in this template.
+
+Plugins offer a JavaScript API which communicates through an interface to
native methods. This interface can send and receive data through strings, or
data that can be represented as a string such as JSON and Base64.
+
+This template includes examples for communicating in several ways:
+
+1. A function that returns a string from a native method.
+2. A function that sends a string to, and gets another back, from a native
method.
+3. A function that calls a native method with a JSON object input, and
provides a callback function, which is fired by a native method, and receives
JSON data.
+4. Defining a property that is linked to native methods when retrieved or
set.
+5. Starting and Stopping a native thread, with a callback function that
receives events from the native thread.
+
+## Building and Testing the Sample
+
+The included sample is the default Cordova Hello World application created
by the "cordova create" command. It is ready to run on your simulator simply by
calling "cordova run" in the sample directory. It has been altered to include a
div in "index.html" for displaying the test data, and a set of test functions
in "js/index.js" to excercise the template API and display some results.
+
+To use the plugin in another project, that's been created with Cordova,
run "cordova plugin add <path to this Template folder>/plugin"
+
+Then you can call the methods with the namespace
"community.templateplugin", and that should appear in WebInspector as an Object
so you can see what APIs are available. The example APIs included will be
detailed later in this guide.
+
+## Starting a Plugin from the Template
+
+Copy the Template folder to a location on your computer to start working
with it.
+
+### Momentics NDK setup
+
+You can either import the project from the Template folder, or use the New
Project Wizard in Momentics to create a starter project.
+
+#### Using the New Project Wizard
+
+1. Open the Momentics IDE. Navigate to the workbench and from the program
menu select File -> New -> New BlackBerry Project.
+2. Choose Native Extension from the Project Type list, then select
BlackBerry WebWorks, and click Next.
+3. Change the project name to "Template" and click Finish.
+4. Right click your project again and select Build Configurations ->
Manage..., then click New.
+5. Enter "device" for the name and choose to copy settings from
Device-Release.
+6. Repeat to create a configuration named "simulator", and choose to copy
settings from Simulator-Debug.
+7. You will need to copy the device and simulator folders to the
"/plugin/src/blackberry10/native" directory where you copied the Template, each
time you build. You can configure a post build command if you'd like, in the
project properties.
+
+#### Importing the Template
+
+1. Open the Momentics IDE. Navigate to the workbench and from the program
menu
+select File -> Import and choose "Existing Projects into Workspace".
+2. Choose "Select root directory: " and browse to the
"/plugin/src/blackberry10/native" directory where you copied the Template.
Select the Template project in the Projects list and uncheck "Copy projects
into workspace". Click Finish.
+3. Follow these next steps to build the template plugin to be sure the
setup is working.
+
+#### How to build your native Plugin
+
+1. Right click your project and select the Clean Project option.
+2. Right click your project again and select Build Configurations -> Build
Selected... .
+3. A window will appear that shows all the available build configurations
+for the project. Select "device" and "simulator" and click ok.
+4. You should see the shared libraries (libTemplate.so files) generated in
the folders for each Build Configuration that you selected.
+
+### Using the Plugin in an Application
+
+To use the plugin in another project, that's been created with Cordova,
run "cordova plugin add <path to this Template folder>/plugin".
+That will copy the plugin into the project, and update the www/config.xml
file to include the feature as below:
+
+
+<feature name="community.templateplugin" value="community.templateplugin"
/>
+
+
+All the methods in the plugin will be prefixed by that feature name, so a
method called "test()" supplied in the "community.templateplugin" plugin will
be called in JavaScript like so:
+
+
+community.templateplugin.test();
+
+
+Depending on the plugin, these methods can also have return values, take
arguments, or supply callback methods.
+
+To remove the plugin, run "cordova plugin rm community.templateplugin"
+
+### Modifying the Template Plugin
+
+#### Namespace
+Choose a namespace for your application that is concise and descriptive.
Use community.pluginname as the general format. Change all the occurences of
the name in plugin/plugin.xml. Update the "ID variable in client.js to match
the namespace.
+
+#### JNEXT plugin files
+index.js and the template_js.cpp/hpp files are linked by the name of the
library and the name of the class in the library. Change the Class Name from
TemplateJS to something that matches the new plugin's role. Change the project
name in the NDK as well. Then you will need to update the references in
index.js to match the new values:
+
+Find self.init = function () {}, and change "libTemplate" to the new
project name, but keep the "lib" prefix. Then change the reference to
"TemplateJS" to use the new Class Name.
+
+
+self.init = function () {
+ if (!JNEXT.require("libTemplate")) {
+ return false;
+ }
+
+ self.m_id = JNEXT.createObject("libTemplate.TemplateJS");
+
+ //...
+};
+
+#### Update .js files
+There are many other places where "template" is used in file names and
methods in the JavaScript files. These can be changed to better reflect the new
plugin API. Note carefully where index.js calls the JNEXT.Template object so
that you don't break the chain.
+
+#### Change NDK files
+In the files template_ndk.hpp and template_ndk.cpp, there are plenty of
uses of "Template" and "template" which can be changed to match the new plugin.
+
+#### Rebuild
+When making changes, rebuild regularly so you don't make a really hard to
find typo.
+
+Follow the steps above to:
+1. Build the native portion, and
+2. Use the plugin in your test app.
+
+## Architecture of a Plugin
+
+Plugins are organized into several files, each with a specific role.
+
+1. plugin.xml - defines the namespace of the plugin lists the files that
need to be included.
+2. client.js - the client file defines the API that can be called by an
application. It calls to functions in index.js using the Cordova framework. It
also connects callback functions to the events that fire them.
+3. index.js - This is the main controller of the plugin. It receives calls
from the client.js through Cordova, and calls the appropriate methods in the
included JNEXT object, which does the communication to the Native side of JNEXT.
+4. template_js.hpp - C++ header for the JNEXT code. You should rarely have
to edit this aside from renaming.
+6. template_js.cpp - C++ code for the JNEXT plugin. Besides renaming, the
primary editing of this will be to edit the InvokeMethod function to call the
appropriate methods in template_ndk.cpp, given the command and callbackId sent
in from index.js and the Template object.
+7. template_ndk.hpp - C++ header for the native code. Where you will need
to list method signatures for the extenion methods called from the
template_js.cpp file, and any private methods or variables.
--- End diff --
sp: extenion
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
