cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jsoref <>
Subject [GitHub] cordova-plugin-globalization pull request: BB10 implementation
Date Wed, 30 Jul 2014 18:33:31 GMT
Github user jsoref commented on a diff in the pull request:
    --- 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
    +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 ( 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
    +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 or file a JIRA ticket
with INFRA.

View raw message