UCOSP Final – School’s Out For Summer!

Open Source

TITLE_IMAGE

Well, school is done for most of our UCOSP participants, most of who were in their final year of university. Of course the time for learning never stops in this industry, which is why I love it so much. This was our first year involved with UCOSP and I wanted to do a recap off all that was accomplished through the program. A total of 12 upper year students from seven different Canadian universities received course credit while writing open source code with us at BlackBerry and learning what it’s like to be part of a distributed open source project. They also each developed at least one application for BlackBerry World to earn their own Limited Edition device.

Some of the students worked on BlackBerry 10 WebWorks Extensions, and we managed to produce six community extensions. The Compass extension was a temporary stopgap, later replaced by the Sensors API, but from the simple, useful, LED and Vibration extensions, to the more powerful UnZip, Thumbnail, and BarcodeScanner extensions, this is great work that’s very valuable to the developer community.

Other students worked on bbUI.js and submitted a whole bunch of code over the two terms. One of the students is the top community contributor over the period, and there are several commits ready to go in from students this past term. With bbUI.js used by thousands of applications, these students are contributing to the success of many developers around the world. One of those students, Dmitry, had the following to share about his experience working with BlackBerry 10 WebWorks:

“I’d like to briefly talk about what I worked on this semester, and then use the opportunity to provide a quick tutorial on application invoking and working with the file system in a Javascript BB10 app.

As someone excited about web technologies proliferating beyond the confines of the browser, I found working on the BlackBerry stack as part of the UCOSP program at University of Toronto a relevant and useful experience. While web apps on mobile are nothing new, building apps that approach the appearance and user experience of native applications is still far from straight forward. One of the members of the BlackBerry 10 SDK family that I had a chance to work on was bbUI.js, a framework which fills the gap between native and web apps via a set of UI elements and building blocks that match the look and feel of the native BlackBerry 10 Cascades UI. Since the framework deals with UI elements only, it can be easily used alongside other Javascript libraries like Backbone.js or Ember.js to build a modern MVC-style web app that fits nicely with its native brethren and provides a consistent UX.

Aside from bbUI.js, web apps on BlackBerry 10 can access a variety of API’s in order to gain access to device features. One of the things you can do is allow your app to be invoked by other apps, e.g. to share a file between the applications. The file can then be accessed by your app using the WebKit File API. As there are a few gotchas to the process, I figured it might be useful to walk through the necessary configuration settings needed to set up invoking of a BB10 web app, and then show how a shared image file can be accessed using the File API.

In order to get invoking set up, we need the following settings in the app’s config.xml:

    <!-- Invocation APIs -->
    <feature id="blackberry.invoked" version="1.0.0" required="true" />
    <!-- Access to I/O -->
    <feature id="blackberry.io"   required="true" />
    <feature id="blackberry.app"  required="true" />
 
    <!-- Access to user's file system -->
    <rim:permissions>
        <rim:permit>access_shared</rim:permit>
    </rim:permissions>
 
    <!-- Configure invoking -->
    <rim:invoke-target id="com.helloworld.app">
        <type>APPLICATION</type>
        <filter>
            <action>bb.action.SHARE</action>
            <!--Register app for all image MIME types -->
            <mime-type>image/*</mime-type>
            <property var="uris" value="file://,data://local"/>
        </filter>
    </rim:invoke-target>
    <rim:invoke-target id="com.helloworld.viewer">
        <type>VIEWER</type>
        <filter>
            <action>bb.action.SHARE</action>
            <!--Register app for all image MIME types -->
            <mime-type>image/*</mime-type>
            <property var="uris" value="file://,data://local"/>
        </filter>
    </rim:invoke-target>

That will set up your app as a target for invoking and configure all the necessary permissions needed to access the file system. Note that the MIME type in the rim:invoke-target section will determine whether your application appears on the list of invokable apps when the user decides to share a particular file type.

Next, we need some Javascript. I will dump it all out on you, and then explain immediately after:

document.addEventListener('webworksready', function(e) {
    blackberry.event.addEventListener('invoked', 
        function eventListener(data) {
            // Expose callbacks via closure
            var callbacks;
 
            callbacks = {
                // Generic error handling 
                err: function error(e) {
                    console.log("Error: ", e);
                },
 
                fileSystem: function(fs) {
                    fs.root.getFile(
                        data.uri, 
                        null, 
                        callbacks.getFile,
                        callbacks.err
                    );
                }, 
 
                getFile: function(fileEntry) {
                    // Could this be more nested? Yes.
                    fileEntry.file(
                        callbacks.fileEntry,
                        callbacks.err
                    );
                },
 
                fileEntry: function (file){
                    console.log("Got the file!", file)
                    // YOUR CODE
                }, 
            };
 
            // Sandboxing off to allow access to shared file system
            blackberry.io.sandbox = false;
            // Chop off the 'file://' to get just the path
            data.uri = data.uri.substr(7, data.uri.length)
 
            window.webkitRequestFileSystem(
                window.PERSISTENT,
                0,
                callbacks.fileSystem,
                callbacks.err
            );
        }
    );
}, false);

First of all, to detect an invocation from another app, we need to listen for the invoked event using the blackberry.event module. When the callback for invoked is called, the first argument will contain the URI to the file. Since we’ll be dealing with file paths, we want to remove the file:// prefix from the URI before continuing. We also want to disable sandboxing of I/O since we need access to the shared file system.

From there on, we need to make a series of asynchronous calls to the File API to get to the contents of the file. I combined all the needed callbacks in one object for brevity. Eventually, once the FileEntry.file success callback is called, its first argument will be a regular File object much like one from a “file”  input form element. You can then read the file as text or binary using the FileReader interface, upload it somewhere using XHR and the FormData interface (see the append method), etc.

And that’s it! You’re ready to rock.

We’ll be making plans for the next year working with UCOSP, so keep an eye out for those projects getting started in September. In the meantime, we’re going to be doing some summer open source coding. We’re in the early stages of planning at least one hack-a-thon where we’ll focus on open source: frameworks, tools, libraries, etc., so we can all make even better applications. If open source is your thing, or you’d like it to be, think about some projects that you want to work on, and keep a slice of time set aside before your summer gets booked up – it’s going to be good times.

About Tim W.

Tim works on the Developer Relations team at BlackBerry, focusing on WebWorks, HTML5, and Open Source.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus