HTML5 Doctor » JavaScript APIs

Introducing Web SQL Databases

Remy Sharp — Wed, 24 Feb 2010 10:15:39 +0000

The Web SQL database API isn’t actually part of the HTML5 specification, but it is part of the suite of specifications that allows us developers to build fully fledged web applications, so it’s about time we dig in and check it out.

What’s in the box?

If you haven’t guessed from the overly verbose specification title, Web SQL Databases is a spec that brings SQL to the client side. If you have a back-end developer’s background, then you’ll probably be familiar with SQL and happy as a pig in muck. If not, you might want to learn some SQL before you start hacking around, Google’s your friend here.

The specification is based around SQLite (3.1.19), but having come from MySQL myself, it’s all pretty much the same (sorry for the sweeping statement!).

For an example of Web SQL Databases working, have a look at the Twitter HTML5 chatter demo I put together. It uses SQL and the WHERE clause to narrow down the recent chat about HTML5 on Twitter (it will work in Safari, Chrome and Opera 10.50).

There are three core methods in the spec that I’m going to cover in this article:

openDatabase
transaction
executeSql

Support is a little patchy at the moment. Only Webkit (Safari, SafariMobile and Chrome) and Opera 10.50 (ATOW alpha on Mac) support web databases. Fellow Doctor Bruce Lawson has told me that Firefox are holding off as they feel there’s a better implementation than SQLite (though I hope it’s similar, whatever they pick). Either way, I’d definitely recommend checking out the SQLite documentation for the functions that are available.

Because of this patchy support and the simple fact that Webkit had implemented the database spec some time ago, the spec on the W3C is now slightly ahead of the implementations in Safari, while Webkit is still catching up. On the other hand, since Opera has only just added support, it’s closer to the spec (I’ll mention the differences as we go along).

Nonetheless, it’s fun to play with, so let’s get playing!

Creating and Opening Databases

If you try to open a database that doesn’t exist, the API will create it on the fly for you. You also don’t have to worry about closing databases.

To create and open a database, use the following code:

var db = openDatabase('mydb', '1.0', 'my first database', 2 * 1024 * 1024);

I’ve passed four arguments to the openDatabase method. These are:

Database name
Version number
Text description
Estimated size of database

The missing feature of openDatabase (I’m not sure when it was added) is the fifth argument:

Creation callback

The creation callback will be called if the database is being created. Without this feature, however, the databases are still being created on the fly and correctly versioned.

The return value from openDatabase contains the transaction methods, so we’ll need to capture this to be able to perform SQL queries.

Estimated database size

From the tests I’ve run, only Safari prompts the user if you try to create a database over the size of the default database size, 5MB. The prompt is shown the image below, asking whether you want to grant the database permission to scale up to the next size of database — 5, 10, 50, 100 and 500MB. Opera, on the other hand, builds the database without complaining, which I expect might change later as it’s still in alpha.

Versions

I could be wrong, but everything I’ve tested so far says that versioning in SQL databases is borked. The problem is this:

If you upgrade your database to version 2.0 (e.g., there are some important schema changes since version 1.0), how do you know which visitors are on version 1.0 and which are on version 2.0?

The version number is a required argument to openDatabase, so you must know the version number before you try to open it. Otherwise, an exception is thrown.

Also, changeVersion, the method to change the database version, is not fully supported in Webkit. It works in Chrome and Opera, but not in Safari or Webkit. Regardless, if I can’t determine which version of database the user is on, then I can’t upgrade the user.

A possible workaround is to maintain a state database, something like the ‘mysql’ database in MySQL. This way, you would only have one version of this state database, and within this you would record the current version of any databases that control your application. It’s a hack, but it works.

Transactions

Now that we’ve opened our database, we can create transactions. Why bother with transactions instead of just running our SQL? Transactions give us the ability to rollback. This means that if a transaction — which could contain one or more SQL statements — fails (either the SQL or the code in the transaction), the updates to the database are never committed — i.e. it’s as if the transaction never happened.

There are also error and success callbacks on the transaction, so you can manage errors, but it’s important to understand that transactions have the ability to rollback changes.

The transaction is simply a function that contains some code:

var db = openDatabase('mydb', '1.0', 'my first database', 2 * 1024 * 1024);
db.transaction(function (tx) {
  // here be the transaction
  // do SQL magic here using the tx object
});

I recently uploaded a demo to html5demos.com that demonstrates a transaction rollback in action: Web SQL database rollback demo

In the nightly builds of the browsers, we also have db.readTransaction, which allows only read statements to run on the database. I assume there are performance benefits to using a read-only readTransaction instead of a read/write transaction, most probably to do with table locking.

Now that we’ve got our transaction object (named tx in my example) we’re ready to run some SQL!

executeSql

This is the funnel of love for all your SQL goodness. executeSql is used for both read and write statements, includes SQL injection projection, and provides a callback method to process the results of any queries you may have written.

Once we have a transaction object, we can call executeSql:

var db = openDatabase('mydb', '1.0', 'my first database', 2 * 1024 * 1024);
db.transaction(function (tx) {
  tx.executeSql('CREATE TABLE foo (id unique, text)');
});

This will now create a simple table called “foo” in our database called “mydb”. Note that if the database already exists the transaction will fail, so any successive SQL wouldn’t run. So we can either use another transaction, or we can only create the table if it doesn’t exist, which I’ll do now so I can insert a new row in the same transaction:

var db = openDatabase('mydb', '1.0', 'my first database', 2 * 1024 * 1024);
db.transaction(function (tx) {
  tx.executeSql('CREATE TABLE IF NOT EXISTS foo (id unique, text)');
  tx.executeSql('INSERT INTO foo (id, text) VALUES (1, "synergies")');
});

Now our table has a single row inside it. What if we want to capture the text from the user or some external source? We’d want to ensure it can’t compromise the security of our database (using something nasty like SQL injection). The second argument to executeSql maps field data to the query, like so:

tx.executeSql('INSERT INTO foo (id, text) VALUES (?, ?)', [id, userValue]);

id and userValue are external variables, and executeSql maps each item in the array argument to the “?”s.

Finally, if we want to select values from the table, we use a callback to capture the results:

tx.executeSql('SELECT * FROM foo', [], function (tx, results) {
  var len = results.rows.length, i;
  for (i = 0; i < len; i++) {
    alert(results.rows.item(i).text);
  }
});

(Notice that in this query, there are no fields being mapped, but in order to use the third argument, I need to pass in an empty array for the second argument.)

The callback receives the transaction object (again) and the results object. The results object contains a rows object, which is array-like but isn’t an array. It has a length, but to get to the individual rows, you need to use results.rows.item(i), where i is the index of the row. This will return an object representation of the row. For example, if your database has a name and an age field, the row will contain a name and an age property. The value of the age field could be accessed using results.rows.item(i).age.

That’s all you should need to get started with Web SQL Databases. I’m certain that mini JavaScript libraries are going to emerge to help support working with databases. If you want to find out more about SQL databases (shameless self promotion begins) I just finished the storage chapter for Introducing HTML5, which I’m writing with fellow Doc Bruce, so check that bad boy out too!

Demos

Share and Save:

Introducing Web SQL Databases originally appeared on HTML5 Doctor on February 24, 2010.

Why designers should care about HTML5

Cennydd Bowles — Wed, 14 Oct 2009 13:01:06 +0000

After a while on the fringes of our collective consciousness, HTML5 is finally getting the attention it deserves. The development community (as typified by the SuperFriends) has come together to debate practical elements of the spec, argue over the inclusion of controversial elements, and assess the timeframe over which we can unleash HTML5 in the wild.

However those of us more accustomed to the world of Post-Its, sketches, and .psds – the designers – haven’t been so vocal. Perhaps we’ve been distracted by the bright lights of CSS3 and those surface thrills we’ve longed for. (Rounded corners! Gradients! Transparency!) Or, alternatively, we’ve been in the thrall of @font-face and looking forward to the coming age of passable web typography.

Understandable. But it’s time designers got excited about HTML5 too.

Partly, it’s just good practice. Whatever your flavour of design – visual, web, interaction, user experience – knowing the native technology makes you better at your job. Just as composers should understand the capabilities of the orchestra’s instruments, designers need to understand the language of the web.

But there’s more to HTML5 than simply keeping our skills sharp. It could make a big difference to the way we design for the web.

Semantic elements

Information architects (and, by extension, user experience designers) should be excited by the new HTML5 elements –

and so on. While they won’t immediately revolutionise today’s web, they’re an investment for the future. Doing useful stuff with information is the central theme of IA, and therefore its practitioners should be at the forefront of the new experiences that machine-readable semantics will offer. HTML5 allows us to mark text up in a more meaningful way than a sea of

s, meaning we’ll soon see applications appearing at a sub-page level. We’ve started to scratch the surface – think about the Operator toolbar or customisable UIs à la iGoogle – but we’ll need detailed design thinking to work out how to bring the benefits of semantic richness to the end user.

APIs and other extensions

While it’s clear that some of the HTML5 APIs are far from perfect right now, when they’re refined they will offer us intriguing new opportunities and challenges.

Designers of location-based services should of course find the geolocation API invaluable. The contentEditable attribute gives us further power to make the web truly read/write without resorting to JavaScript and custom interfaces. New input types (eg type="search") can provide extra visual cues about input function, although of course this depends on the solutions chosen by the browser manufacturers.

Until now, it’s been easy to consider our domain as bounded by the viewport and the web server. But HTML5 is another step toward seamlessness: the merging of desktop, offline and online. For instance, the drag and drop API could see the line between online and desktop experience blur further. Local storage could allow for a web-like experience in areas of poor connectivity. This convergence is clearly a good thing, but we must also design how to expose those hidden seams at the user’s request. Users should stay in control of how their locations are published and what data is synchronised to their machine.

, ,

There is of course something of a reported schism between the standards world and the Flash world. Some see the advent of these new media elements (particularly ) as heralding the death of Adobe’s poster child.

I don’t think this is either likely or desirable. Neither technology is perfect. Flash is, of course, proprietary and thus subject to the whims of a third party that stands between browser and user. has known accessibility problems. But the two can live in harmony, if we play to their respective strengths. Some current Flash applications might be better suited to , particularly those based around dynamic visualisation: graphs, animations, infographics. Some applications will benefit from the powerful capabilities of Flash: games, heavily interactive widgets.

This aside, there’s clearly a user experience benefit in not having to rely on an external plugin to play rich media elements, and it will be interesting to see the uptake of the and elements. Although it will initially be down to browser makers to define the interface elements involved, we will need to figure out how to integrate them into everyday web experiences. The good news is that they can be styled in the same way as any other HTML element. If your visual aesthetic relies on slanted images with box shadows, it’s trivial to apply this to video too.

That said, we can’t ignore the elephant in the room: the thorny codec issue. I’m sure we’d all agree that the sooner it’s resolved, the better.

What can designers do?

Only the most patient and detail-oriented designer will relish the idea of reading the spec in full and arguing the finer points on the WHATWG list. That’s just not the way designers roll.

But as a community it’s important that we start talking about HTML5. If you’re new to HTML, now’s a great time to learn. The articles on this site and A preview of HTML5 give useful guidance on the differences between HTML5 and its predecessors. Above all, designers should get chatting with their developer friends: there can’t be many left who no longer have an opinion on this technology. How do they see their practices changing? What can we do today to prepare our sites for the advent of HTML5? How can we build on its strong points to make the web a better place?

We don’t yet know what we’ll accomplish with HTML5, but then it’s not often that the vocabulary of the web changes this deeply. However, one thing is clear: if we prepare now, we have a great chance to bring innovation to our users’ online lives.

This article was jointly published on Ineffable, Cennydd’s personal website.

Share and Save:

Why designers should care about HTML5 originally appeared on HTML5 Doctor on October 14, 2009.

Accessibility & Native Drag and Drop

Remy Sharp — Thu, 23 Jul 2009 13:30:32 +0000

A few days before my native drag and drop article came out Gez Lemon wrote about accessibility in drag and drop, and touched on HTML 5.

I then promised to look at implementing accessibility with native drag and drop, and here’s my findings.

ARIA Support

This was quite easy to add, though only by following Gez’s article. Since I already had events for drag start, I just needed to add drag end to clean up and remove the ARIA effects.

I added the following to the dragstart event:

addEvent(dragItems, 'dragstart', function (event) {
  // via ARIA say the element has been grabbed
  this.setAttribute('aria-grabbed', 'true');
  // code continues...

The added a new dropend event:

addEvent(dragItems, 'dragend', function (event) {
  // remove the ARIA grab attibute when we're not dragging
  this.setAttribute('aria-grabbed', 'false');
});

The effectAllowed and dropEffect combo was difficult to work out at first, though probably because I was playing with link and reference, whereas I should have been playing with move or copy. That said, a note about move and copy, move is a type of copy, with a clean up function to delete afterwards. Once I had this combo correct, the drop effects worked.

The changes required were to:

On drag: on all the drop targets add: setAttribute('aria-dropeffect', 'copy')
On drag: set the allowedEffect on the drag event: event.dataTransfer.effectAllowed = 'copy';
On drop: say what we’ll accept: event.dataTransfer.dropEffect = 'move';
On dragend: remove the drop effect from the drop targets: removeAttribute('aria-dropeffect')

The big problem for me was that I couldn’t truely test this.

Update: between the time I had finished my code and writing this article, NVDA (the Windows open source screenreader) announced that they recieved support from Yahoo!, and that ARIA drag and drop support is in their development roadmap.

The full working version of native drag and drop with ARIA support is available here: native drag and drop with ARIA support (source code)

Keyboard Support

Keyboard, sadly, is a whole different story.

I was able to replicate a lot of the keyboard features that Gez included in his demo. This included setting the tabIndex = 0 to allow the elements to tab to (superb trick by the way), included highlighting the drop targets as we drag.

However, the problem was: I wanted the user to be able to start the drag operation using the keyboard. Initially looking at the spec I couldn’t see that it was supposed to be supported (which it turns out, it is).

I started going down the path of using the keyboard to trigger drag events. I was able to replicate the drag event being triggered from the keyboard (like space starts the event), however, and this is a biggie, I couldn’t replicate the dataTransfer object. I tried faking it. I tried giving it nothing. I tried all kinds of random attempts to trick the browser in to giving me the object. It’s a no goer.

As it turns out, there is keyboard support written in to the spec (though in my personally opinion it’s not completely obvious to an author reading). The drag and drop operations should work like a copy and paste operation.

This is very clever, and I like it. Tab round to the dragable element, copy using the keyboard, which triggers the dragstart event, which I can then add classes to the drop targets, and make them tabbable. The user then tabs round to the drop targets, and pastes. This triggers the drop event and we’re all good.

No browsers support this keyboard event model.

I’ve raised bug for Mozilla and Webkit. They’ve both had comments on, and in both cases I’m not 100% sure what the comments mean, but speaking to the people involved via IRC, they’ve both said if it’s in the spec, it should be in the browser.

Let’s hope they do something about it. Now, how do I report a bug in IE…?!

Share and Save:

Accessibility & Native Drag and Drop originally appeared on HTML5 Doctor on July 23, 2009.

Native Drag and Drop

Remy Sharp — Thu, 09 Jul 2009 09:00:13 +0000

Along with an army of JavaScript APIs, HTML 5 comes with a Drag and Drop (DnD) API that brings native DnD support to the browser making it much easier to code up.

HTML 5 DnD is based on Microsoft’s original implementation which was available as early as Internet Explorer 5! Now currently supported in IE, Firefox 3.5 and Safari 4.

We’re going to look how to implement DnD and review some of the issues (or hoops we have to jump through) with the current implementations now.

My First Drag and Drop

DnD requires only a few things to work:

Something to drag
A drop target
JavaScript event handlers on the target to tell the browser it can drop

The following elements are draggable by default: elements and elements (with an href).

If you want to drag a different element, you need to set the draggable attribute to true. That’s according to the spec, but to get it to work in Safari and Firefox there’s a little more that you need to do, which we’ll come on to.

If you want to skip the code walk through, here’s the simple drag and drop (source code)

Here’s our example markup:





Basic Drag and Drop

Note: the included h5utils.js script is a small library to trigger HTML 5 elements and to give me cross browser event binding.

Currently the elements can be dragged, but they can’t be dropped (this is the browser’s default).

To drop elements we need to:

Tell the browser that the element can be dragged over a specific point
Handle the drop event

To tell the browser we can drop in this element, all we have to do is cancel the dragover event. However, since IE behaves differently, we need to do the same thing for the dragenter event.

Here’s the code for basic drop handling:

var drop = document.querySelector('#drop');

// Tells the browser that we *can* drop on this target
addEvent(drop, 'dragover', cancel);
addEvent(drop, 'dragenter', cancel);

addEvent(drop, 'drop', function (event) {
  // stops the browser from redirecting off to the text.
  if (event.preventDefault) {
    event.preventDefault();
  }

  this.innerHTML += '' + event.dataTransfer.getData('Text') + '';

  return false;
});

function cancel(event) {
  if (event.preventDefault) {
    event.preventDefault();
  }
  return false;
}

Note for this code, I’m using addEvent where you’d normally see element.addEventListener, it’s from the h5utils.js library to support IE.

In the JavaScript we are:

Searching for the drop target in the DOM using document.querySelector (which returns the first result only)
When dragover event is fired (when the user drags the element over another), it will trigger the function called ‘cancel’ (at the bottom of the code above) which will prevent the default browser action
Do the same for dragenter to support IE
Bind the drop event, and within there grab some data about what was dropped.

dragover & dragenter

By cancelling this event, we’re telling the browser this element that we’re over is the one you can release and drop upon.

I’m still not entirely sure why there’s a difference here, but Firefox and friends needs preventDefault on the event, and IE requires the return false. Note that the examples out in the wild that use inline JavaScript (yuk, bad), the preventDefault is supposed to be implicit, so you won’t see it in the code.

drop

To show what was dropped, we need to do two things:

Cancel the default browser action. This is to ensure that if we drop a link, the browser doesn’t go off and surf to that location
Get the contents out of the dataTransfer object

The cancelling of the browser default is, again, done using the preventDefault and return false.

If we don’t set the dataTransfer data manually (which I’ll show you later), the default key is set to Text. So this might be the value of an href of an element, or it might be src address.

Doing More with Drag’n Drop

There’s a number of extra bits in the spec other than just dragging images.

Here’s a few bits that I can see being useful:

Being able to drag any element
More complex data types, other than text
Set a different drag icon/image when dragging the element

Dragging Anything

If we change the to

tags with background images, I still want to be able to drag them around the page, and drop them in to my container.

The HTML 5 spec says it should be as simple as adding the following attributes to the markup of the elements in question:

draggable="true"

However, this doesn’t work completely for Safari or Firefox.

For Safari you need to add the following style to the element:

[draggable=true] {
  -khtml-user-drag: element;
}

This will start working in Safari, and as you drag it will set a default, empty value with the dataTransfer object. However, Firefox won’t allow you to drag the element unless you manually set some data to go with it.

To solve this, we need a dragstart event handler, and we’ll give it some data to be dragged around with:

var dragItems = document.querySelectorAll('[draggable=true]');

for (var i = 0; i < dragItems.length; i++) {
  addEvent(dragItems[i], 'dragstart', function (event) {
    // store the ID of the element, and collect it on the drop later on
    event.dataTransfer.setData('Text', this.id);
  });
}

Here’s a working demo of drag and drop anything (source code)

More Complex Data Types

You’ve already seen how we can use dataTransfer.setData(format, string) to associate some data in the example above.

You can also use this key/value pair to store more data, but you’re limited to storing strings only.

One way I would get around this is to have a data lookup, where the key of the lookup may be the ID of the element, and then I can de-reference the data on the drop event.

For example:

var people = {
  rem : {
    name : "Remy Sharp",
    blog : "http://remysharp.com"
  },
  brucel : {
    name : "Bruce Lawson",
    blog : "http://brucelawson.co.uk"
  }
  // etc...
}

var dragItems = document.querySelectorAll('[draggable=true]');

for (var i = 0; i < dragItems.length; i++) {
  addEvent(dragItems[i], 'dragstart', function (event) {
    // store the ID of the element, and collect it on the drop later on
    event.dataTransfer.setData('Text', this.id);
  });
}

addEvent(drop, 'drop', function (event) {
  // stops the browser from redirecting off to the text.
  if (event.preventDefault) {
    event.preventDefault();
  }

  var person = people[event.dataTransfer.getData('Text')];

  this.innerHTML += '' + person.name + '';

  return false;
});

Here’s a working demo of drag and drop with associated data (source code)

Obviously this isn’t the most ideal situation, but there’s also the possibility to set other content types in the drag data, which should produce some interesting apps in the future.

Drag Icon

Along with several other options with the dragstart event, you can also set a drag image, i.e. what you see under your cursor.

You can create a DOM fragment, and then associate the fragment with the dataTransfer using setDragImage(element, x, y).

So we can add the following to our example to use a custom drag image:

var dragIcon = document.createElement('img');
dragIcon.src = 'http://twivatar.org/twitter/mini';

Which creates an image element, and how within the dragstart event, we’ll set the drag image:

addEvent(dragItems[i], 'dragstart', function (event) {
  // store the ID of the element, and collect it on the drop later on
  event.dataTransfer.setData('Text', this.id);
  event.dataTransfer.setDragImage(dragIcon, -10, -10);
  return false;
});

This sets the custom drag icon 10 pixels below the cursor, as seen in this example: drag and drop with custom image (source code)

Native Drag

There’s lots of Drag and Drop JavaScript libraries available, but what I’d like to see, is native DnD support falling back to library based. However, I know for a fact that some libraries, including jQuery, construct a custom event when passed in to the event handler which means, currently, you can’t use the dataTransfer object, so you’ll have to rely on binding the events yourself. I’m sure this will change soon.

There’s lots more in Drag and Drop but this should be enough to go and play with now!

As for me, I'll be updating the Drag and Drop demos on HTML5demos.com to see if I can add ARIA support and capture a screencast of it running. Watch this space!

Further Reader

Share and Save:

Native Drag and Drop originally appeared on HTML5 Doctor on July 9, 2009.

More Complex Data Types

Drag Icon

Native Drag

Further Reader

Related Posts:

HTML5 Doctor » JavaScript APIs

Introducing Web SQL Databases

What’s in the box?

Creating and Opening Databases

Estimated database size

Versions

Transactions

executeSql

Demos

Related Posts:

Why designers should care about HTML5

Semantic elements

Accessibility & Native Drag and Drop

ARIA Support

Keyboard Support

Related Posts:

Native Drag and Drop

My First Drag and Drop

dragover & dragenter

drop

Doing More with Drag’n Drop

Dragging Anything