Archive for May, 2010

border-image-generator: Local File Access

by on May.31, 2010, under border-image-generator, Web Dev

This article covers the techniques used to implement the local file access feature that is included, along with tiling support, alternate styling, and parameter optimization, in the most recent push to border-image-generator.

One of the biggest short comings that I felt like border-image-generator was that all files had to be posted on a HTTP server due to restrictions on the access to the file:// protocol. In my personal workflow this was somewhat of a pain, so I set out to find a way around this issue.

During the design of this feature, I quickly decided that all data must remain on the client as I did not want to upgrade my hosting service to include more bandwidth, felt like responsiveness could be a concern, and do not want to tangle with the potentially messy privacy issues that could arrise from storing user generated images on my server.

While this sounded like a daunting task, it turns out that this was possible, in sufficiently advanced browsers, using a variety of HTML5 techniques, including Data URIs, the File API and the Web Storage API.

Display

The problem of displaying the image was the easiest to solve as all of the targeted browsers support data URIs as part of the border-image property. This allowed the application to generate URLs like the following

    border-width: 46px;
    border-image: url("data:image/png;base64,iVBORw0KGgoAAA....") 46 stretch;

And operate as expected. Data URIs have been covered fairly extensively elsewhere, so I will leave this to the reader to investigate.

Reading

With the actual display issue solvled, there was still the non-trivial issue of actually loading the content. My initial investigations involved Flash, which provides FileReference.load API which allowing for this functionality, but under the version I was testing on this API is only usable if invoked in response to user input. Being a HTML guy and lacking functional knowledge of the Flash development process I quickly ruled this technique out.

Continuing my research I came across an article on MDC that covered this exact use case, using the draft File API specification. This worked like a charm, even exposing the ability to read the image contents directly into a data URI.

The API is very clean for use cases such as this:
function loadFile(file) {
    var reader = new FileReader();
    reader.onload = function(event) {
         updateImageURI(file.name, reader.result);
     };
     reader.readAsDataURL(file);
}

Where the file variable above is a File object retrieved from a

<input type="file">
or the dataTransfer object passed to the drop html event.

        $("body").bind("dragenter dragover", function(event) {
            // We have to cancel these events or we will not recieve the drop event
            event.preventDefault();
            event.stopPropagation();
        });
        $("body").bind("drop", function(event) {
            event.preventDefault();
            event.stopPropagation();
            var dataTransfer = event.originalEvent.dataTransfer,
                file = dataTransfer.files[0];

            loadFile(file);
        });
        $("#localImage").bind("change", function(event) {
            var file = this.files[0];

            loadFile(file);
        });

This unfortunately is not without it’s issues. The File API is very much bleeding edge at this point and support is somewhat limited. As of this writing Firefox is the only browser which features this in production (Version 3.6). Support landed in the WebKit trunk literally earlier this month and can be used in their nightlies, but so far has not made it into any production releases.

The site is currently designed to progressively enhance as it detects support for the File API, so no need to worry about being left out of the site as a whole if you are not on one of these browsers yet.

History

After loading the content using the File API, the original implementation utilized the same #hash storage method for the data URIs, but this proved to be problematic as these strings can become quite large and interacting with these URLs was unwieldily. Needing another data store and being forced to maintain a cache of all local images due to the security model employed by the File API, we were left the options of storing all data in Javascript space or using the new Web Storage APIs implemented as part of HTML5.

Examining both options it seemed the the best course was to utilize the sessionStorage object when available and fail over to the javascript data model when not.

    // Check for browser support of session storage and that it is accessible
    // This may be inaccessible under certain contexts such as file://
    function supportsSessionStorage() {
        try {
            return !!window.sessionStorage;
        } catch (err) {
            return false;
        }
    }
    var localDataBinding = (function() {
        if (supportsSessionStorage()) {
            // If they support FileReader they really should support storage... but who knows (With the exception of file://)
            return {
                storeImage: function(name, data) {
                    var entryId = (parseInt(sessionStorage["imageList-count"])||0)+1;
                    sessionStorage["imageList-count"] = entryId;
                    sessionStorage["imageList-src-" + entryId] = data;
                    sessionStorage["imageList-display-" + entryId] = name;
                    return entryId;
                },
                getImage: function(entryId) {
                    return { src: sessionStorage["imageList-src-" + entryId], displayName: sessionStorage["imageList-display-" + entryId] };
                }
            };
        } else {
            // Fail over to plain js structures, meaing that refresh, etc will cause failures.
            var cache = [];
            return {
                storeImage: function(name, data) {
                    cache.push({ src: data, displayName: name });
                    return cache.length-1;
                },
                getImage: function(entryId) {
                    return cache[entryId];
                }
            };
        }
    })();

Working with this API it seems as though it is still somewhat rough. The vendor documentation all state that supported datatypes are only string values (Mozilla, WebKit), but the spec implies that this will change be final release and allow for storage of a much broader set of datatypes.

A consequence of this design is that boomark and URL sharing for local files is not a possibility. For users who need to share or store application states the image in question will need to be stored on a HTTP server and accessed by this route.

These changes as well as some incremental changes have been pushed live on border-image.com and are available in the github repository.

1 Comment :, , more...

Javascript Operation Queue

by on May.28, 2010, under Dev, Palm, Web Dev, webOS

When developing for a platform that relies on asynchronous APIs, such as webOS, the application logic frequently will need to block on a given operation prior to executing other dependent components. This may include anything from loading user data after authentication to saving data after initialization of a given data structure among others.

One method of handling this problem is to make the blocker component explicitly aware of the dependent components and the unique interface to each component, which works for simple cases or situations where the dependent to blocking relationship is one-to-one, but this quickly becomes complicated as a number of dependent components grows. In the extreme cases the blocker may have to be aware of significant portions of the system, leading to maintenance concerns.

Alternatively the blocker call can allow dependent components to register their interest in the completion of the operation and upon completion the blocker can simply notify the components on this list in a generic fashion. This allows that components to remain loosely coupled and has the added benefit of allowing for run-time conditional relationships without requiring that the blocker be aware of the state of the dependent.

Implementing such a notification system is fairly straightforward in Javascript: Simply collect waiting callbacks in an array or other structure then executing each upon completion of the blocking call.

Library

While simple to implement, my experience onFacebook for webOS has shown that a library to implement this behavior is worth the initial effort as manually writing nearly identical for loops over callbacks for the umpteenth time becomes tedious and error-prone.

To this end, we developed and open sourced the OperationQueue class which provides a common implementation that doesn’t require far too many for loops :)

Usage

To use the OperationQueue class you simply need to enqueue your dependent operations using the queue API.

queue can accept a single function which will be called upon successful completion.

    opQueue.queue(function(result) {
        // Do something with the data that we were waiting for!
        console.log("Blocking Operation Completed!");
    });
It also accepts an object with any combination of onSuccess and onFailure fields who will be called for each respective event.
    opQueue.queue({
        onSuccess: function(result) {
            // Do something with the data that we were waiting for!
            console.log("Blocking Operation Completed!");
        },
        onFailure: function(result) {
            console.log("Blocking Operation Failed");
        }
    });

These calls may occur at anytime. If the blocking operation has already completed then calls to queue will result in immediate execution of the queued operation. In this case the result object will not be included.

For the blocking call itself the getSuccessHandler and getFailureHandler generators will return callback functions that may be used to directly on completion or may be passed as callback handlers to the async API. These methods also accept a function parameter which will be called prior to their completion.

Used directly:
(opQueue.getSuccessHandler())();
As a callback:
ServiceRequestWrapper.request('palm://com.palm.preferences/systemProperties', {
        method:"Get",
        parameters:{"key": "com.palm.properties.nduid" },
        onSuccess: opQueue.getSuccessHandler(function(response) {
                Mojo.Log.info("Device ID: %j", response);
            }),
        onFailure: opQueue.getFailureHandler()
    });

For more complicated use cases, the reset function allows for enabling and disabling queuing at any time. For example, if you need to initially allow all operations to proceed and then block only while a given operation is in progress, the getSuccessHandler API may be called immediately after instantiation of the queue and then reset called prior to execution of the blocking operation.

Source:

Operation queue is available in the webos-samples repository on github, within the tipsAndTricks subproject.

One final note: While this was written for a webOS application, it does not depend on any webOS-specific constructs and may be used in any Javascript environment. To see it in action, check out the demo in any browser!

Comments Off on Javascript Operation Queue :, , , , more...

Facebook for webOS: Seed Status

by on May.18, 2010, under Dev, Palm, webOS

With the 1.2.1 release of Facebook for webOS, we are now officially supporting the ability to seed status updates via an application manager launch. This allows for applications that do not wish to interact directly with the Facebook APIs to provide Facebook status posts with minimal effort.

All that is required is a single service request to the application manager.
function seedFacebookStatus(text) {
    ServiceRequestWrapper.request('palm://com.palm.applicationManager', {
        method: 'launch',
        parameters: {
            id: "com.palm.app.facebook",
            params: { status: text }
        }
    });
}

This call will launch the Facebook application, open to the new stream, and populate the update status control in the Facebook application. Once populated the user may edit the message as they please and submit.

A sample project is available on github.

Are there any other features that you would like to see via launch APIs in the Facebook application or for Facebook APIs in general on webOS? Feel free to leave a comment on this post with any ideas that you may have.

9 Comments :, , more...

ServiceRequestWrapper Update

by on May.04, 2010, under Dev, Palm, webOS

This article is part of my Palm Dev Day summary series as well as a follow up to the original service request garbage collection post from last month.

After reexamining the original ServiceRequestWrapper implementation and the possible use cases, some improvements began to show through:

  • Subscribe requests were not protected from garbage collection after the initial complete callback (Thanks to Johan for pointing this out)
  • Requests were not being automatically cancelled on completion
  • The class did not need to be instantiatable as the 90% case can be handled by a singleton

With these issues in mind I decided that a rewrite was in order to make the class easier to use, as this is what the goal was in the first place :).

Non-Subscription Requests

Usage for non-subscription requests now involves a single call, ServiceRequestWrapper.request that is a “fire and forget” call meaning that cleanup is completely automated.

For example a call to determine the device ID can be done as follows:
    ServiceRequestWrapper.request('palm://com.palm.preferences/systemProperties', {
            method:"Get",
            parameters:{"key": "com.palm.properties.nduid" },
            onSuccess: function(response) {
                Mojo.Log.info("Device ID: %j", response);
            }
      });

Note that are no special requirements to cleanup the request object for these types of calls. Upon completion the request object will be cleaned from both the ServiceRequestWrapper data structures as well as any system level data structures.

Subscription Requests

The subscription case is not as simple as the framework can not reliably determine when the request is complete and future results are no longer desired. In order to reliably cleanup subscription requests ServiceRequestWrapper places the cleanup responsibility on the caller, via the cancel method, much in the same way as the Mojo.Service.Request API.

In practice this is not much harder than dealing with the single case. The following example monitors the system preferences for two changes to an arbitrary preference and then cancels any further action on that subscription.

var count = 0;
ServiceRequestWrapper.request('palm://com.palm.systemservice', {
    method:"getPreferences",
    parameters:{ keys: [ "food" ], subscribe: true },
    onSuccess: function(response, request) {
        Mojo.Log.info("Preference changed: %j", response);
        count++;
        if (count === 2) {
            request.cancel();
        }
    }
});

The request API also returns the a request object, which is identical to the 2nd parameter passed to callbacks, for those that need to cancel the request outside of the scope of a callback.

var subsRequest = ServiceRequestWrapper.request('palm://com.palm.systemservice', {
    method:"getPreferences",
    parameters:{ keys: [ "food" ], subscribe: true },
    onSuccess: function(response, request) {
        Mojo.Log.info("Preference changed: %j", response);
    }
});

// And then a miracle occurs

subRequest.cancel();

Source

The updated library is available on github in the palm/webos-samples repository.
Comments Off on ServiceRequestWrapper Update :, , , more...

Visit our friends!

A few highly recommended friends...