Go check it out! As a thank you for reading I will give away some free passes to the first 10 people who can answer this question correctly:

“Who created the Modernizr project?”

Mention me on twitter, @ryanseddon, with your answer to the question.

I will let the winners know via twitter.

If you don’t answer in time, don’t fret! It’s super cheap to get access to my course and many others at learnable.com, 2012 is the year of upskilling so get onto it!

Short URL: http://cssn.in/ja/038

Clipboard events

The testcase above hooks into six events that will trigger when the user does a clipboard operation, unfortunately the before[cut/copy/paste] events don’t seem to trigger.

Range objects

Range objects are what you’ve selected on the page allowing you to alter the selection or simply just return what a user has selected. Ranges also allow you to programmatically set a selection within your document, both of these work in iOS safari.

When setting a range iOS Safari won’t actually show the selection as highlighted but if you were to check the document selection it would return the correct content, desktop browsers will show the range selected in the document.

However if you do the same with a user action like tapping the “set selection range” button in the demo the iOS highlight will show up. Another interesting quirk is if I tap the content and bring the keyboard up but don’t dismiss it then refresh the page the programmatically set selection will show the iOS selection highlight.

Another interesting find is if you perform execCommand, which I’ll touch on later in the article, like bold it will apply the command to the selection made and make the iOS selection UI appear.

var sel = window.getSelection(),
    range = document.createRange();

range.setStart($("h1")[0].firstChild, 5);
range.setEnd($("p")[2].firstChild, 50);
sel.removeAllRanges();
sel.addRange(range);

You’ll notice that when selecting an element I get its firstChild, which is a textnode, this is so the offset value will work and allows you to select half a textnode.

The code is saying create a range starting at the documents first h1 element offsetting the selection by 5 characters and ending at the 3rd paragraph offsetting the end of the paragraph by 50 characters.

Setting clipboard data

Accessing the clipboard is an incredibly sporadic task, there is sort of access in some browsers. IE has the most consistent behaviour similar to how DnD data setting works you have a clipboardData interface which has get and setData methods on it. Other browsers have semi-reversed engineered the IE API with the exception that clipboardData is on the event object rather than the window. iOS Safari allows you to get the clipboard data on a paste event but doesn’t allow you to set it.

There is hope that clipboard access will one day have some consistent support through the Clipboard API editor spec but that’s a long way off for now.

In the demo if you’ve copied text from another location and paste it it will alert the clipboard contents before being pasted.

if("clipboardData" in e && e.type === "paste") {
    alert("Clipboard data: " + e.clipboardData.getData('text/plain'));
}

WYSIWYG

By adding support for the contenteditable attribute comes a whole swoth of API’s available for manipulating the contents, one of those is execCommand.

execCommand allows you to do a whole bunch things to the content. Take a look at this great resource which shows all the commands available and its support in the major browsers. These commands allow you to manipulate the style and html of the editable content (this is how all those fancy WYSIWYG editors work).

I would be keen to know if this works on other smart phone browsers, leave a comment if you know more details.

Short URL: http://cssn.in/ja/037

var obj = {
    handleEvent: function() {
        alert(this.dude);
    },
    dude: "holla"
};

element.addEventListener("click", obj, false);

Why is this awesome?

We can do things like this:

var obj  =  {
    init: function() {
        document.getElementById("btn").addEventListener("click", this, false);
        document.getElementById("btn").addEventListener("touchstart", this, false);
    },
    handleEvent: function(e) {
        switch(e.type) {
            case "click":
                this.button();
                break;
            case "touchstart":
                this.button();
                break;
        }
    },
    dude: "holla",
    button: function() {
        alert(this.dude);
    }
};

obj.init();

As you can see our object has an init() method which binds all the events and just passes in “this” as the callback, handleEvent then delegates off to whatever method it needs based on the event being triggered, rad.

But wait there’s more

Another awesome thing we can do is change the buttons behaviour without having to remove and re-attach the event handler. The second button in the demo changes what the first button does by redefining the handleEvent method.

changeHandleEvent: function(evt) {
    this._handleEvent = this.handleEvent;
    // Change the the handleEvent method without needing to remove 
    // and re-attach the event(s)
    this.handleEvent = function(e) {
        var t = evt.target;

        if (t.id === "btn") {
            // Check the button being clicked and do new stuff
        } else if(t.id === "btn3") {
            this.revertHandleEvent();
        }
    }
}

Makes for some pretty powerful stuff. The third button re-instates the first buttons behaviour back to its original form.

This works in nearly all browsers that support addEventListener, Blackberry 6 browser being one that doesn’t. Blackberry OS7 has fixed this bug.

Polyfill it

IE9 was the first to support addEventListener + handleEvent in the IE family, so for the older ones we can polyfill in support for <IE8 and other non-supporting browsers (BBOS6).

// fn arg can be an object or a function, thanks to handleEvent
function on(el, evt, fn, bubble) {
    if("addEventListener" in el) {
        // BBOS6 doesn't support handleEvent, catch and polyfill
        try {
            el.addEventListener(evt, fn, bubble);
        } catch(e) {
            if(typeof fn == "object" && fn.handleEvent) {
                el.addEventListener(evt, function(e){
                    // Bind fn as this and set first arg as event object
                    fn.handleEvent.call(fn,e);
                }, bubble);
            } else {
                throw e;
            }
        }
    } else if("attachEvent" in el) {
        // check if the callback is an object and contains handleEvent
        if(typeof fn == "object" && fn.handleEvent) {
            el.attachEvent("on" + evt, function(){
                // Bind fn as this
                fn.handleEvent.call(fn);
            });
        } else {
            el.attachEvent("on" + evt, fn);
        }
    }
}

For oldIE it checks if the callback is an object and if it contains handleEvent. Using call we can change the “this” context to the object passed.

For BBOS6 we wrap a try catch around addEventListener and if the attaching throws, check the callback is an object and has the handleEvent method otherwise don’t swallow the error.

We handle all this by wrapping up the event attaching into a nice method which handles the process for us.

Resources

I’m certainly not the first to document this, see ajaxian article with some great examples.

Even HTML5 boilerplate mobile uses this technique for their fast touch event handling.

Short URL: http://cssn.in/ja/036

Fullscreen, finally

HTML5 video has come a long way but still lacks consistent codec support and the ability to go fullscreen, until now of course.

As you can see I’ve created a very simple demo showing HTML5 video in full screen, make sure you’re using Chrome dev, webkit or firefox nightly. In Firefox you’ll need to enable it in about:config, search for “full-screen-api.enabled” and set it to true. Webkit nightly will require the “–enable-fullscreen-api” flag when launching. Chrome dev has it enabled by default.

API differences

If you poked around the source you’ll notice that Webkit uses slightly different method to trigger fullscreen. Turns out webkit only uses a different API for videos but uses the same as firefox for all other elements. Mozilla initially created a draft spec for fullscreen elements but Webkit decided to change the name slightly, for the better I think.

var video = document.getElementById("video");

// Mozilla
video.mozRequestFullScreen();

// Webkit for video elements only
video.webkitEnterFullScreen();

As with entering fullscreen you can also cancel it. Using the cancelFullScreen method will exit any element currently in fullscreen mode.

// Mozilla
video.mozCancelFullScreen();

// Webkit
video.webkitCancelFullScreen();

Fullscreen CSS, DOM properties and events

Along with the ability to force a video into fullscreen there is also some CSS pseudo-classes and DOM properties.

video:-webkit-full-screen     { max-height: 100%; }
video:-moz-full-screen        { max-height: 100%; }

The FullScreen API adds one notable pseudo-class that lets you change the element when it’s in fullscreen mode. A good example is if you had a max-height set on your video element and you triggered fullscreen mode you can then reset the max-height to be 100%.

If you want to do something when the browser is in full screen mode the document object gets the fullScreen property. This is slightly different in webkit compared to mozilla.

// Mozilla
document.mozFullscreen;

// Webkit
document.webkitIsFullscreen;

As you can see mozilla doesn’t include the Is in the property like webkit does. So we have this boolean property on the document how do we know when to check it? Well luckily the API also includes an event that triggers called [moz/webkit]fullscreenchange.

video.addEventListener("mozfullscreenchange",function(){
    console.log(document.mozFullScreen);
}, false);

video.addEventListener("webkitfullscreenchange",function(){
    console.log(document.webkitIsFullScreen);
}, false);

The event will trigger whenever fullscreen mode changes so you can then check the document fullScreen property if it’s currently in or out of fullscreen mode. The event is currently prefixed in both Webkit and Firefox.

Some quirks

API differences aside the mozilla spec highly recommends that hitting the Esc key will exit the browser from fullscreen, unfortunately Chrome doesn’t adhere to this (see bug) (Bug has been fixed for linux/windows still needs a fix for mac). If you’re on OSX Lion it will put the browser into full screen mode so to exit you have to hit Cmd+Shift+F on windows F11.

API changes are almost guaranteed. There is already a webkit bug which mentions changing to “Fullscreen” rather than “FullScreen” but for now both are enabled.

UPDATE: There is an official editor draft of the spec and looks like Mozilla’s implementation will be the final one. The API is slighty changing to make FullScreen lowercase in all API calls except where it isn’t the first word e.g. requestFullscreen.

Much more than just video

I only wanted to cover video elements in this article but the API allows fullscreen on almost any element, this functionality is much more limited in Webkit. Webkit uses webkitRequestFullscreen for all other elements. Using the allowfullscreen attribute on iframes for example will allow youtube or vimeo to put their iframe embeds into fullscreen mode. Firefox works with more elements in their nightly build e.g. if you add the mozallowfullscreen attribute to the iframe you can put it into fullscreen mode.

There is also some security restrictions around key events and characters allowed.

Further reading

• Mozilla has a full on demo showing all the support currently in nightly builds, see blog post too.
• Make sure to read over the editor draft spec.
• Apple developer docs mentions support for some of the events and properties.
• Check out MEjs which recently added support for the fullscreen APIs

Short URL: http://cssn.in/ja/035

Modernizrs’ previous method of injecting the elements revolves around forking for IE, IE<9 uses addRule() rather than insertRule(), this makes it hard to write a simple re-useable method for doing such a test that is cross browser. So I began thinking how this could be re-written to be simplified for re-usability. Rather than inject a style element into the head of a document we could use innerHTML and inject into the element that Modernizr will test against.

elem.innerHTML = "<style>"+css+"</style>";
doc.appendChild(elem);

Simple, easy and certainly re-usable. But something that stumped me for a while is IE6-9 would not append the style element inside the test element?

IE and the case of the NoScope element

After searching high and low I found some useful information about scope and NoScope elements in IE. Basically IE has a few elements that are considered NoScope which when trying to insert with innerHTML will be stripped! On this infamous page however it mentions if you precede a NoScope element with a scoped element they will not be stripped and we can then insert our style element.

elem.innerHTML = scopeElem+"<style>"+css+"</style>";
doc.appendChild(elem);

Huzzah! It works in IE6-9. We now have a simpler easier way to inject an element with associative styles and we've halved our touching of the DOM by bundling the test element and style element into one appendChild operation.

What's considered a scoped element?

A scoped element can be anything other than a style, script or comment element. In Modernizrs' case it uses the soft hyphen entity (&shy;) so as not to interfere with measurements done on the injected element. We could very well prepend the innerHTML string with the test element we wish to inject, but for easier referencing I create it in the method and pass it to the callback. This way we can keep the reference to the node and not have to query the DOM again.

injectElementWithStyles = function(rule,callback){
    ...
    var style, div = document.createElement('div');
 
    style = ['&shy;','<style>',rule,'</style>'].join('');
    div.id = mod;
    div.innerHTML += style;
    docElement.appendChild(div);
 
    ret = callback(div,rule);
    ...
}

There's also a few other additions that centre around the injectElementWithStyles() method such as the test_bundle() method which does the DOM injection test in one fell swoop. If you want to know more go check out the source or hit me up on twitter.

Short URL: http://cssn.in/ja/033

Remy recently added remote debug functionality by the way of an intermediate server to delegate commands, mine works differently and the two solutions could work well together.

In order to use the demo you’ll need to install the BrowserSocket add-on first.

For a quick intro on what you can do, watch the screencast below. I’ll go into how it works on a technical level in the rest of the article. I’ve also filmed a super dodgy looking video of the remote debugging on the iPad.

Browser to browser connections

As mentioned in the intro and screencast this requires the very clever, and awesome, BrowserSocket Firefox addon which allows you to let a browser window act as a WebSocket server that can be connected to by a client using the standard WebSocket API. The beauty of this is it requires very little setup and no actual server, browser to browser communication. In order to communicate with external devices they just need to be on the same local network as your current browser, you can even create an adhoc network between your computer and the device and remote debug that way.

Connecting the client to the console

There a two ways you can connect a client to the jsconsole webapp.

Using the client bookmarklet you can load it on any website and connect to the generated websocket address, make sure the client and the remote device are on the same network. Once an active connection is obtained any console calls will be sent to both the client and the jsconsole webapp, all JavaScript calls will be executed on the client including loading of js libraries.

The second is including the JavaScript file in your project the advantage of this is you can setup automatic connections so any console calls will be sent to the web app.

<script id="jsconsole" 
    data-socketaddress="ws://127.0.0.1:56187/bs/15917705/" 
    src="client.js">
</script>

How it works on a technical level

Once you have installed the BrowserSocket addon in jsconsole you can call the :createServer command which will generate a WebSocket address that you will connect the client to.

:createServer command opens a BrowserSocket instance and gives you a WeSocket address to connect to

Behind the scenes the BrowserSocket addon exposes the BrowserSocket() constructor which uses the nsIServerSocket interface available to Firefox addons to create a socket server with the ability to accept incoming connections.

Using the constructor we create a new instance and supply a connection handler which will initialise the server instance and allow you to attach functions to the various events i.e. onopen/message/close etc same API as WebSockets.

var bs = new BrowserSocket(bsHandler),
     bsConnection;
 
function bsHandler() {
    return new function() {
        bsConnection = this;
        bsConnection.onmessage = function(msg) {
            // Handle messages sent to browsersocket
        }
        bsConnection.onopen = function() {
            // Run stuff once connection is open
        }
        bsConnection.onclose = function(e) {
            // Revert changes once connection is closed
        }
    }
}

On the client side we simply use the native WebSocket API to connect to our BrowserSocket instance upon successful connection it will log a success message to both client and jsconsole webapp. Very simple and very powerful.

var ws = new WebSocket(url);
 
ws.onmessage = function(msg) {
   // Eval code sent from jsconsole
}
ws.onopen = function() {
   // Run stuff once connection is open
}
ws.onclose = function(e) {
   // Revert changes once connection is closed
}

There is one more command called :killServer which does just that, kills the BrowserSocket instance and disconnects jsconsole from the client.

:killServer command kills the BrowserSocket instance and if there is an active connection closes that too

bsConnection.close();
bs.stop();

It’s only the beginning

I have many ideas that I will be implementing such as a :cd command so you can switch between connected device and jsconsole web app. I’ll add a roadmap/ideas wiki on my github fork soon. If you wish to suggest a feature create an issue for now.

I have also created a fork of the BrowserSocket addon on github that will eventually have some minor updates to help with remote debugging such as returning your local ip to make it easier to connect to remote devices. You can check out the master repository on launchpad to follow the actual developments of the addon.

Short URL: http://cssn.in/ja/032

I’ve put the following article ideas into real world practice by using Modernizr as a test subject since it uses a fair amount of the concepts discussed in this article. Make sure your console is open and you’re using a good browser.

Just a side note that since I’m doing some hefty logging and using ternary statements inside some of the logs, the actual execution speed of Modernizr is affected. Always remove logs from production code.

More than just messages

Before we dig into the other console methods let’s show some of the powerful functionality console.log() has, such as the ability to pass as many arguments as you want.

var foo = {baz: "tubular", goo: "rad"}, bar = "baz";
console.log("string",1,foo.goo,bar,foo.baz); // string 1 rad baz tubular

This will print out each argument and display it on the one line. That’s kinda useful but what would be better is if we could somehow intertwine all those arguments into a nicely formatted message in the console. Wait we can.

If you’re familiar with printf() in other languages console.log() shares some similarities. Taking the last example and passing in all those extra arguments we can reference them and create a nicely formatted string.

var foo = {baz: "tubular", goo: "rad"}, bar = "baz";
console.log(
     "%s theory is %d %s concept. I can only describe it as %s and %s",
      "string", 1, foo.goo, bar, foo.baz 
);
// string theory is 1 rad concept. I can only describe it as baz and tubular

What do those %s and %d do?

Glad you asked, these are special characters so we can do string formatting within our log message. Basically %s says print the argument as a string, %d says to print the argument as an integer you can also use %i or %f.

Each appearance of the string formatting operator will choose the corresponding argument. First replacement operator will use the first argument and so on so forth.

We can adjust the order in which an argument will appear within the string by using the $ parameter preceded by the argument we wish to print.

var foo = {baz: "tubular", goo: "rad"}, bar = "baz";
console.log(
     "%2$d theory is %d %s concept. I can only describe it as %s and %s",
     "string",1,foo.goo,bar,foo.baz
);
// 1 theory is 0 baz concept. I can only describe it as tubular and %s string

What this string replacement is saying is I’ll start at the second argument and progress from there which as you can see causes an issue.

Essentially the first argument gets appended to the end of our arguments giving us six arguments but we only specified five locations for the strings to be replaced in and since we started at argument two it only prints four of them followed by %s and string.

We can fix this by adjusting the above log message and reset the position so everything will be printed as expected.

var foo = {baz: "tubular", goo: "rad"}, bar = "baz";
console.log(
     "%2$d theory is %1$s %3$s concept. I can only describe it as %s and %s",
     "string",1,foo.goo,bar,foo.baz
);
// 1 theory is string rad concept. I can only describe it as baz and tubular

In order to get the arguments to print out correctly we need to change the starting order of the second and third replaced items. The others are in the correct order so we don’t need to adjust where they should start looking. The string will use the arguments in this order 2,1,3,4,5.

String formatting is a powerful tool and I’ve only scratched the surface. Try experimenting to see what you can get it to do and take a read of some of Joe Hewitts docs on the console.

Different kind of messages

Like log there a few other methods that will allows us to present a message to the console with different styling. Those are console.info(), console.warn() and console.error().

console.info("%s numbers %d, %d and %d","hello",1,2,3); // hello numbers 1, 2 and 3
console.warn("%s numbers %d, %d and %d","hello",1,2,3);
console.error("%s numbers %d, %d and %d","hello",1,2,3);

Firebug example of console.info(), console.warn() and console.error()

All three can also use string formatting and be passed as many arguments as you want. These can obviously give you much clearer visual clues as to what is going on in your code.

Logging the DOM

When you log a reference to a DOM element the default behaviour is to provide a link to that DOM element with console.dir() and console.dirxml() methods we can inspect the elements properties or create a little subset of the html outline of the element.

console.dir(document.documentElement);
console.dirxml(document.documentElement);

Chrome example of console.dir() and console.dirxml()

Grouping

Sometimes it would be useful to be able to group a bunch console calls for easier referencing we can do that with console.group(), console.groupCollapsed() and console.groupEnd().

console.group("Overlord");
console.log("Overlord stuff");
 
console.group("Lord");
console.log("Overlord stuff");
 
console.group("Minion");
console.log("Minion stuff");
console.groupEnd();
 
console.groupCollapsed("Servant");
console.log("Servant stuff");

Safari example of console.group() and console.groupEnd()

As you can see nesting console.group() will further nest the results, in order to end a particular group you use the console.groupEnd(). console.groupCollapsed() is the same as console.group() but the group and its related information will be collapsed.

Code timing and profiling

The console also allows you get fairly accurate timings useing console.time() and console.timeEnd(). These two methods need to be placed at the start and end of what you want to time in your code.

console.time("Execution time took");
// Some code to execute
console.timeEnd("Execution time took");

Firefox example of console.time() and console.timeEnd()

The timers are associated with each other via their labels, this way you can have multiple timers throughout your code. When a timer hits a console.timeEnd() it will output a message with your label and the time it took in milliseconds to execute.

Along with timings we can also profile a subset of your code and output the profile stack, giving lots of juicy information about how much time the browser spent where.

console.profile();
// Some code to execute
console.profileEnd();

Asserting your code

When you begin working on a complex project it’s important to start unit testing your code. This allows you to avoid simple mistakes and possible regressions. Luckily the console also includes assertions.

Assertions allow you to enforce rules in your code and to make sure the results it’s producing are the results you expect. The console.assert() method allows us to do rudimentary unit tests on our code, if something fails the console will throw an exception. The first argument can be anything, function, equality check or checking existence of an object.

var a = 1, b = "1";
console.assert(a === b, "A doesn't equal B");

Chrome example of console.assert()

The assert method takes the assertion you want to enforce as the first argument, in this case a simple strict equality check, and the second argument is the message to display if it fails.

Browser support

Most of the following console methods discussed have quite good browser support. IE8+, Firefox with firebug, Opera or a webkit browser such as Safari or Chrome. There are a few differences between the browsers, Firefox, Safari and Chrome having the widest support. A good way of finding support is to do console.dir(console) which gives you nice look at the console object and it’s methods.

Opera with Dragonfly does support most of the methods on the console with the exception of string formatting so no fancy logging with argument re-ordering in dragonfly. There is no timing but no profiling (although there is profile and profileEnd available it will log saying this feature is not yet available).

iOS Safari also has pretty rubbish support, no string formatting, timing, profiling or grouping but the limited screen real estate could be the reason some of these aren’t supported. It does however support assertions.

IE8 has support for a pretty wide range too including string formatting and assertions but no timing, profiling, dir or dirxml.

Having said that using firebug lite can add some of the console methods to unsupporting browsers.

I haven’t discussed everything available in the console but what I did cover would be the most useful features available to make debugging and testing a much smoother process. Go forth and enrich you development with more than just string logging.

Short URL: http://cssn.in/ja/031

A recent release on the Chrome Dev channel shipped early support of this new specification allowing us to play around with the new API.

Update: The API is now prefixed with webkit for File System Access and the BlobBuilder, see announcement.

Update 2: requesting PERSISTENT storage needs to go through the Quota Management API, I’ve updated the demo and source files to use TEMPORARY instead, to use PERSISTENT see HTML5Rocks article.

Isn’t this what indexedDB/WebSQL, applicationCache and WebStorage is for?

What this API offers over indexedDB/WebSQL, applicationCache or WebStorage is the ability to process, store and organise very large amounts of data, such as videos. The specification mentions some potentially useful use cases where this API would be advantageous. The developer has the ability to store these large files in a sandboxed environment. If the browser closes or crashes we can access the previously loaded files from our sandboxed filesystem.

However the WebSQL and indexedDB both have the ability to store “Blob” objects which could potentially be used to polyfill support for the Filesystem API. Although indexedDB Blob support has only just landed in Firefox 11.

If you don’t have Chrome Dev installed you can watch the screencast below showing the demo in action. If you do have Chrome dev installed you need to launch chrome with this flag –unlimited-quota-for-files.Chrome no longer needs to be started with this flag for the FileSystem APIs to work! If you’re not running the demo in your localhost but from a file:// protocol you’ll also need to do the additional –allow-file-access-from-files flag for filesystem access to work.

The above demo has a few buttons which run some code to create files/directories or write text to a file. You can also drag and drop files which will be copied into your new sandboxed filesystem.

Requesting access

In order to gain access so we can read and write to our filesystem we need to request access which will create our filesystem based on a few parameters we pass to the requestFileSystem() method.

window.webkitRequestFileSystem( TEMPORARY, 5242880 /* ~5MB */, function(fs) {
    fsys = fs;
    root = fsys.root;
}, FSA.error);

On the window object we have the requestFileSystem() method that takes four arguments (type, size, successCallback and errorCallback), the last one being optional.

• type: Can either be PERSISTENT or TEMPORARY either it needs to stick around or we only wish to use it for a while and don’t care if the browser needs to remove it.
• size: How much storage we need, in bytes, for our filesystem. This is ignored at the moment since we’re setting the –unlimited-quota-for-files when launching Chrome.
• successCallback: Upon successful creation or successfully accessing a previously created file system we can run some code. In the above example I store the DOMFileSystem object so we can access it later.
• errorCallback: If something goes wrong such as requesting too much storage space we can capture the error and display a useful message to the user.

In the specification it mentions asking permission from the user to create a filesystem. As of writing it never asks the user for permission but I imagine this will eventually trigger a permission request much like geolocation and web notifications currently do.

Creating files and directories

We now have access and have created a reference to our DOMFileSystem inside our immediately-invoked function expression, (function(){})(). This way we don’t pollute the global scope and can have private variables only accessible within the execution context. Let’s dive into creating files and directories.

Create a file

In order to create a file inside our DOMFileSystem we have the getFile() method, which is oddly named for creation but it will make sense in a second.

FSA.createFile = function(path) {
    root.getFile(path,
        { create:true, exclusive:true },
        function() {
            console.log(path+ " file created");
        },
        FSA.error );
};

Inside the FSA.createFile() method we pass a path argument and access our DOMFileSystem using root variable we created on the inital filesystem request. On root we have the getFile() method which takes four arguments (path, flags, entryCallback, errorCallback) , the first being the only required one.

The flags object has two properties, create and exclusive. In the above code example I specify both create and exclusive to be true which means if the file doesn’t exist create it and if it already exists throw an error. If we don’t specify create and the file doesn’t exist it will trigger the errorCallback if specified. The entryCallback will let you add data to the current file, which I’ll go into later in article.

Create a directory

Creating a directory works exactly the same as creating a file except we have the getDirectory() method which takes the same arguments as getFile().

FSA.createDirectory = function(path) {
    root.getDirectory(path,
        { create:true, exclusive:true },
        function() {
            console.log(path+ " directory created");
        },
        FSA.error );
};

Within the path argument we can specify a relative path but we can’t create a folder more than one folder deep if none of its parents exist e.g. setting path to “multiple/levels/deep” will fail if “multiple” and “levels” folders don’t exist.

If the folder structure root > multiple > levels exists we can then create nested folders easily by passing our path argument as “multiple/levels/deep”. We can also get fancy using “..” in our path argument e.g. If I want to create a folder at the same level at “levels” I can pass “multiple/levels/../samelevel” to the path argument and get “levels” and “samelevel” inside “multiple”. This concept also applies to getFiles().

Writing to files

getFile() and getDirectory() also have the ability to write content to a file or create a file within a directory. This is done through the successCallback which passes in either the fileEntry or directoryEntry reference so we can further manipulate it.

Write content to a text file

In the callback when we have access to the fileEntry which has two methods we can use, createWriter() and file(). To write to a file we utilise the createWriter() method.

function(fileEntry) {
   fileEntry.createWriter(function(writer) {  // FileWriter 

       writer.onwrite = function(e) {
           console.log('Write completed.');
           dir = null;
       }; 

       writer.onerror = function(e) {
           console.log('Write failed: ' + e);
       }; 

       var bb = new WebKitBlobBuilder();
       bb.append(data);
       writer.seek(writer.length); // Always append text to end of file. 
       writer.write(bb.getBlob(mimetype)); 

   });
}

In the getFile() successCallback we initialise the createWriter() method on the current fileEntry, attach a few listeners to the writer, onwrite and onerror so we can trigger some code when it’s done or if something goes wrong. There are several other events that are currently not listed in the spec:

• onabort
• onprogress
• onwriteend
• onwritestart

To append the data to the file we create a new BlobBuilder, this is part of another File API extension specification called File API: Writer. We append our passed in data to the blob, we then set the seek() method to the writer length so we append our text to the file rather than insert it over the top of existing data. Using the write() method we then get the blob data to write to the file.

Getting fancy, drag and drop to your filesystem

The above example may have looked over complicated for just adding some text to a file but it becomes much more powerful when playing with advanced file creation. If you watched the demo screencast or played around with the actual demo you would have noticed that you can drag and drop files to the drop area and it will add those files to your sandboxed filesystem.

FSA.handleDrop = function (e) {
   var dt = e.dataTransfer,
       files = dt.files,
       count = files.length,
       file, fileType,
       droppedFileName; 

   e.stopPropagation();
   e.preventDefault(); 

   for (var i = 0; i < count; i++) {
       file = files[i];
       fileType = file.type;
       droppedFileName = file.name; 

       console.log("File type: " + fileType + "\n" + "File name: " + droppedFileName); 

       dropReader = new FileReader();
       dropReader.name = droppedFileName;
       dropReader.type = fileType; 

       dropReader.onloadend = function(e) { FSA.write2File.call(e); };
       dropReader.readAsArrayBuffer(file);
   }
};

In order to create copies of your dropped files we read in each file, using the File API, as an ArrayBuffer. ArrayBuffer support is recent addition to the File API spec. That way we can pass in the ArrayBuffer to the BlobBuilder, which also had the recent addition of accepting ArrayBuffers, and write it to the file using the Blob data. This allows us to handle just about any file.

That was fancy, but let’s get really fancy

All the interaction in the demo has been creating files from either in the demo or adding locally available files through drag and drop. How about adding files pulled down from a web server. Better yet how about pulling down a tarball file through an XHR request, parsing and extracting its contents and adding all the files to your sandboxed filesystem? Sounds crazy but we can do that.

Using the very clever MultiFile tarball parser by Ilmari Heikkinen and the new Uint8Array type to convert the returned binary data to a typed array. We can accomplish just that.

MultiFile.stream(name, function(f) {
   var name = f.filename,
       data = f.data,
       mime = "application/octet-stream",
       ui8a = new Uint8Array(data.length),
       bb = new WebKitBlobBuilder(); 

   for (var i = 0; i < ui8a.length; ++i) {
       ui8a[i] = data.charCodeAt(i);
   } 

   bb.append(ui8a.buffer); 

   FSA.write2File(name,bb.getBlob(mime),mime);
});

Using the MultiFile.stream() method we can stream each file extracted from the tarball and run a callback function. We then convert the raw binary to a typed array, append it to a blob as an ArrayBuffer using the buffer attribute (thanks Eric Bidelman for the tip) and pass of the information to the FSA.write2File() method. This takes the blob and writes it to our sandboxed filesystem.

XMLHttpRequest Level 2 specification does have the responseBlob attribute defined which would allow us to avoid the memory intensive operation of looping over the binary bits to convert it to an ArrayBuffer. Instead we could append the response straight into the BlobBuilder. Unfortunately Chrome doesn’t yet have this response type so we have to resort to the above method

This opens up some really great possibilities for some really powerful web apps of the future. Ilmari even has a gzip parser so we could also stream a compressed tarball.

Iterating over directory contents

In the demo if you’ve added any images by dragging and dropping them. You can click the “get images” button which will iterate over the root directory and find any images and append them to the inside the drop area. This is also executed on window load so any previously added images will be displayed onload.

FSA.getFiles = function() {
   var dirReader = root.createReader(); 

   dropContainer.innerHTML = ""; 

   dirReader.readEntries(function(files) {
       for (var i = 0, len = files.length; i < len; i++) {
           if(files[i].isFile) {
               FSA.getFile(files[i].name);
           }
       }
   }, FSA.error);
};

In order to iterate over the root directory we use the createReader() method which creates a new DirectoryReader. Then we use the readEntries() method to read each entry. Using a for loop we go over every file check the isFile flag to make sure we’re dealing with a file, directories have isDirectory, and then pass of the file name to the FSA.getFile() method.

FSA.getFile = function(name) {
   root.getFile(name, null, function(fileEntry) {
       fileEntry.file(function(file) { 

           if("createObjectURL" in w && img.test(file.type)) {
               var url = w.createObjectURL(file),
                   image = document.createElement("img"); 

               image.src = url;
               image.width = 300;
               image.height = 200; 

               dropContainer.appendChild(image);
           } 

       }, FSA.error);
   }, FSA.error );
};

In the above code we pass the name to the DOMFileSystem getFile() method, inside the success callback we access the file in question, test to make sure createObjectURL is supported and that the file is of an image type.

createObjectURL() allows us to avoid loading each file into memory and rather generate a blob URL that points to the file. So rather than setting the source of an image as a base64 string we set it as the blob URL and it works like referencing a normal image url.

Removing directories and its contents

If you need to remove any directories and all its containing files you can use the removeRecursively() method on a directory entry.

FSA.removeDirectory = function(path) {
   root.getDirectory(path,null,function(dir) {
       dir.removeRecursively(function() {
           console.log("'" + path + "' and all its contents was succesfully removed");
       }, FSA.error);
   }, FSA.error);
};

Basically you call the getDirectory() method and in its successCallback use the removeRecursively() method which takes two arguments; successCallback and errorCallback. Trying to delete the root directory will throw an error as you cannot do that.

Removing individual files

In the spec on a fileEntry there is a remove() method, as well as several other methods like copyTo(), unfortunately these aren’t available in the current dev build of Chrome. You cannot delete individual files at the time of writing.

Handling Errors

In my demo I set all the error callback arguments to my FSA.error() method this allows for easy logging of errors in a central place.

FSA.error = function(e) {
   switch(e.code) {
       case 1:
           console.log("File doesn't exist");
           break;
       case 2:
           console.log("Stop being silly");
           break;
       case 9:
           console.log("You've already created it");
           break;
       case 10:
           console.log("You've either exceeded your storage quota...");
           break;
       default:
           console.log(e);
   }
};

Inside this function I have a switch statement that lets me fork for certain errors. You can then either do what I’m doing and log a message to the console or run another function. You see a full list of FileErrors and what number means what.

Also check out the Peephole Chrome extension which makes it very easy to debug the FileSystem API.

Can I use it?

Not really, browser support is Chrome Dev and you need to launch it with a flag in order to use it. This is very early days but it’s exciting to be able to play with the future APIs in the browser and get a real feel for them.

If it’s Chrome only, sure, it’ll be fine to use to add some extra functionality to your web app. You could fallback to WebSQL/indexedDB Blobs for other browsers.

I’ve only scratched the surface of what is coming. I’m sure this article will become out of date as the discussion progresses for the API. I’ll try to keep pace with it. You should always refer to the specifications for the latest information.

Short URL: http://cssn.in/ja/030

In the spirit of giving back to the community I have released it under a dual BSD and MIT license so you can do as you please with it. I’ve setup a github repository so you can fork it, watch it suggest ways to improve it and submit any issues.

This script doesn’t rely on any libraries. It uses feature detection to find out if the browser already supports the constraint validation API and either hooks into the native support or creates methods to emulate it.

How does it work?

Let’s dive into the inner workings of the script and see how some of it works. As discussed in the Forward thinking form validation article the script adds the support for some of the HTML5 forms chapter input types and attributes as well as the constraint validation API.

On page load you run the H5F.setup() method which accepts two arguments, the second being optional. The first argument can be a HTMLFormElement, HTMLCollection of form elements or an array of HTMLFormElements. The second optional argument is an object to setup the class names to be applied to the fields in their different validity states.

H5F.setup([d.getElementById("signup"),d.getElementById("anotherform")], {
    validClass: "valid",
    invalidClass: "invalid",
    requiredClass: "required"
});

The above example passes an array of two HTMLFormElements. The script will then detect that more than one form is being passed and loop through the array and attach the functionality. The second argument specifies the class names to be applied when a field is valid, invalid or required.

Event capturing

In order to avoid potentially adding hundreds of event listeners we use the event models capturing behaviour and attach it to the parent form. This way when a field triggers an event we want to use, it will start at the window object work its way down the DOM tree and the form will capture it. To work around IE not bubbling blur and focus events we use the focusout and focusin events which do bubble.

if(type === "blur") {
    type = "focusout";
} else if(type === "focus") {
    type = "focusin";
}
node.attachEvent( "on" + type, fn );

The above code is taken from the H5F.listen() method which inside the IE fork will check if we are using blur or focus and change them to focusout and focusin respectively.

Detecting native support

Opera 9.6, Chrome 4, Firefox 4 and Safari 5 all support the constraints validation API natively so in order to not overwrite any built in functionality we use feature detection.

H5F.support = function() {
    return (H5F.isHostMethod(field,"validity") && H5F.isHostMethod(field,"checkValidity"));
};

The H5F.support() method will return a boolean value depending on the browsers support level. We check for native support of the checkValidity() method and the validity attribute.

Adding support

If the browser doesn’t support the necessary features we add them. Each form will have the checkValidity() method and we loop through each form control and also add checkValidity and the form controls validity attribute.

if(!H5F.support()) {
    form.checkValidity = function() { return H5F.checkValidity(form); };
 
    while(flen--) {
        isRequired = !!(f[flen].attributes["required"]);
 
        if(f[flen].nodeName !== "FIELDSET" && isRequired) {
            H5F.validity(f[flen]); // Add validity object to field
        }
    }
}

Looping over each form control we check that it isn’t a fieldset (Firefox includes fieldsets in the elements array whereas webkit doesn’t) and that it is required. We only check the existence of the required attribute and not its value since it is a boolean attribute.

H5F.validity = function(el) {
   var elem = el,
       missing = H5F.valueMissing(elem),
       type = elem.getAttribute("type"),
       pattern = elem.getAttribute("pattern"),
       placeholder = elem.getAttribute("placeholder"),
       isType = /^(email|url)$/i,
       evt = /^(input|keyup)$/i,
       fType = ((isType.test(type)) ? type : ((pattern) ? pattern : false)),
       patt = H5F.pattern(elem,fType),
       step = H5F.range(elem,"step"),
       min = H5F.range(elem,"min"),
       max = H5F.range(elem,"max");
 
   elem.validity = {
       patternMismatch: patt,
       rangeOverflow: max,
       rangeUnderflow: min,
       stepMismatch: step,
       valid: (!missing && !patt && !step && !min && !max),
       valueMissing: missing
   };
 
   if(placeholder && !evt.test(curEvt)) { H5F.placeholder(elem); }
   elem.checkValidity = function() { return H5F.checkValidity(elem); };
};

In native supporting browsers each form control has the validity attribute that has boolean values to know what state the control is in.

Compare with regular expressions

When a pattern attribute is used we first check the field’s type against a regular expression.

var isType = /^(email|url)$/i,
   fType = ((isType.test(type)) ? type : ((pattern) ? pattern : false));

If a fields type is either email or url we want to handle that differently compared to just a normal text input with the pattern attribute.

H5F.pattern = function(el, type) {
   if(type === "email") {
       return !emailPatt.test(el.value);
   } else if(type === "url") {
       return !urlPatt.test(el.value);
   } else {
       usrPatt = new RegExp(type);
       return !usrPatt.test(el.value);
   }
};

Knowing what type the form control is we can than fork it to handle emails and url’s by using our predefined regular expressions.

For all other form controls which don’t match any of our predefined types we pass in the pattern attribute value to a regular expression and test the field’s value against that.

Keep a form control within range

H5F also supports a simplified version of min, max and step attributes. It will only support whole numbers and in the demo we use it for a postcode example, although most international postcodes aren’t all numbers like Australia but we’ll use this example just to demonstrate the feature.

The postcode form control has both the min and max attributes set to keep it within two values, 1001 – 8000 in our case. Since min, max and step are all related I created a single method called H5F.range() to handle it all.

H5F.range = function(el,type) { 
    var min = parseInt(el.getAttribute("min"),10) || 0, 
        max = parseInt(el.getAttribute("max"),10) || false, 
        step = parseInt(el.getAttribute("step"),10) || 1, 
        val = parseInt(el.value,10), 
        mismatch = (val-min)%step; 
 
    if(!H5F.valueMissing(el) && !isNaN(val)) { 
        if(type === "step") { 
            return (el.getAttribute("step")) ? (mismatch !== 0) : false; 
        } else if(type === "min") { 
            return (el.getAttribute("min")) ? (val < min) : false; 
        } else if(type === "max") { 
            return (el.getAttribute("max")) ? (val > max) : false; 
        } 
    } else if(el.getAttribute("type") === "number") { 
        return true; 
    } else { 
        return false; 
    } 
};

If a form control specifies only the step attribute the H5F.range() method works around that by using the OR (||) operator to give the variables fallback values so the calculations can still be made. To emulate the step attribute we use modulus (%) which will divide our value by our minimum value, will fallback to 0 if it isn’t specified, and return the remainder.

...
mismatch = (val-min)%step; 
 
if(!H5F.valueMissing(el) && !isNaN(val)) { 
    if(type === "step") { 
        return (el.getAttribute("step")) ? (mismatch !== 0) : false; 
    }
}

Using the modulus value we can find out if it is conforming to the specified increment. We make sure the field isn’t empty and that it is actually a number. Then we do a check to make sure it doesn’t equal zero, if it does it will return true which will indicate that there is a step mismatch if false the number is conforming. E.g. If the field has a step value of 3 and the user enters 11 we work out the remainder: (11-0)%3, 3 goes into 11 three times and leaves us with a remainder of 2 which tells us there is a step mismatch.

Browser differences

Since HTML5 is still a working draft there a few difference between browsers and browser version, I’ve listed some of them I’ve come across here:

• In Firefox 4 invalid form controls have a red box-shadow applied to them; this can be reset by setting the box-shadow to none.
• Firefox 4 will override the title tooltip value depending on the validity state of the form control.
• Safari 5¹, Chrome 4-6¹ and Opera 9.6+ all block form submission until all form control validation constraints are met.
• Opera 9.6+ upon form submission will focus to the first invalid field and bring up a UI block indicating that it is invalid.

1. Safari 5.0.1, and Chrome 7 have removed form submission blocking if a form is invalid, most likely due to legacy forms now not submitting on older sites.

Short URL: http://cssn.in/ja/029

While the first feature of drag and drop uploading I figured out quite easily, this drag out feature was a doozy.

How did I figure it out?

There were two clues which got me started. One it only works in Chrome so it had to be an extension to the current Drag and Drop API. Two, after some poking around in gmail, there was a custom attribute on the attachment link called download_url which colon separated the attachments mime type, file name and download link.

Since Gmails JavaScript is obfuscated to within in an inch of its life there was no easy way to attach the built in debugger to anything that might give it away. So I tried downloading the script and running it through various unobfuscaters which made it format nicely but I still had to work with function names like vHG etc.

My last hope was chromiums bug tracker and searching to see if any bugs or feature requests were filed that could help give it away. I knew the download_url attribute played a role and it would be set using setData method on the dataTransfer object. So I searched high and low on Chromiums bug tracker for matches to “download_url”, “downloadurl” & “downloadurl setData” nothing nada, zip. So I turned to the webkit bug tracker, still nothing! So I thought maybe Mozilla had discussed it on their bug tracker, a long shot but worth a try. Bingo! This bug led me to this bug, on webkits bug tracker don’t ask why the search didn’t bring this up, and then onto this proposal. We’re in business!

How does it work?

So we’ve found the details let’s play with it.

Update: I’ve rolled out drag to desktop across my site for all my demo source files. If you’re using Chrome 5+ just drag the “Download the source files” link to your desktop!

The above demo will, in Chrome 5+, allow you to drag any of the items to your desktop and save them without having to go through the usual save dialog process.

var file = document.getElementById("dragout");
 
file.addEventListener("dragstart",function(evt){
    evt.dataTransfer.setData("DownloadURL",fileDetails);
},false);

From the code above you attach an ondragstart event listener to something you want to “drag out” and save to your file system. On the dragstart event you set the data using the new “DownloadURL” type and pass file information to it.

In order to pass the correct information to the event we access the download_url attribute and use that for our setData call. I’ve made one change that is slightly different to how Gmail sets and gets the attribute.

<a href="Eadui.ttf" id="dragout" draggable="true" data-downloadurl="
    application/octet-stream
    :Eadui.ttf
    :http://thecssninja.com/gmail_dragout/Eadui.ttf">Font file</a>

Instead of creating a new attribute I have instead used the new custom data attributes specified in the HTML5 spec. While not officially supported by Chrome yet we can still use it and add a simple test for support and fork the code either way.

The custom attribute needs three things specified that are separated by colons in order for it to work. The files mime type, the name you wish it to be saved as (this can be anything) and the url to where the file can be downloaded from.

var fileDetails;
 
if(typeof file.dataset === "undefined") {
    // Grab it the old way
    fileDetails = file.getAttribute("data-downloadurl");
} else {
    fileDetails = file.dataset.downloadurl;
}

Above I do a check to see if the element supports the dataset attribute if not use getAttribute to grab the value.

A cool finding

Playing around with this new functionality I did find a cool side effect that if I drag a file that’s set the DownloadURL type on the setData method into a page using Firefox 3.6+ that will capture a drop event the dataTransfer file attribute will act as though it’s captured a local file and can be manipulated with the FileAPI e.g. In my font dragr web app if I drag a font file that’s been attached to an email it will render the font as though I’ve dragged it from my local file system! Doing the same with Chrome 6, which also supports file attribute on the dataTransfer property, will ignore the drop.

Predicting the next challenge from Google

So what do I think the Gmail team will do next? Since they announced, and are now starting, their 6 week release cycle of chrome. I foresee the ability to upload folders not just individual files, being able to capture a photo from your web cam straight into an embedded picture using the proposed media capture proposal. Whatever it is I’m sure it’ll knock everyone’s socks off and make me rack my brain in trying to figure it out.

Short URL: http://cssn.in/ja/028