BlackBerry has a great invocation framework allowing you to easily interact with Applications on BlackBerry 10, reuse code from other applications and exchange information between applications.

But when trying to use invocation cross-platform (iOS, Android, BB10) , it’s a separate implementation for each and every type of Platform.

Cross-Platform invocation

There is a way to be able to talk cross-platform with invocation that even works on the web. Connecting for instance emails, web content and other applications with your application.

The way to do this is using the App URL method.

You can construct a URL matching pattern, which will allow your application to be invoked when called with a URL scheme. This can be both a Web URL scheme: http:// or an application specific URL scheme: <myapp>://

App URL’s are widely supported by the industry and a good starting point to learn more about the is at: http://appurl.org/ . There is already a wide support from the Applications themselves. Just take a look at http://appurl.org/apps/ Once you have implemented App URL’s in your own app you can add yours to the list.

BlackBerry 10 Implementation

To implement an App URL in BlackBerry, you just need to register an invocation target that specifies the wanted URL scheme. In the bar-descriptot.xml add a new target by just adding the following lines.

One very practical example to use App URLs is to use it to configure applications after they have been deployed to the device. There are quite a number of applications that need to be configured to be able to be used. In many cases this is to ensure the Application points to the right internal systems to get its data from.

As these applications might be on multiple Platforms (iOS, Android, BlackBerry), it’s hard to come to a single method to distribute these configuration details.

This is where an App URL can help. By emailing the users of the applications an email with an App URL that actually contains the configuration for the application, that is the same on all platforms.

And in our code we handle the request with the following code, where we process the query string of the URL to extract the actual configuration details.

The end result of this code is when you send a user the following App URL for instance in an email and set it to a clickable link: configdemo://configuration?host=www.blackberry.com&port=443&https=yes&email=sample@blackberry.com&password=12345678

E.g.

“To configure your Business App click HERE”

The App would then be launched and show the following information:

We’ve used clear text in the query string for demo purposes. But the recommendation is to encrypt the actual payload that only the Application could decrypt to not allow malware to send wrong configuration information.

This is the second follow-up post from the UCOSP program this past fall. Besides creating new WebWorks plugins, some of our work has been to maintain the ones we have built in previous terms. Tim, from Thomson Rivers University in BC, spent his time working on a few different plugins. Here’s his account of the term:

The opportunity to contribute to a BlackBerry WebWorks plugin made me learn two important things that change the way I code: The importance of communication and never taking anything for granted.

Since starting to learn how to code, I have always coded alone and I rarely had the chance to sit with others and code together. If I encountered any problem I would look up the answer myself. In mid-September, I attended the code sprint in Toronto. During the sprint, people exchanged ideas about how to achieve the goal. Questions were asked and answered quickly when someone had encountered them before. At that moment I realized how efficient it was, and was enjoying being part of it. Even though the sprint is over and we are not co-located anymore, we continue meeting on a weekly basis, where members of the team share their progress and issues. I would say this is very important in the process of learning, thus I am happy I get to understand it through this opportunity.

BarcodeScanner, ExtractZipFile, and LowLatencyAudio are the three plugins that I worked on this term. Tasks like bug fixes, new features, and function modifications are what I spent time on. In order to modify the code, I needed to understand the code. I needed to know which part of the code is doing what job and understand why the former authors coded it in that way. During the process of understanding, I learned that things are not always as they appear. Here is one example: You would expect the barcode scanner to work on any data string, but instead it gave you an error when there is was a space in the string, and returned nothing to the user. When I examined the code, I thought native C++ code that created the JSON return object might be stripping off everything past the first space. Eventually I found out the bug was never in that code, but was in how the scan result was parsed and interpreted. Such simple mistake can be easily overlooked if you take code for granted, thus I now pay extra attention to those details which I think should be behaving properly.

Due to Tim’s work, ExtractZipFile now supports compressing directories and multiple files, LowLatencyAudio makes more efficient use of resources, and the BarcodeScanner is fixed to scan data with spaces. In addition, we’ve been able to release a major update to the BarcodeScanner so that it uses the native camera viewfinder when scanning. If you’re interested in following along with the student project, watch #bbucosp on Twitter, and all the code will be going into the public BlackBerry repositories on GitHub. If you want to get involved yourself, contact me to get started: @timothywindsor on Twitter, https://github.com/timwindsor on GitHub.

]]>http://devblog.blackberry.com/2015/02/three-plugins-updated-by-ucosp-student/feed/0timclassictimwin1timclassicAudioMetaData WebWorks Plug-inhttp://devblog.blackberry.com/2015/02/audiometadata-webworks-plug-in/
http://devblog.blackberry.com/2015/02/audiometadata-webworks-plug-in/#commentsTue, 10 Feb 2015 16:50:02 +0000http://devblog.blackberry.com/?p=19240/ Read More]]>This past fall we worked with the UCOSP program again, with a kickoff sprint back in September, and several students joined us to work on WebWorks plugins for the term. Many of the students worked on larger projects this time and wrote blog posts at the end of the term, which was in December. As a result, we’ll gradually publish their comments in blogs over the next few weeks. The first we’ll hear from is Jim, from the University of Alberta.

While working with the BlackBerry UCOSP team, I was given the opportunity to work on a plugin that extracts ID3 metadata from mp3 files. I strode into the project thinking that it would be fairly simple; however, when it came to the time to code, everything fell apart. Given the previous examples provided by Tim, our advisor, assumptions of simple linkage of components were in my mind. However, it turned out that the license of the sample library I was supposed to use conflicted with the licenses which our plugins were based on. Besides the license conflict issue, other challenges also arose along the way. Midway into the project, Unicode handling became an issue as ID3 tags contained data that is encoded in either ISO88591 or Unicode. The data which I was working with turned out to be garbage in my test application and this had me stumped for a week or two. Besides some implementation issues, others occurred simply due to working with an unfamiliar platform. As more time was dedicated to the project problems began to be solved, I was able to produce a working plugin that fulfilled all the requirements. Finally, for the released product, the plugin takes a file path to the mp3 file the users wished to work with. In return, depending on the function called by the users, they can extract, set, as well as remove the ID3 metadata that exists on an mp3 file. However, the last functionality is a bit senseless, as the need to remove ID3 tags from mp3 files seems little to nonexistent.

In both extraction and injection of the ID3 tags, the user has the ability to only set the following:

song

title

artist

name

track

number of the song on the album

album name

year of release

genre

In the case of extraction, the data is returned in a JSON object in the following form: { “album” : “Let’s talk about love”, “artist” : “Celine Dion”, “genre” : “pop”,“title” : “My heart will go on”, “year” : “1997” }

And in the case of injection of data, the same formatted JSON data is needed to be passed into the function with the following keys editable: “title”, “album”, “artist”, “year”, “genre”, “track”.

Even though current version of release is functional, it is always possible to add new features. Some ideas include:

Possible optimization to the library used as it currently copy and pastes the entire file edited thus causing a delay in operation.

Further testing for specific edge cases that might have been forgotten to handle.

Overall the UCOSP program provided me with the chance to see what is like working with students across Canada on an open source project and I highly recommend this experience for students who are interested in contributing to open source application development.

We’ve already started a new term working with students, but we’ve got a few more updates to post about last term before we talk about their work. If you’re interested in following along with the student project, watch #bbucosp on twitter, and all the code will be going into the public BlackBerry repositories on GitHub. If you want to get involved yourself, contact me to get started: @timothywindsor on Twitter, https://github.com/timwindsor on GitHub.

Our third UCOSP project this summer was the Facebook Connect plugin. Like our other project, the Google Analytics plugin, the Facebook Connect plugin allows interaction with a 3rd party web service, and we were able to do it in JavaScript without going to C++. Zain took on this plugin and here’ what he had to say about his experience on the project:

For as long as I can remember, I’ve been very passionate about building things. Lego and I were best of friends when I was young. In middle school I fell in love with electronics. I spent most of my weekends surrounded by batteries, motors, switches, wires, screwdrivers etc., building my ideas. Then in my first year of University, I was introduced to Software Development and being someone with a passion for building things and brining ideas to life, I instantly fell in love with it. But it wasn’t until I learned about the concept of open source development that this love really took off.

Open source software, like everything else has its pros and cons. Depending on the type of project you’re working and the situation you’re in, one may out-weigh the other. For me it has always been the most preferred way to build and collaborate on projects. Open sourcing software projects not only allow you to share your ideas to a broader audience and get their opinions and input, but it also allows other developers to contribute to and extend your ideas. And since this works both ways, you’re also able to work on and extend other people’s ideas and projects. In general, this leads to a ton of improvement, new ideas and learning.

This summer, as my computer science degree was approaching its end, I decided that I wanted to do a course that lets me focus completely on software development, preferably an open source project where I could work on building a cool idea or an app. I came across UCOSP (Undergraduate Capstone Open Source Project) program and enrolled in it via my University and chose to work with BlackBerry on developing Cordova/WebWorks plugins for BlackBerry 10.

For those of you not familiar with Cordova and BlackBerry WebWorks, in a nutshell, they are frameworks that provide mobile developers with a set of device APIs, allowing them to access native device functionality (Camera, Speakers etc.) using JavaScript. Super cool isn’t it? The beauty of this is that it allows developers to build apps completely in HTML5, CSS and JavaScript without having to write any native code at all. This also proves to be convenient because developers can now, with minimal effort, port their apps to the different platforms, without worrying about the look and feel and platform dependencies.

My project for this course was building the Facebook plugin for Cordova/WebWorks for BlackBerry 10. A WebWorks plugin generally consists of two parts, the Client which is the API interface for the developers using this plugin and the Server which takes care of invoking the native code. Since BlackBerry wrote BlackBerry 10’s Facebook App themselves, there exists no Native SDK and therefore I had to write this complete plugin in JavaScript. I initially tried a few different approaches, using a static copy of Facebook’s JavaScript SDK etc. but finally settled on using REST calls as this would take away the headache of worrying about the changes that Facebook would be making in the future. The working copy of the plugin can be found at in the Community API repo. I plan to work on this even after the completion of this course and in the process learn and further improve my technical skills. Kudos to BlackBerry for letting me work with them and to Tim Windsor for his amazing mentorship :)

Zain was able to get the plugin working for BlackBerry 10 but there’s more to be done before we can upstream it to PhoneGap Build. This coming term we’ll finish that up and send it upstream. If you’re interested in following along with the student project, watch #bbucosp on twitter, and all the code will be going into the public BlackBerry repositories on GitHub. If you want to get involved yourself, contact me to get started: @timothywindsor on twitter, https://github.com/timwindsor on GitHub.

Back in mid-September we met in Toronto again at Mozilla’s very nice office, to kick off a new term of UCOSP. With six students from four universities and one volunteer from another, the team is ready to do some very cool things this term. While earning course credit for their degrees, our students will be writing open source code and contributing it publicly for other BlackBerry developers to use. For a report of how the weekend event went, here is one of the students, Stefan from Thomson Rivers University in BC:

After arriving in Toronto Thursday, after a long day of travel (for some), the students of UCOSP got together at the University of Toronto for a meet and greet. We played a few ice breaker games to help encourage some interaction, led by Karen Reid; had a presentation by Raquel Urtasun who introduced and promoted U of T’s graduate program; followed by general mingling.

Friday morning we went to the office of our host, Mozilla. We were given a welcome to the UCOSP by Michelle Craig, and then an overview of Mozilla and their vision by Mike Hoye. We jumped into our teams and introduced ourselves a little more. The PhoneGap team consists of: BlackBerry mentor, Tim Windsor; past UCOSP member and University of Toronto student, Kris Flores; University of Guelph student, Justin; University of Waterloo student, Yifan; University of Alberta students, Tanya and Jim; and Thompson Rivers University students, Stefan and Tim.

During our visit, we were fortunate to be provided a tour of the Mozilla facility and got to see the team members in Toronto at work in their real-world environment. It was quite exciting to see their development process, the development rooms filled with white boards and Post-it notes that outlined their goals and tasks currently in progress or discussion. As we are all potential developers, it was invaluable to see the real-world interactions of the members. Different areas of the office building provided people with the ability to get away from their desks and work in a shared space in the office or to just either relax in a non-work environment or even take up a game of Ping-Pong.

The tasks were divided up by interest, and then the team members started right into them. As we all learned, there is a learning curve with the introduction of a new API as well as the whole development of a new plugin for the BlackBerry 10 platform. Each team member was provided with a new Z10 or Q10 for testing purposes. This will enable us to test the plugins on actual devices and realize the effect of our efforts immediately on the targeted environment.

The initial tasks that we decided upon ranged from finding and fixing a bug in the Bar-code scanner; finish merges for Facebook connect, Google Analytics, and Distimo SDK; support reading audio metadata; and additional support for the EmailSender plugin. At the end of our day on Sunday, we were all getting much more comfortable with the environment, although there are still some areas of the development process that are not 100% clear, this will all be overcome with time and practice. I look forward in getting to understand the processes of our project and am excited as to what the term will bring.

The students are all hard at work on their chosen projects and great progress has already been made since the opening sprint. If you’re interested in following along with the student project, all the code will be going into the public BlackBerry repositories on GitHub. If you want to get involved yourself, contact me to get started: @timothywindsor on twitter, https://github.com/timwindsor on GitHub.

Our first ever summer term with the Canadian University program called UCOSP, has just finished. This is the program where upper year university students contribute to open source projects for a term and get course credit. UCOSP decided to try a summer term with a few projects and students this year, and BlackBerry was asked to participate. We ended up with just 3 students this time and we continued to work on porting plugins to the BlackBerry 10 platform. One of those projects was a Google Analytics plugin, done by Andrew. Here are Andrew’s thoughts on the term:

This summer term I enrolled in UofT CSC494, which gave students an opportunity to work on open source projects coordinated by UCOSP. I got into the BlackBerry team, along with two other students. Our task was to incorporate either pre-existing plugins from other platforms or new plugins into the new BlackBerry WebWorks community APIs .

At the beginning of the term, our mentor, Tim, and us had a two-days meet in the BlackBerry Jam Space at Communitech Hub located in Kitchener, Ontario. It was a fascinating and eye-opening experience to see all the vibrant tech companies and startups inside the building and within the neighborhood. We had the opportunity to see a few of the groups, including a visit to the local startup, Thalmic Labs, which developed the Myo(tm) gesture controlled armband. An armband that you can use to control, say, a RC-helicopter, how cool is that!

Now back on topic, my task for the project was to incorporate Google Analytics (GA) as a WebWorks community plugin. I didn’t have any previous experience in mobile apps development, so there was a particular steep learning curve. Clearly, if I had taken CSC309 in UofT, it would have helped a lot :) There were a lot of things to read to get things started, e.g. how to install debug tokens, how does the Cordova interface work, how to use WebWorks, Momentics and BB Simulator, how is the architecture of a plugin, etc. For GA in particular, Google has a public SDK for Android and iOS, but not for BB10. So in order to incorporate GA, I also needed to go through the documentation and know how to use the functionalities of GA. As it turned out, using GA wasn’t difficult, but it did have a few tricky issues. The coding itself, to incorporate the basic functionalities of GA, was not too much work, when compared to the amount of time needed to understand all those I just mentioned.

Working with this project, one idea that was surely reinforced was to test, and test often. I’m sure every student is taught and told about test-driven development, but we’ll always be tempted to write a lot of code without testing in between. With Javascript, which is used in the non-native side of a WebWorks plugin, there is no compile-time error checking so a simple typo like missing a semicolon could causes us a lot of time to debug. I certainly ran into situations where I had to remove a bigger section of new code, and re-do it in small increments in order to identify that small bug or typo I missed.

The experience working for this UCOSP BlackBerry project was a very positive one for me. While it was not easy, there were a lot of things to learn. It is definitely very different that our typical academic course projects where we may have access to lecture notes and project handouts to tell us exactly what to do. While the UCOSP project is under supervision of our mentors, the project is geared toward real-world applications. There are no notes or handouts, and it’s up to us to find the information we need, solve issues we face and ask the questions we have. It’s also rewarding knowing that our work may turn into something useful for other people in the real world.

Andrew was able to get the plugin working for BlackBerry 10 and this coming term we’ll finish up merging it into the PhoneGap Build plugin and sending it upstream. If you’re interested in following along with the student project, watch #bbucosp on twitter, and all the code will be going into the public BlackBerry repositories on GitHub. If you want to get involved yourself, contact me to get started: @timothywindsor on twitter, https://github.com/timwindsor on GitHub.

When mobilizing a company, there will be challenges to gain access to platforms, data and processes, that are siloed of in monolithic stacks and session based transports. With the connectivity and bandwidth challenges of mobility, it’s hard to build upon the traditional Enterprise Technology stacks. Mobility uses high volume, high transactional, non-session based transactions and requires a different approach.

A new paradigm

Mobility changes how we use IT services and solutions. With its 24/7 always on nature, it creates new windows of opportunities and possibilities, but it also comes with challenges for the existing Enterprise Architecture in many larger companies. Traditional Enterprise Architecture is based on high bandwidth, low transactions, session-based communications. Mobility does not have that luxury; a device with a mobile connection has limited bandwidth and doesn’t always have connectivity.

To mitigate these challenges, mobility uses non-session based, high volume transactional, small bits of communications, to reduce the overhead of dropped sessions and ensure responsiveness in communication and the actual application usage on the devices.

In mobility almost everyone is standardizing on RESTfull web API’s/ web services to provide that type of communication for mobility.

Building Bridges

Trying to pry everything out of the existing systems and build a complete new Architecture takes time and is a gradual process; while mobile needs are rising now, as they are the key for many companies to differentiate themselves, increase productivity and efficiency.

So to be able to move forward, bridges need to be built.

One of those bridges is provided by NodeJS. NodeJS is the standalone JavaScript run-time engine that also powers Google’s Chrome browser. NodeJS is great for mobile when using HTML5 as the platform to build your Enterprise Application with. You can have both JavaScript on the Server and in the Client, use the same objects and data bindings, allowing much reuse of code on both client and server.

Additionally NodeJS provides exactly the right communication profile based on http(s) for mobile and allows both great horizontal and vertical scaling, allowing for extreme high volume of transactions.

To top it off there are over 77,000 modules available for NodeJS that help to connect to your existing Enterprise Systems; Oracle, MS SQL, SAP to LDAP, Active Directory, Sharepoint and many, many others.

Crossing the bridge

Leveraging the BlackBerry Enterprise Service 10 for connectivity and security, you can use the Github sample LDAP Search.
The Sample shows how to setup and configure a NodeJS server that provides a small Web API, to do LDAP searches against your own LDAP directory (for example your corporate Active Directory), to find your colleagues.

]]>http://devblog.blackberry.com/2014/07/building-bridges-nodejs/feed/0BridgereumerdBridgeNot only can Sample Projects save time…they can save lives. Open source to the rescue!http://devblog.blackberry.com/2014/06/open-source/
http://devblog.blackberry.com/2014/06/open-source/#commentsFri, 20 Jun 2014 17:12:31 +0000http://devblog.blackberry.com/?p=18488/ Read More]]>Below is a post from Richard Balsewich (@OnlineODB)

If you have ever participated or competed in a hackathon, then you already know how much time you have to build something “real”… Not enough! So how can you turn the time-constraint in your favor? Easy… smart searching and open source and sample projects.

So from the authors that brought you the epic series “From GitHub to Production”, we are back putting our approach to the test and showing you how sample projects can save time and even save lives. We just so happen to be at a hackathon that involved the need for disaster preparedness solutions, so as soon as the contest started this is what we came up with:

We imagined a solution that involved GeoFencing capabilities that can provide alerts/messages to a user on the location or area they just entered. For example, “Fire ahead turn around” or “Medical Supplies to the left after you enter building”.

There were several technologies and capabilities we would need to accomplish this solution, for any user on any platform. So our smart searching and sample project focus was broken down into the following:

Maps and Overlays – visualization and coordinates of Points of Interest (POIs)

mBaaS:

There are tons of providers in this category to choose from both paid and free. Since the BlackBerry 10 platform offers App and Content Management for Android devices as well as an Android runtime, we decided to go with Google Cloud due to their “ready-to-deploy” cloud service and sample project. The sample application we found demonstrates the JSON data object exchange between a mobile end-point and the cloud service. Using this sample we will have a persistent way to allow admin users to enter POIs, and a place for our mobile solution and users to query.

Device Capabilities:

There are several ways to obtain a user’s current position. For this project, we focused on getting this information from the device GPS receiver. This would give us the accuracy we needed, as well as the ability to adjust the speed in which the coordinates were obtained. Since our end project will be the result of stitching together several sample projects with mixed technologies, we ventured to Cordova Geolocation to accomplish getting the user position.

Maps and Overlays:

Now you’d think this feature would be our biggest focus and be the biggest time consumer… and you’d think wrong, because we know BlackBerry’s Jim Ing (@jim_ing ). A few months back, Jim gave a demonstration on a Geofencing project he has contributed to open source that uses HTML5 and leverages Leaflet maps.
If you have not seen this demo, stop reading immediately and click HERE now!

Final Results:

Now that we had all the pieces to our puzzle, it was time to figure out what and how to stitch these pieces together. We decided the best approach would be to get a skeleton of the data flow working between the cloud and end-points first. Since this was not our first rodeo, we quickly outlined data types, transport and persistence deployment best practices for our end-points.

Backend end result: We deployed the mobile application entity and object structures to the cloud platform. This gave us our handshake of JSON objects full of meta-data for application elements, user elements, and query elements between our end-points and cloud service. We generated some dummy user and POIs that we could use to get started on the end-points.

Next, we focused on the concept of native mobile applications communicating with embedded WebViews, the basis for Cordova. Since our mapping and overlay sample project leverages web technologies, we wanted a way to expand the JavaScript libraries without having to spend time writing additional Cordova plugins. Nearly every platform offers this sort of hybrid application approach. (e.g.: BlackBerry 10 , Android , etc.)

We built most of the core features like awareness logic, hardware interaction, local persistence, app/user state and communication layer using native methods into a base native project. Then, these methods were exposed to our JavaScript libraries to provide for a more dynamic mapping experience.

Next, we updated the Geofence sample project to interact with our native base project to capture user details and our POIs. Additional logic was created to show the POIs to the user on the Overlay as well as their current position in relation to those POIs. We added some Geofences around some of the key buildings to demonstrate how exact we could be with the Overlays.

The end result was an android application deployed through BlackBerry Enterprise Service 10 to an Android Nexus 5 smartphone running BlackBerry Secure WorkSpace for Android. The application accomplished passing objects back and forth between each user and the backend. It tracked all users of the application and their whereabouts in relation to the POIs (good and bad). Although we did not win the hackathon, combining these samples to create a fully operational multi-platform mobile application was worth the validation that open-source projects can save time and save lives.

Geofences combined with user location awareness for addressing disaster preparedness only scratches the surface of what can be accomplished with these technologies and capabilities. What other user cases can you envision these capabilities being used? Maybe punch a digital time clock for employees as they enter the work geofence? Comment below! I’m looking forward to seeing all of your contributions!

]]>http://devblog.blackberry.com/2014/06/open-source/feed/0Dev1insideblackberryblogDev1Dev 3Dev4WebWorks Gamepad API thanks to our friend Peardoxhttp://devblog.blackberry.com/2014/06/peardox-gamepad/
http://devblog.blackberry.com/2014/06/peardox-gamepad/#commentsFri, 13 Jun 2014 19:33:45 +0000http://devblog.blackberry.com/?p=18458/ Read More]]>I’m very pleased to announce the release of a Gamepad API for WebWorks applications. Not only is this a cool API that will open up new capabilities for WebWorks apps and games, but it was done in collaboration with one of our open source community members. Before I talk too much about the API, I want to take some time to thank Simon, better known as Peardox, for his many contributions. Peardox contributed the base code for several of the more advanced plugins that have been done by the community, including:

Peardox also provided some great additional contributions to the DeviceInfo plugin, which provides a bunch of lower level information from the device.

Besides the plugins that have been created, Peardox’s work has also greatly contributed to what it’s possible to do in a WebWorks plugin, and the new Gamepad plugin is no exception. So, thanks very much for all your contributions, Simon, on behalf of the whole BlackBerry community.

Our gamepad test app running on a Q5 – Image created in Mockit!

Peardox came to me with an initial proof-of-concept for the Gamepad API. He had a working version and sample based on the Native Gamepad code, but other work was making him busy and he didn’t have the time to finish it off. I completed the minor remaining tasks, but I also wanted to make using this API really seamless for Web developers. So, I spent some extra time making it implement the current HTML5 Gamepad spec. I also tested it with the HTML5Rocks.com Gamepad Tester loaded into a WebWorks app just to be sure.

Implementing the spec means that you use this API in a slightly different way than most WebWorks plugins. The plugin will check to see if navigator.getGamepads exists, and if not will map it to its own function for that call. That will happen when the “webworksready” or “deviceready” event has fired. This method returns the list of available gamepads in an array:

The Gamepad API recommendation is to check this array on the Animation Frame updates so that graphical and controller input is synchronized. For example, this is the method from the sample app:

There are events fired as well for when a gamepad is connected or disconnected, and in the sample this is used to update the list of attached controllers to display input from:

You’ll see from the sample app that the buttons go in a certain order – that’s the HTML5 Gamepad API’s “standard” mapping. As long as the controller is one that this plugin has an ID for then it knows how to map it to the “standard” order. Otherwise it will send it in the raw order that it gets, and the mapping attribute will be the empty string. That’s also according to the spec.

It’s really as simple as that. With a few lines, you can connect gamepads to your application or game controls and provide great new capabilities for your users. Consider adding gamepad support to multimedia apps, like a remote control, or to presentation and data visualisation applications.

In my previous blog post, “Introducing the PantherUI Carousel”, I wrote about how you can use virtual space to create responsive apps for different platforms and screen sizes. So for this post, I wanted to share some of those cross-platform “gotchas” with some tips.

1. Touch Support

If you’re planning on building an app that runs on mobile and desktop, you could get away with just using a click event for finger taps and mouse clicks, but the user experience will be slower on most mobile browsers due to a 300 ms delay on click events. Whereas, a touchstart event has no delay. Another reason for using touch is it gives you the ability to handle gestures like swiping.

Especially, if you use a tiny library like Hammer.js that provides support for advanced multi-touch gestures like pinch and rotate. If you’re dealing with a legacy desktop app, you could use a polyfill library like FastClick that doesn’t require changes to your existing code. Or if you prefer to do this manually like I did, you can dynamically bind your events based on whether your browser supports touch or not:

I chose not to use a library because I wanted the PantherUI to be a standalone library with no dependencies. So the choice really depends on your needs.

Touchend not firing

Another thing to remember is that touch events have quirkson some devices. Originally in the PantherUI Carousel, you could swipe left or right anywhere on the screen to rotate the panels. But when I tested this on an Android device, I found the carousels weren’t turning. After debugging the touch events, I discovered that the touchend event wasn’t firing. Apparently, this was due to a known issue on Android.

preventDefault

The workaround was to call preventDefault() on either the touchstart or the first touchmove event. Unfortunately, using preventDefault cancels native scrolling for overflow content, which means if you want that behavior, you’ll have to implement it yourself. Although, there are libraries like iScroll that I could’ve used, I knew that the BlackBerry 10 browser had hardware-accelerated scrolling so I wanted to keep that default behavior.

Touch target

So the simplest solution was to bind the touch event to a non-touch area like the panel’s title bar. This area was big enough for swiping left or right, and the touch events with preventDefault didn’t conflict with scrolling or clicking links. Also, by moving the touch target outside the content area ensured that it wouldn’t conflict with components like geographic maps, where a user would normally pan or zoom using gestures.

Figure 1: Title Bar

Event delegation

Problem solved, right? Not quite. Moving the listener to the title bars meant I’d have to attach a listener to every panel, which isn’t a big deal if we only have a few panels. But once we start dynamically adding dozens of panels or removing them, it becomes more complex and can affect performance. So I decided to use event delegation to attach one listener to the carousel element (parent) that would handle all the panels (children) and execute only when the target is a title bar:

minDragDistance

So delegating the events greatly simplified the code, but I noticed the touch target was very sensitive. If you just tapped the title bar with a slight jitter, even a 1px movement would cause the carousel to rotate when you just meant to tap on the maximize or restore button. To solve that issue, I added some logic to check if the distance met the minimum threshold for the drag distance (i.e., 16px) before performing the actual turn:

“Rubber band” bounce effect

Another platform-specific feature that I ran into was the “rubber band” bounce effect in iOS. If you swiped on a slight angle, it would cause the whole page to scroll up or down and bounce back even though the page had no overflow content. Although it’s a neat effect, it’s not the behavior we want in our carousel-based app.

To fix that issue, I could’ve used preventDefault on touchstart or touchmove for the entire body, but that would cancel all the default behaviors like scrolling and clicking on links. Although I could’ve added logic to detect and handle all those things manually, it wasn’t worth the effort. Two simpler solutions were to: (1) use buttons instead of gestures to turn the carousel, or (2) for PhoneGap apps, disable the webviewbounce setting in the config.xml:

2. CSS 3D Transforms

preserve-3d

Although CSS3 features are available in all the modern browsers, 3D Transforms are not supported in IE 8 or 9, and only has partial support in IE 10 and 11 (see caniuse.com/#feat=transforms3d). Unfortunately, this is due to the lack of support for the preserve-3dproperty on nested elements. For the PantherUI Carousel, this means all the panels are flattened on top of each other:

Figure 2: Carousel in IE 11

So if you need to support IE 10 or 11, you can wait for Microsoft to add it (see IE Web Platform Status), or the workaround is to manually apply the parent element’s transform to each of the child elements in addition to the child element’s normal transform. This is something that may be added to the Carousel in a future update, but the more likely option will be to create a fallback to a 2D Carousel like Swipe JS to support older browsers.

overflow-scrolling

Another issue that I found was that 3D Transforms can affect the position of the scrollbar if hardware-accelerated scrolling is enabled in some browsers:

Figure 3: Scrollbar Offset

This doesn’t affect every panel so you could leave it in, but I chose to comment out the CSS until it’s fixed in the affected browsers:

3. Cross-browser

Another tip worth mentioning is understanding browser differences, and the differences between certain JavaScript properties that may seem alike, but are subtley different.

target vs srcElement

For cross-browser support with events, you should use W3C’s target property because srcElement is a Microsoft standard that is not supported in Firefox. However, if you need to support IE browsers before IE 9, you’ll need to use srcElement.

childNodes vs children

When you’re accessing the DOM, be aware that children is a property of an Element. Only Elements have children, and these children are all of type Element. Whereas, childNodes is a property of Node, and childNodes can contain any node.

Besides the type differences, what this means is that childNodes includes text nodes that may contain empty whitespace. Most of the time, you’ll want to use children because you don’t want to loop over TextNodes or comments in your DOM manipulation.

Final Thoughts

If you’re interested in a more complete list of cross-browser best practices, check out Modern.IE’s 20 Tips. If you have others, please feel free to add them in the comments section below.

The final lesson I wanted to share is to use the 3D Carousel sparingly. Just because it’s cool and you can load it with “unlimited” content, be practical and know your audience — the content in each carousel panel should be related. For example, letting a user swipe between financial reports makes it easy to compare revenue numbers from one year to the next.

Recently, OData V4.0 won approval as a new OASIS Standard. This is kind of a big deal, so if you’re not sure what it’s all about, check out my blog post from last year on the original OData client library for the NDK.

To support the release of this latest standard, we have an updated client for NDK users on our GitHub site.

So what’s new with this update?

The sample is now much simpler to build in Cascades. Simply open the OData and TestHarness projects from your BlackBerry Momentics IDE and build, though I do suggest changing the default OData server side example for a private one for yourself. See the README for more detail.

The library now includes support for v4.0 features like $filter, $count, $orderby, $skip, $top and $search. Format switching between JSON and ATOM (ATOM is easier to debug, but JSON makes lighter queries in production).

I expect to see a lot more of OData v4.0 as server side gets deployed into products by vendors like SAP, IBM, Microsoft, and others. Give the update a try and let us know what you think!

Challenges

As Enterprises try to figure out their device strategy of whether to support BYOD (Bring Your Own Device), CYOD (Choose Your Own Device), COPE (Corporate Owned, Personally Enabled) or CLEO (Corporate Liable, Employee Owned), the benefits of building cross-platform hybrid applications becomes more obvious. Although native apps offer better performance, web apps simplify development, reduce costs, provide device flexibility and future-proofing, and they have a faster time-to-market. Hybrid apps can give you the best of both worlds — they’re built using web technologies, and they run inside a native container that has access to device capabilities.

Given that HTML5 and tools like PhoneGap/Cordova have made cross-platform development much easier, one of the challenges that developers still struggle with is how to handle different screen sizes and orientations. If that wasn’t hard enough, some enterprises also want their apps to work on larger tablets, desktop screens and even TVs. The reason for this is: (1) a company may have to migrate from a legacy desktop app so they need to re-use existing assets because they don’t have time to rewrite those pieces, or (2) a company may have requirements to build a seamless app for their users so they can move from their office to a meeting room to their car.

Use Virtual Space

Of course, the focus and functionality of such a desktop app will be very different from the mobile app, but if we use a Mobile First approach and Responsive Web Design (RWD), we can get closer to a layout solution that works across multiple devices and platforms. In fact, this was the motivation for creating the PantherUI Carousel — to provide a responsive template that leverages the maximum amount of usable space by utilizing depth and extended virtual space.

In Figure 1, notice how each carousel is multi-sided. By using 3D panels that can be rotated using swipe gestures, and carousels that can be scrolled horizontally in an extended screen, we can significantly increase our screen real estate.

Figure 1: Small Smartphone (Square)

Tips From Downsizing Your Home

However, just because we can load all these panels with content doesn’t mean we should. Designing for mobile is a lot like downsizing from a large 2500 sq. ft. house to a tiny 700 sq. ft. apartment. All the stuff that was stored in your 2-car garage, basement, attic, and backyard shed is not going to fit on your balcony. Although you’re moving the same stuff, you have to make decisions about what items to get rid of, what needs to be replaced, and how to layout your furniture. The same applies to mobile content — be selective and only provide what a person will actually use.

There are also many interior design tips that we can use to make our “place” look bigger:

By hiding navigation, we can remove unnecessary clutter to keep our space clean.

By using slightly transparent panels and lighter colors, we can let in more light to open up the space.

By using a monochromatic color palette, we can define a more cohesive space that is balanced.

By organizing our content into logical blocks, we can create multi-functional furniture like a sofa bed.

So in Figure 2, notice how the layout automatically switches to a semi-stacked layout for a larger mobile screen. In this case, Carousel 1 is used for displaying actual content while Carousel 2 and 3 are used for showing lists and debugging information. In practice, Carousel 2 can be used to drive the content in the other carousels based on the context. It can turn carousels simultaneously to a specific side, and dynamically add panels as new data comes in.

Figure 2: Large Smartphone (Portrait)

For larger screens (see Figure 3), we can fit all the carousels without needing an extended screen. This gives us the best user experience, and we can make it better by letting the user maximize and restore the size of each carousel.

Figure 3: Tablet and Desktop (Landscape)

Under The Hood

So how did we do this? Basically, we used some of the latest features in CSS3 (transforms and animations) to create the carousel and panels with a 3D perspective. Here’s a code snippet of the important parts:

To create the extended screen, we simply used CSS media queries, position and size properties, and set the body to scroll horizontally for overflow content.

/* BlackBerry 9900, Q5, Q10 */

@media (device-aspect-ratio: 1/1) {
html, body {
overflow-x: auto;
}

#container1 {
width: 100%;
height: 100%;
}

#container2 {
top: 0;
left: 100%;
width: 100%;
height: 100%;
}

#container3 {
top: 0;
left: 200%;
width: 100%;
height: 100%;
}
}

To support other devices and orientations, we just used more media queries. The nice thing about CSS is you only need to modify the properties that are different so you don’t need to create bloated stylesheets for each device.

With BlackBerry Enterprise Service 10 and BlackBerry 10 devices, your employees have direct access to your company intranet through the Work Browser. But navigation through your intranet might not always be easy, and it might help to provide your users with some waypoints.

Using our WebWorks web launcher open source project, you can create simple web clips onto the device of your users, they can use to launch your intranet portal or specific website in the Work Browser.

Added to the GitHub project is a very detailed step by step instruction document in the “docs” directory, and the short version on how to create your own web clip is given here:

1. Ensure you have WebWorks 2.0 Gold or higher installed
2. Ensure you have properly setup your signing keys
3. Run WebWorks
4. Create a new Project
5. In the plugins tab add the “com.blackberry.app” plugin
6. Copy over the files from this GitHub (webworks-launcher) project onto the newly created project replacing all existing files
7. Create your own 114x114px icon and save it as “logo.png” to the “www/img/” directory in your newly created project
8. Adjust and save the projects settings, and be sure to press the “save” button

a. Change App ID to your own package name
b. Change App Name to your own app name
c. Change App Description to your own description
d. Change the Author to your own author name
e. Change the Author email to your own author email
f. !! IMPORTANT !! Change the Author URL to the URL you want to launch
(e.g. http://www.blackberry.com)

This past term with the Open Academy project was quite productive. Many of you will be familiar with the program and its Canadian University version called UCOSP. If not, the program invites upper year university students to contribute to open source projects for a term and get course credit. We have been working with the program for two full years now, both with the Canadian program in the fall and the International version in the winter term.

With the launch of WebWorks 2.0 during this term, we focused on porting plugins from the WebWorks 1.0 format and added a few useful ones as well. In all, we ported seven plugins to the new format, added two new ones and new features to two more. You can see our plugins in our repository here.

Before we talk about what’s next with the program, let’s hear from three of the participants in their own words. First up is James from Brock University in Ontario:

I started the semester working on porting over the vibration plugin. This took some time since I had a new system to learn. Luckily with available templates and native code for the plugin, the task was not too hard. It was time-consuming to learn the differences between the old plugin and the WebWorks 2.0/Cordova structure.

By the end of the code sprint at Facebook I was able to finish up the vibration plugin with Tim’s help to ensure everything that was needed had been done, including allowing it have a callback function, which again took some time to figure out went somewhat smoothly. The code sprint was a fantastic opportunity for us to get some work done and get immediate help from our mentors, making the first plugin ports much easier to understand so that we could contribute our work to the open source WebWorks plugins.

After I finished the vibration plugin, it was time to start working on writing a new plugin. I decided I was up to the challenge of working on an audio recorder plugin. Now I had to learn more about the native code. I had a slight idea of how it all worked from working on porting the last plugin, but I had never used BlackBerry native code before. Luckily I had some experience with C++ so writing the code was not too difficult.

The difficult part was making sure that everything worked together: the native code, the JavaScript code, as well as ensuring that I was calling the functions properly in the test app. After figuring out which libraries I had to import, and which functions needed to be called to get the device to record and save an audio file using the audiorecorder documentation, the plugin was now finished. The hardest part of this plugin was that I needed to save an audio file to see if it worked; if a file didn’t show up, then it meant I made a mistake, but there were many places that the error could be. That took up a lot of my time until I decided to start over with the knowledge I had gained, and it took no time at all to get the plugin working. Soon I was able to see an audio file saved in the directory I told it to save to.

I have had the opportunity to learn a lot in the past couple months and consider it valuable to my education. It should help me when I am finished with school and working on real world projects. It is exciting to see that WebWorks 2.0 has gone gold during the duration of the semester and hopefully developers will make use of our plugins to make things easier for them while working with WebWorks/Cordova.

Thanks to Tim for his help; it sounds like the whole group working on the BlackBerry plugins is getting a lot done and learning a lot while doing it.

Second, let’s hear from Morgan of Simon Fraser University in British Columbia:

I’d like to talk about a few topics: briefly my reasons for entering UCOSP and choosing to work on BlackBerry 10 WebWorks plugins, what open source software has come to mean to me because of UCOSP, the plugins that I have ported from WebWorks 1.0 to 2.0 and finally my next WebWorks project.

As a university student, I saw UCOSP as an opportunity to expand my programming knowledge and resume with real world experience. I chose to work on WebWorks because I have been a fan of BlackBerry since the release of BlackBerry 10, and also because WebWorks plugin development provides me an ideal mix of new languages and paradigms to learn – the web programming side – and a language I have plenty of experience with: C++. The fact that WebWorks was open source appealed to me but was not a significant factor in my choice of project.

However, through my experience with WebWorks I have learned to appreciate open source as a platform of opportunity: a platform to gain experience, to learn, to create, and to contribute to the community. Open source helps build experience and knowledge at the same time by allowing easy access to fantastic projects to contribute to, and the opportunity to study code by other developers.

Open source also allows us to build and monetize our own ideas. For example, as a gamer and developer I have always wanted to create games, and the MIT licensed Cocos2d-X has provided me with an excellent avenue to create my own inventions. Cocos2d-X is a mobile 2d game engine built to provide easy access to beginner developers and enough power to experienced developers, all the while providing cross-platform support. It is easy to understand: every game object in your game is a subclass of a class called CCNode, which implements the composite pattern. By creating a CCScene class to act as the backdrop of your game, and by adding CCSprite objects as children to CCScene, a game can be easily populated with sprites. These sprites can then be manipulated and animated by passing in CCActions to their “runAction” interface inherited from CCNode. And because CCNode implements the composite pattern, any action ran on it is ran on its children.

Finally, open source projects allow contribution to communities. The open source nature of WebWorks has afforded me the opportunity to contribute to the BlackBerry community. During the spring semester I ported two plugins from WebWorks 1.0 to 2.0. The first is a thumbnail plugin which can resize images, and the second is a screenshot plugin. My next project is to extend the functionality of the ExtractZipFile plugin to enable it to be able to compress files and folders using Minizip into .zip format. I hope you found this post inspiring!

Finally, let’s hear from Alexandre of the Université de Sherbrooke in Quebec:

The first thing we had to do was to port a plugin from WebWorks to WebWorks 2/Cordova. My plugin was DeviceInfo. DeviceInfo is used to give the developer some information about the device, such as the phone model, the type of keyboard, the mobile country code and much more. The task has been more challenging than expected. Since the plugins use many different frameworks and languages (BlackBerry SDK, JNEXT, Cordova, C++, JavaScript), I had a lot of difficulty understanding each of them and their relation to one another. Also, I had some difficulties using the WebWorks framework itself and the Momentics IDE. However, once everything had been mastered, the process went perfectly.

On the weekend of February 7th – 9th we had the chance to visit Facebook’s headquarters in Menlo Park, California. On the first day, Scott Chacon spoke about Git and GitHub. We learned how to use Git and GitHub; one of the most useful points of this was to learn how to do a pull request. Since all our plugins are hosted on GitHub, this talk was very useful. Afterwards we moved to Facebook’s office to start the sprint.

The purpose of the weekend was to meet our team and talk with our mentor, Tim Windsor, about the projects and ask our questions. During that weekend, I finished porting the DeviceInfo plugin and started a pull request to merge it with the community repository. At the end of the sprint I was assigned my second task: to port the ScreenDisplay plugin. Porting the ScreenDisplay went pretty easily since it was the second plugin I worked on.

My third and final task was to create a new plugin called EmailSender. The purpose of this plugin is to be able to send an email directly from an app not using BlackBerry’s composer. This task was the most challenging of all, since it used some libraries I’ve never used during the semester. I also discovered that I had to set some permissions for the app to be able to use the plugin. Finally, after my pull request, our mentor asked me to add a new feature to the plugin: to allow the user to be able to select an email account on the device instead of using the default account.

This last semester was very nice and I learned a lot about the open source community, GitHub, BlackBerry and working in a remote environment. During our weekly meeting with our mentor, we had the chance to ask questions and get updates from the team. Tim was always there for us to answer our questions and helping us; thank you Tim!

UCOSP is going to try a new spring/summer term this year with four students. We’re going to continue to work on plugins, focusing specifically on the rest of the PhoneGap-Build plugins to add BlackBerry 10 support.

We’ll be starting with a kickoff event on May 12 and 13 at the BlackBerry Jam Space in the Communitech Hub. If you’re interested in following along with the student project, watch #bbucosp on twitter, and all the code will be going into the public BlackBerry repositories on GitHub.

If you want to get involved yourself, contact me to get started: @timothywindsor on Twitter or on GitHub.

Who wants invocation?

Trust me, you do. Inter-app communication has always been a challenge for developers, and will continue to be one as the mobile landscape continues to expand. Users have an unwritten expectation that their apps should seamlessly work together…even in the enterprise. Unfortunately, not having control over other applications is the primary roadblock when it comes to communication between your app and another. BlackBerry 10 answered this call with our Invocation Framework on the initial release of BB10 OS, and has been refining it since.

Our online docs are great explaining how to use invocation in your app.We have a number of core apps that are invokable through the Invocation framework – to both Native and Hybrid apps.

What does Invocation truly mean?

If you were as impressed by our awesome invocation framework on BlackBerry 10 as I was, wait until you see what else you can do with it! First, the ability to launch any other app from your app is a powerful developer tool; it allows you to simplify your app by using the native viewers transparently. Because, after all, there’s no sense recreating the wheel! All of the maintenance, bug fixing and development can be maintained by the invokee and allow you to focus on what your app does best.

I’m sold, how does URI make it better?

The most popular Uniform Resource Identifiers (URIs) are http:, https: and file:. You can create a URI that will launch your app right now on BB10, and you can hand it a payload just like a URL in your browser. Not convinced that this is groundbreaking yet? Let’s look at a few scenarios:

You want to have your users run this great new app that you just pushed to them over the BES, but no one has heard of it yet, or even knows it’s there.

Sending a follow-up email with an embedded link, “myApp://” that they can click on and launch the app.

You want to launch your app from a notification in the HUB.

Send the link in your notification (for an example, the ECL application does this).

You got a support call and you need the user to launch the app with some debug flags.

Text or BBM them a link to “myApp:?mode=debug&data=my%20test%20data”. One click and they are on their way.

You want your app to be invokable by an already existing app.

They can just call your app by URI instead of recompiling invocation capabilities into their app. Simple, fast and extensible.

How do I invoke with a URI?

It’s incredibly simple:

Register your URI:

If it’s a WebWorks app, update your config.xml. It looks like this (from the ECL app):

<!-- This will cause the application to be opened -->

<rim:invoke-targetid="webworks2.ecl2.invoke.waa.open">

<type>APPLICATION</type>

<filter>

<action>bb.action.VIEW</action>

<action>bb.action.OPEN</action>

<propertyvar="uris"value="ecl:"/>

<mime-type>*</mime-type>

</filter>

</rim:invoke-target>

If it’s a Cascades/Native app, update your bar-descriptor.xml. Here is the example from the Cascades Webview app:

<!-- Allow myself to be invoked by uri "webview://" -->

<invoke-targetid="com.waa.WebView2">

<invoke-target-name>WebView</invoke-target-name>

<invoke-target-type>application</invoke-target-type>

<filter>

<action>bb.action.VIEW</action>

<mime-type>*</mime-type>

<propertyvar="uris"value="webview:"/>

</filter>

<invoke-target-pattern>

<pattern-valuetype="uri">webview:</pattern-value>

</invoke-target-pattern>

</invoke-target>

Install your app.

It is instantly available as an invocation target for other apps on your device.

Test it in a browser URL! Nothin’ to it but to do it!

Examples

HTML5 / Hybrid

The new ECL application makes use of invocation to launch from the HUB:

Being an enterprise developer, you are certainly going to bump into some issues and complications that a consumer developer has never heard of. Most enterprise companies regulate Internet access and access to systems, both inwardly and outbound. You’re typically not free to roam the Internet or Intranet and download anything you wish; often you will be restricted in what you are allowed to install on your computer as well.

So when your company does restrict which external resources you have access to, it would be useful to know some hints and pointers how to overcome those challenges.

Signing Keys

One of the first items to get sorted, even before starting development in the enterprise, is setting up your BlackBerry signing keys. These are needed for both releasing software and testing software on devices.

When requesting debug tokens and signing applications, the tools will need access to www.rim.net on port 80/443 – http(s).

Debug tokens are used for testing your application on a real device. The BlackBerry 10 simulator doesn’t require a debug token. A debug token is valid for 30 days and you can test and deploy your apps using the debug token on your device without any further need of Internet connectivity. So if you copy this over to your development station, you don’t need any further Internet access to be able to develop and test your application on the simulator or device.

If by default your company doesn’t allow access to www.rim.net, it might be worthwhile to set up a build server that will be allowed to have Internet access. You can then have the build server create a release build and have it properly signed.

Setting up and using tools

With limited access to the Internet, it may be difficult to download our tools from our developer website on your own station. Also, if your IT department doesn’t allow you to install software (including drivers), contact them to request the right installation packages.

Momentics

After installing Momentics and connecting a device, it will attempt to download the SDK through the IDE. If you don’t have Internet connectivity on your station, this will of course not work. In case your company uses an Internet proxy, the following documentation might resolve the issue: Configure app signing through a proxy server in the Momentics IDE.

WebWorks 2.0 is built upon Apache Cordova and is a tool, which by default will only work if you have proper Internet access to the various online resources (modules). That being said, once a Cordova/WebWorks project is properly set up and contains all the modules you would like to use for a project, you will be able to use it with a debug token without any further Internet access.

There are other development options as well, but for now we’ll just highlight what you need to do for the above two.

Development and Testing

After setting up the tools and debug tokens, development itself will be relatively straightforward. Once you want to start testing your development progress, you will be okay with the deployment to either the simulator or a device (using the debug token).

The simulator will be a good option for most developers to perform normal debugging and testing. The great thing about the simulator is that it resides on your development station and will have access to the internal company enterprise systems.

If you want to test on an actual device and it’s not allowed on the corporate Wi-Fi (or the Corporate Wi-Fi is also firewalled to internal systems), ensure you can have the device activated against a BlackBerry Enterprise Service 10. Once the device is activated, you can deploy the application to the work perimeter on the device, which will have the proper access to the enterprise systems.

To deploy the application in the work perimeter, put your device in development mode and switch over to the work perimeter (home screen > swipe down for settings > Switch to Work). In this mode, select a debug deploy to the device. It will now end up in the work perimeter and you can do your debugging there.

General hints and tips

If you encounter issues related to the network when developing within the enterprise, check whether or not any installed malicious code detection/firewall software might be blocking the traffic. If so, ask the IT administrators to help you out, ensuring this is not keeping you from your development.

We hope this helps you get off to a good start and avoid some of the common frustrations when developing for the enterprise. If at any time you still bump into issues, don’t hesitate to comment below and we will help resolve it!

Did you miss last week’s “Building Web Apps with the New BlackBerry 10 WebWorks SDK” webcast? We’ve got you covered! You can view the recording here.

In this one-hour webcast, BlackBerry development experts walk you through everything you need to know in order to get started building cross-platform web apps with the latest and greatest WebWorks SDK, which is now powered by Apache CordovaTM.

Whether you want to learn how to upgrade your WebWorks 1.0 app, build a new app from scratch, or bring an existing PhoneGap or Cordova app over to BlackBerry 10, this webcast will give you a head start.

Still not sure if this webcast is for you? In this webcast we show you how to:

Install and configure the WebWorks SDK

Configure your signing keys

Create a new project, including an overview of the new project file structure

If you’re in the business of creating physical products that integrate with mobile devices, we’ve got the specs you need to add BlackBerry to your portfolio. Whether you integrate via Bluetooth, USB, WiFi, HDMI, or audio jack, we’ve got you covered. Case maker? Yeah, we can help you too – not only in getting device specs, but also in promoting your products.

Today I’m pleased to announce the availability of developer.blackberry.com/accessories, your one stop shop for all the device specs you need to integrate with BlackBerry 10 smartphones. Check it out and let us know what you think!

]]>http://devblog.blackberry.com/2014/03/bringing-home-the-hardware-add-blackberry-to-your-product-portfolio/feed/0BlackBerry_Accessoriesbrianzub1BlackBerry_AccessoriesPower your WebWorks Extension with Cordovahttp://devblog.blackberry.com/2014/03/power-your-webworks-extension-with-cordova/
http://devblog.blackberry.com/2014/03/power-your-webworks-extension-with-cordova/#commentsTue, 25 Mar 2014 18:23:56 +0000http://devblog.blackberry.com/?p=18094/ Read More]]>Now that WebWorks 2.0 is powered by Cordova, it’s time to convert our extensions from the previous WebWorks 1.0 format to the new Cordova and WebWorks 2.0 format. This conversion process is necessary to ensure your plugin is compatible with WebWorks 2.0. Thankfully, the majority of the changes are quite superficial and it really involves just swapping out one set of framework calls for another.

The approach that I think works best is to start from the new BB10-Cordova Template project, and move the functional code from your old extension into the new template. With this approach, your work will be more consistent with creating a new plugin, and you’ll have less potential for mixing the boilerplate code up.

For the first step, you’ll need to rename the Template to match the extension that you are porting. There are a lot of places where this will be done, from the namespace, to the individual file names, and the native project as well. Follow the guide given in the Template Readme to make those name changes. Then, let’s look at the changes you’ll need to make in each part of the plugin:

Plugin.xml

This file tells WebWorks how to install the plugin into your app. The namespace of the API is defined here, in the “id” property, and the same value is used in a few other spots. Usually you’ll choose a reverse domain name and descriptive name for your plugin. The Template uses “community.templateplugin”, but for all the ones we submit to the Cordova Plugin Registry, we use “com.blackberry.community.<plugin name>” for the ID and feature name/value. However, we usually use just the “community” namespace for the target JavaScript Module value. Here’s the Prevent Sleep plugin.xml as an example:

Client.js

This file is similar in many ways to what you will be used to with WebWorks 1.0. You are still going to define a series of methods to be exported as the API. However, instead of using the old “webworks” APIs to make the function calls, you will now use Cordova’s “exec” method. Also, the namespace of the API is defined here as the _ID value directly, rather than being pulled from the manifest.json file (which is no longer used at all). The “exec” method has a different signature than the WebWorks methods did. It will take success and fail callback functions, then the _ID, the method to call, and the input values in a JSON object. If the API that you are porting didn’t use success and fail callback functions before, then you can do as the Template does and define those methods inline. All the “webworks.event” code that was required before for asynchronous functions is also handled differently, but not in this file, so that will be removed for now.

Here’s how the _ID changes from WebWorks 1.0:

To WebWorks 2.0:

And here’s how one function call would change from WebWorks 1.0:

To WebWorks 2.0:

Index.js

This file also requires some changes. Instead of having a separate JNEXT file, that code is now integrated into index.js. Each method here will have 4 parameters: success, fail, args, and env. The very first line of code in each method should be:

var result = new PluginResult(args, env);

This PluginResult object is how communication is handled through Cordova. The object has methods for returning values, errors, for handling callbacks, and for sending back no result. The second parameter tells Cordova if it should keep the PluginResult object around. Many basic functions will set it false. If the method call is asynchronous or will have multiple results, that parameter should be set to true. In those cases, the PluginResult object is also put into a mapping so that it can be retrieved when the asynchronous results come back. The object automatically generates a unique callbackId value. The callbackId is used the reference the object in the mapping, and is also sent to the native code for use in communication.

If you have “success()” method calls in your old WebWorks 1.0 code, these will typically be replaced by “result.ok()” methods, or “result.noResult()” calls.

Here’s the same method in index.js changed from WebWorks 1.0:

To WebWorks 2.0:

JNEXT

This was a separate file in WebWorks 1.0, but now is included at the bottom of index.js. Instead of using hardcoded event names as done in WebWorks 1.0, the new way uses the unique callbackId value to link up asynchronous events with the original calling function. For this reason, the function calls in the JNEXT portion of the file will now include the callbackId as a parameter sent to the native code. Also, the onEvent function is much reduced in size. The callbackId is retrieved from each event, and the PluginResult object is pulled from the map. In most cases, calling “result.callbackOk(data, false)” and removing the result from the map is all that is needed.

Here’s the small change to send callbackId from WebWorks 1.0:

To WebWorks 2.0:

Template_js and Template_ndk

In the native portion, there are very few changes to make. Only asynchronous method calls are affected, and only by the need to update the event name to be dynamic. The callbackId will be parsed out in the “InvokeMethod” call, and this needs to be passed to any event that sends asynchronous results using the “NotifyEvent” call. Any call to that method should use the callbackId instead of the hardcoded event name that was used previously.

Here’s an example method from WebWorks 1.0 that sends back JSON Asynchronously:

And in WebWorks 2.0, here’s a similar method using the callbackId:

And that’s it! Small changes, really, across all the files, and almost no native code changes, makes for a fairly rapid porting process. In the end, I think the solution works better as well, with unique callbacks for each asynchronous method. If you’re interested in contributing your plugins to the public BlackBerry repositories on GitHub, we’d appreciate your input. Contact me to get started at @timothywindsor or on GitHub.

Step 2: Request and install code signing keys

In order to build release-ready code and publish an application in BlackBerry World, you must request and install code signing keys. Code signing keys are used to securely imprint your digital signature on a compiled piece of code, such as a production-ready application. The Momentics IDE simplifies the code signing installation process and is recommended. See instructions on how to configure signing using Momentics.

Step 3: Optionally Sign BlackBerry Open Source contributor agreement

If you’d like to contribute your work back to the community through the BlackBerry repositories, you’ll need to sign a Contributor’s Agreement and submit a request to BlackBerry. The contribution process is designed to protect the interests of both the community and BlackBerry, while being lightweight and easy to follow. Once approved, your name will be included among the list of Approved Signatories.

Step 5: Starting a Project from the Template

There is a fair amount of boilerplate code involved in a new plugin, so the best place to start is with the Plugin Template. For convenience, the native portion of the template is included in the NDK New Project Wizard, but for a few reasons, the best place to get the template will always be the GitHub repository.

To create a new plugin, copy the template project into a new location. I would recommend building the sample application first before you attempt to do anything new. Only the “www” folder of the application is included, so you’ll want to create a new application with WebWorks 2 or Cordova first:

In the “Template” folder, run “webworks create sample2”, or “cordova create sample2”.

Remove the “www” folder from this new app, and replace it with the one from the template’s sample folder.

Change to the “sample” folder: “cd sample2”.

If you are using Cordova, make sure the BlackBerry NDK is on your path, or run the “bbndk-env” script to setup your path, and then run “cordova platform add blackberry10”.

Add the plugin to this app with “webworks plugin add ../plugin” or “cordova plugin add ../plugin”

Build and run the app on your device or sim with “webworks run” or “cordova run”. You may need to supply your signing key and device password.

You should see the template sample app run and give you the output from this screenshot:

With that process completed, we’re in good shape to start breaking things!

Step 6: Renaming the Template

Remove the plugin from the app with “webworks plugin remove community.templateplugin”, or likewise with “cordova.” Import the native portion of the Template Project into the Momentics NDK. The project definition is in the “Template/plugin/src/blackberry10/native” folder. Now rename the template plugin and its various parts to suit the plugin that you want to create. Instructions for these steps are included in the Readme. Pay close attention here, as typos and missed renames will cause problems that can be hard to track down. Before actually changing any of the methods, just the names of the boilerplate files and classes, rebuild the sample including the native portion of the plugin and add it back to the sample. This way you can be certain that you’ve got a working base before making the more significant changes.

Build the Native portion, following the instructions in the Readme. This will put native binaries into the simulator and device directories with the name that you chose.

Make sure you updated the reference to the native code in the index.js file where it refers to “libTemplate” and “libTemplate.TemplateJS”. This is how the plugin dynamically loads the native binaries from the .so file.

Also make sure that your “plugin.xml” file was updated with all the new file names. This file tells WebWorks and Cordova how to install the plugin.

Add the plugin to the sample app with “webworks plugin add ../plugin” in the sample2 folder again.

Change the function calls in the sample app function called “testPluginCalls” to reference the namespace that you chose earlier.

Build the app again with “webworks run”.

Step 7: Adding Features and Plugin Communication

Provided all the name changes worked out, you should get the same results as before, but now it’s your new plugin that’s doing all the magic. With this, the door is open to more advanced features, and the template functions are available to show you how to transmit different types of data between the JavaScript and C++ layers. You can send a simple command with no data, with a string, or with JSON. You can get a result immediately, or asynchronously, or initiate a thread that returns multiple results. This is the flow and usage of each part of the plugin:

When the app launches, an object with the contents of plugin/www/client.js is created using the name given in plugin/plugin.xml. In the case of the Template, this is “community.templateplugin”.

In your app you can call a method on this plugin object, which will send the command and parameters through the Cordova framework. It looks up the plugin using the “_ID” value that is used in the exec function calls and defined in client.js.

The “_ID” value matches the id defined in plugin.xml, which means Cordova calls the index.js method of the same name as the command passed from client.js. This index.js file is appended into the “frameworkModules.js” file that you can view in the Bootstrap WebView of your application. It’s the first WebView in the list when you connect WebInspector to your debug application, so you are able to open this WebView and put breakpoints in there for debugging.

The first step of a function call in index.js is to create a new PluginResult object. This object handles communication back to the application through the Cordova framework. The PluginResult is stored in an object for lookup later using its own generated callbackId value.

To get into the native code, the plugin will use the JNEXT bridge, defined at the bottom of the index.js file. This code loads and links the native object code and serializes function calls into it. It’s important that you send in the callbackId value from the PluginResult, and that any parameters are string, so make sure to call JSON.stringify on JSON objects here.

From here the control passes into the InvokeMethod of the native code. The command and callbackId values are stripped off the string to determine the method to call, and the remainder is considered arguments. The architecture separates the JNEXT bridge portion of the code into a file named template_js.cpp while the true plugin is in the template_ndk.cpp file. You will likely have renamed these earlier. Based on the command given, a method from the plugin file is called.

Besides running the native methods needed at this point, the arguments may need to be parsed from a string into JSON. If this is a method that should return a result immediately, you might simply return the result as a string. Otherwise, to return a result, use the “m_pParent->NotifyEvent(callbackId + “ “ + message)” method, where message is a string.

After each change to the native code, the native project needs to be rebuilt. Use the device and simulator targets to build the library in the right folders. When any change to the plugin code occurs, including native code changes, the plugin should be removed and re-added to the sample app. You can write a simple script to do so.

Step 8: Debugging and Logging

Take note of the Logging feature that is integrated into the native part of the template. This is a convenient wrapper for the device’s slog2 logging tool. Given a priority level and a string, the message will be written into slog2, which can be viewed by connecting to the device with Momentics.

When adding features into your plugin, make sure to note what library the code comes in. You’ll need to add that library to the linker setup on your native project. Otherwise, when the plugin library tries to load at runtime, it will fail to link and will not load. The error message states that the app can’t find the library, so this can be quite misleading. Information about adding libraries and special instructions for Qt libraries is in the Template Readme.

Step 9: You’re Good to Go!

At this point, you’re on your way to building plugins and doing some very cool things. Working together with the community, we’ve been able to release 18 community plugins already. Don’t be discouraged if you run into trouble; a lot of your fellow developers have been there before and we can help. If you’re interested in contributing to our BlackBerry repositories on GitHub, we’d appreciate your input. Contact me on Twitter or GitHub to get started.