Introduction to HTML5 History API

Before the advent of HTML5, the only thing we could not control and manage (without reloading content or hacks from location.hash) is the story of one taba. With the advent of the HTML5 history API, everything has changed - now we can walk through history (previously we could also), add elements to history, respond to history transitions and other usefulness. In this article we will look at the HTML5 History API and write a simple example illustrating its capabilities.

Basic Concepts and Syntax

The History API relies on one DOM interface, the History object. Each tab has a unique History object, which is located in window.history . History has several methods, events, and properties that we can control from JavaScript. Each page of a tab (Document object) is an object of the History collection. Each history element consists of a URL and / or a state object (a state object); it can have a title (title), a Document object, form data, a scroll position, and other information associated with the page.



The main methods of the History object:

1. window.history.length : Number of records in the current history session
2. window.history.state : Returns the current history object
3. window.history.go(n) : A method that allows you to walk through history. An argument is passed as an argument, relative to the current position. If 0 is transmitted, the current page will be updated. If the index goes beyond history, then nothing will happen.
4. window.history.back() : Method identical to go(-1)
5. window.history.forward() : Method identical to go(1)
6. window.history.pushState(data, title [, url]) : Adds a history item.
7. window.history.replaceState(data, title [, url]) : Updates the current history item

To go 2 steps back in history, you can use:

 history.go(-2) 

To add history elements we can use history.pushState :

 history.pushState({foo: 'bar'}, 'Title', '/baz.html') 

To change the history record, we can use history.replaceState :

 history.replaceState({foo: 'bat'}, 'New Title') 

Living example

Now we know the basics, let's look at a living example. We will make a web file manager that will allow you to find the URI of the selected image ( see what happens at the end ). The file manager uses a simple javascript file structure. When you select a file or folder, the picture is dynamically updated.



We use data-* attributes to store the header of each image and use the dataset property to get this property:

 <li class="photo"> <a href="crab2.png" data-note="Grey crab!">crab2.png</a> </li> 

For everything to work quickly, we load all the images and update the src attribute dynamically. This acceleration creates one problem - it breaks the back button, so you cannot go forward or backward through the pictures.

')

HTML5 history comes to the rescue! Every time we select a file, a new history record is created and the location document is updated (it contains the unique URL of the image). This means that we can use the back button to crawl our images, while in the address bar we will have a direct link to the picture, which we can bookmark or send to someone.

Code

We have 2 divas. One contains the folder structure, the other contains the current image. The entire application is managed using javascript. Only the most important moments will be covered. The source code of the example is very short (about 80 lines); look at it after reading the entire article.



The bindEvents method hangs handlers for the popstate event, which is called when the user navigates through the history and allows the application to update its state.

 window.addEventListener('popstate', function(e){ self.loadImage(e.state.path, e.state.note); }, false); 

The event object that is passed to the popstate event popstate has a state property — this is the data that we passed as the first argument to pushState or replaceState .



We hang up a handler on a click event on a div, which represents our file structure. Using the event delegation, we open or close a folder or load a picture (with adding an entry to the history). We look at the parent's className in order to understand which element we clicked on:

- If this is the folder we open or close it

- If this is a picture, then we show it and add an element of history.

 dir.addEventListener('click', function(e){ e.preventDefault(); var f = e.target; //   if (f.parentNode.classList.contains('folder')) { //     self.toggleFolders(f); } //   else if (f.parentNode.classList.contains('photo')){ note = f.dataset ? f.dataset.note : f.getAttribute('data-note'); //   self.loadImage(f.textContent, note); //    history.pushState({note: note, path:f.textContent}, '', f.textContent); } }, false); 

The method that changes the content of the image and updates its caption is very simple:

 loadImage: function(path, note){ img.src = path; h2.textContent = note; } 

We got a simple application that demonstrates the capabilities of the updated interface of the History object. We use pushState to add a history item and a popstate event to update the page content. In addition, when clicking on a picture, we get its address in the address bar, which we can save or send to someone.

When can I use it?

Firefox 4+

Safari 5+

Chrome 10+

Opera 11.5+

iOS Safari 4.2+

Android 2.2+

IE ???

List of browsers supporting the history API

Where is it used?

1. Facebook

2. Github - navigating the project tree

3. ???

Read

1. Manipulating History for Fun & Profit

2. WHATWG HTML5 history API

3. W3C history API Spec

4. MDC Manipulating the browser history

5. History.js - the script emulates the HTML5 history API (location.hash magic) in those browsers that do not support it