PLAYING NICELY WITH OTHERS

You do not always need to know how a script or program works, as long you know how to ask it to do something, and how to process its response. The questions you can ask and the format of the answers form the API.

WHAT THE API CAN DO

If there is a script or program that offers functionality you need, consider using it rather than writing something from scratch.

Because each script, program, or platform has different features, the first thing you need to do is understand what the API allows you to do. For example:

• The DOM and jQuery APIs allow you to access and update a web page that is loaded in the browser and respond to events.
• Facebook, Google+, and Twitter APIs let you to access and update profiles and create status updates on their platforms.

When you know what the API allows you to do, you can decide if it is the right tool for the job.

HOW TO ACCESS IT

Next you need to know how to access the functionality of the API in order to use it.

The DOM's functionality is built into the JavaScript interpreter in the browser.

With jQuery you need to include the jQuery script from your server or a CDN in your pages.

Facebook, Google+, Twitter, and other sites provide various ways to access the functionality of their platforms using APIs.

THE SYNTAX

Finally, you need to learn how to ask the API to do something and the format in which you should expect any replies.

As long as you know how to call a function, create an object, and access the properties and methods of an object, you will be able to use any JavaScript API.

This chapter introduces you to a range of APIs so you gain the confidence to learn more about them and other APIs.

HTML5 JAVASCRIPT APIS

First, we will look at some of the new HTML5 APIs.
Along with the markup in the HTML5 specification, a set of APIs define that describe how to interact with features of web browsers.

WHY HTML5 HAS APIS

As technologies evolve, so does the browsing experience. For example, smartphones may have smaller screens and less power than the latest desktop computers; but they include features that are rarely found on desktop machines such as accelerometers and GPS.

The HTML5 specification has not only added new markup, but also includes a new set of JavaScript APIs that standardize how you can make use of these new features in any device that implements them.

WHAT THEY COVER

Each of the HTML5 APIs focuses on one or more objects that browsers implement to deliver specific functionality.

For example, the geolocation API describes a geolocation object that lets you ask users for their location and two objects that handle the browsers response.

There are also APIs that offer improvements over existing functionality. For example, the web storage API lets you store information within the browser without relying on cookies.

WHAT YOU'LL LEARN

There is not space for an exhaustive reference of each of the HTML5 APIs (there have been whole books dedicated to these new HTML5 features). But you will meet three of the APIs and see examples of how to work with them.

This should get you used to using the HTML5 APIs so that you can then go on and learn more about them as you need them. You will also learn how you can test to see whether or not a browser supports the functionality in any of the APIs.

FEATURE DETECTION

When you write code that uses the HTML5 APIs (or any other new feature in a web browser), you may need to check if the browser supports that feature before your code tries to use it.

The HTML5 APIs describe objects that browsers use to implement new functionality. For example, you are about to meet an object called the geolocation object that is used to determine a user's location. However, this object is only supported in modern browsers, so you need to check whether a browser supports this it before trying to use the object.

You may not be surprised to hear that there are some cross-browser issues with feature detection.

For example, in the case of the code above, there was a bug in IE9 which could result in a memory leak when you check for the geolocation object. This could slow down your pages.

It is possible to check whether a browser supports an object using a conditional statement.

If the browser supports the object, then the condition will return a truthy value and the first set of statements are run. If it is not implemented, the second set of statements is run.

if (navigator.geolocation) {
  // Returns truthy so it is supported
  // Run statements in this code block
} else {
  // Not supported / turned off
  // Or user rejected request
}

Luckily, there is a library called Modernizr, which takes away the hassles of cross-browser issues (like jQuery for feature detection). It is a better way to check if the browser supports recent features. The script is regularly updated and refined to deal with cross-browser issues as they are discovered, so they are less likely to affect you.

MODERNIZR

Modernizr is a script you can use in your pages to tell whether the browser supports features of HTML, CSS, and JavaScript. It will be used in the coming HTML5 API examples.

HOW TO GET MODERNIZR

First, you need to download the script from the Modernizr.com website, where you will see:

• A development version of the script. It is uncompressed and features every check that the script is capable of performing.
• A tool (see screenshot below) that lets you select which features you want to test for. You can then download a custom version of the script that only contains the checks you need. On a live site, you should not test for features that you do not use as it would slow your site down.

In our examples, Modernizr is used near the end of the page just before the script that uses it. But you may see Modernizr included in the <head> of an HTML page (if the content of the page is uses features that you are testing for).

HOW MODERNIZR WORKS

When you include the Modernizr script in your page, it adds an object called Modernizr, which tests whether the browser supports the features that you specified that it should test for. Each feature you want it to test becomes a property of the Modernizr object. Their values are a Boolean (true or false) that tell you if a feature is supported.

You can use Modernizr as a condition like this: If Modernizr's geolocation property returns true run the code in the curly braces:

if (Modernizr.geolocation) {
  // Geolocation is supported
}

MODERNIZR PROPERTIES

In the screenshot on the left, you can see some of the features that Modernizr can check for. To see a full list of Modernizr's properties, visit:
modernizr.github.io/Modernizr/test/index.html

GEOLOCATION API: FINDING USERS' LOCATIONS

An increasing number of sites offer extra functionality to users who disclose their location. The users' location can be requested using the geolocation API.

WHAT THE GEOLOCATION API DOES

Browsers that implement the geolocation API let users share their location with websites. The location data is provided in the form of longitude and latitude points. There are several ways for the browser to determine its location, including using data from its IP address, wireless network connection, cell towers, or GPS hardware.

In some devices, the geolocation API can give you more data along with longitude and latitude. But, we focus on these features because they have the most support. Having seen how to use them, if you need to work with the other features, you will be able to.

HOW TO ACCESS GEOLOCATION

The geolocation API is available by default in any browser that supports it (just like the DOM is). It was first supported in IE9, Firefox 3.5, Safari 5, Chrome 5, Opera 10.6, iOS3, and Android 2.

Browsers that support geolocation allow users to turn the feature on and off. If it is on, the browser will ask users if they want to share data for each individual web site that requests that information.

The way in which the browser asks the user if they will share location data differs from one browser to the next and one device to the next.

The geolocation API relies on an object called geolocation. If you want to try and make use of the user's location, first you need to check if the browser supports this object. This example will use the Modernizr script is used to perform this check.

1. A conditional statement is used to check whether the browser supports geolocation.

2. If geolocation is supported, the browser returns a truthy value and the first set of statements run. They request the user's location using the geolocation object's getCurrentPosition()method.

3. If geolocation is not supported, then a second set of statements is run.

if (Modernizr.geolocation) {
  // Returns truthy so it is supported
  // Run statements in this code block
} else {
  // Not supported / turned off
  // Or user rejected request
}

Once you call the getCurrentPosition() method, the code continues onto the next line because it is an asynchronous request (like the Ajax calls in the last chapter). The request is asynchronous because the browser will take a while to determine the user's location (and you do not want the rest of the page to stop loading while the browser works out where the user is). Therefore, the method has two parameters: getCurrentPosition(success, fail)

success is the name of a function to call if the longitude and latitude are successfully returned. This method will automatically be passed an object called position, which holds the user's location.

fail is the name of a function called if the details cannot be obtained. This method will automatically be passed an object called PositionError containing details about the error.

So in all, there are three new objects you need to use in order to work with the geolocation API: geolocation, position, and PositionError. Their syntax is shown on the next page.

THE GEOLOCATION API

There are three objects involved in adding geolocation to your web page. The tables demonstrate how API documentation typically describes the objects, properties, and the methods you can use.

geolocation OBJECT

The geolocation object is used to request location data. It is a child of the navigator object.

Position OBJECT

If a user's location is found, a Position object is sent to the callback function. It has a child object called coords whose properties hold the user's location. If a device supports geolocation, it must provide a minimum amount of data (see the required column); other properties are optional (they may depend on the device's capabilities).

PositionError OBJECT

If location is not determined, the callback function is passed the PositionError object.

WEB STORAGE API: STORING DATA IN BROWSERS

Web storage (or HTML5 storage) lets you store data in the browser. There are two different types of storage: local and session storage.

HOW TO ACCESS THE STORAGE API

Before HTML5, cookies were the main mechanism for storing information in the browser. But cookies have several limitations, most notably they are:

• Not able to hold much data.
• Sent to the server every time you request a page from that domain.
• Not considered secure.

Therefore, HTML5 introduced a storage object. There are two different flavors of the storage object, localStorage and sessionStorage. Both use the same methods and properties. The differences are how long the data is stored for and whether all tabs can access the data that is being stored.

Commonly, browsers store 5MB of data per domain in a storage object. If a site tries to store more than 5mb of data, the browser will usually ask the user whether they want to allow this site to store more information (never rely on users agreeing to give a site more space).

The data is stored as properties of the storage objects (using in key/value pairs). The value in the pair is always a string. To protect the information that a website stores in these storage objects, browsers employ a same origin policy, which means data can only be accessed by other pages in the same domain.

These four parts of the URL must match:

1. Protocol: The protocol must be a match. If data was stored by a page that starts http, the storage object cannot be accessed via https.

2. Subdomain: The subdomain name must match. For example, maps.google.com cannot access data stored by www.google.com.

3. Domain: The domain name must match. For example, google.com cannot access local storage from facebook.com.

4. Port: The port number must match. Web servers can have many ports. Usually a port number is not specified in a URL, and the site uses port 80 for web pages, but the port number can be changed.

The storage objects are just one of the new HTML5 APIs for storing data. Others include access to the file system (through the FileSystem API) and client side databases such as the Web SQL database.

HOW TO ACCESS THE STORAGE API

Both of these objects are implemented on the window object, so you do not need to prefix the method names with any other object name.

To save an item into the storage object, you use the setItem() method, which takes two parameters: the name of the key and the value associated with it.

To retrieve a value from the storage object you use the getItem() method, passing it the key.

// Store information
localStorage.setItem(‘age’, ‘12’);
localStorage.setItem(‘color’, ‘blue’);
// Access information and store in variable
var age = localStorage.getItem(‘age’);
var color = localStorage.getItem(‘color’);
// Number of items stored
var items = localStorage.length;

Data for the storage objects is stored and accessed in a synchronous manner: all other processing stops while the script accesses or saves the data. Therefore, if a lot of data is regularly accessed or stored, the site can appear slower to use.

You can also set and retrieve keys and values of the storage objects as you might with other objects using dot notation.

The storage objects are commonly used to store JSON-formatted data. The JSON object's:

• parse() method is used to turn the JSON-formatted data into a JavaScript object
• stringify() method is used to transform objects into JSON-formatted strings

// Store information (object notation)
localStorage.age = 12;
localStorage.color = ‘blue’;
// Access information (object notation)
var age = localStorage.age;
var color = localStorage.color;
// Number of items stored
var items = localStorage.length;

Below, you can see a table that shows the methods and property of the storage objects. This table is very similar to the one you saw for the geolocation API and is indicative of the types of tables you see in documentation for APIs.

HISTORY API & PUSHSTATE

If you move from one page to another, the browser's history remembers which pages you visited. But Ajax applications do not load new pages, so they can use the history API to update the location bar and history.

WHAT THE HISTORY API DOES

Each tab or window in the browser keeps its own history of pages you have viewed. When you visit a new page in that tab or window, the URL is added to the list of pages you have visited in the history.

Because of this, you can use the back and forward buttons in a browser to move between pages you have visited in that tab or window. However, on sites that use Ajax to load information, the URL is not automatically updated (and the back button might not show the last thing that the user was viewing).

HTML5's history API can help fix this problem. It lets you interact with the browser's history object:

• You can update the browser history stack using the pushState() and replaceState() methods.
• Extra information can be stored with each item.

As you will see, information can be added to the history object when an Ajax request is made, and the user can be shown the right content when they press back or forward buttons.

Browsing pages:
As you browse, the URL in your web browser's address bar updates. The page is also added to the top of something called the history stack.

Pressing back: takes you back down the stack
Pressing forward: takes you up the stack (where possible)
New page: if you request a new page, it will replace anything above the current page in the stack

State refers to the condition that something is in at a particular time. The browser history is like a pile (or stack) of states, one on top of the other. The three methods on this page allow you to manipulate the state in browsers.

ADDING INFORMATION TO THE HISTORY OBJECT

pushState() adds an entry to the history object. replaceState() updates the current entry. Both take the same three parameters (below), each of which updates the history object.

Because the history object is a child of the window object, you can use its name directly in the script; you can write history.pushState(), you do not need to write window.history.pushState().

1. The history object can store information with each item in the history. This is provided in the state parameter and can be retrieved when you go back to that page.

2. Currently unused by most browsers, the title parameter is intended to change the title of the page. (You can specify a string for this value, ready for when browsers support it.)

3. The URL that you want the browser to show for this page. It must be on the same origin as the current URL and it should show the correct content if the user goes back to that URL.

GETTING INFORMATION FROM THE HISTORY OBJECT

Adding content to the browser history is only part of the solution; the other half is loading the right content when the user presses the back or forward buttons. To help show the right content, the onpopstate event fires whenever the user requests a new page.

This onpopstate event is used to trigger a function that will load the appropriate content into the page. There are two ways to determine what content should be loaded into the page:

• The location object (which represents the browser's location bar)
• The state information in the history object

The location object:
If the user presses back or forward, the address bar will update itself, so you can get the URL for the page that should be loaded using location.pathname (the location object is a child of the window object and its pathname property is the current URL). This works well when you are updating an entire page.

The state:
Because the first parameter of the pushState() method stores data with the history object for that page, you can use it to store JSON-formatted data. That data can then be loaded directly into the page. (This is used when the new content loads data rather than a traditional web page.)

THE HISTORY OBJECT

The HTML5 history API describes the functionality of the history object in modern web browsers. It lets you access and update the browser history (but only for pages the user visited on your site).

Even if the visitor is not taken to a new page in the browser window (for example, when only a part of the page is updated using Ajax), you can modify the history object to ensure that the back and forward buttons work as the user would expect them to on non-Ajax pages.

Again, the table below is indicative of the kind you might see in API documentation. As you become comfortable using the methods, properties, and events of an object you will find it easier to work with all kinds of APIs.

history OBJECT

SCRIPTS WITH APIS

There are hundreds of scripts available for free on the web. Many have an API you need to use to get them to work for you.

SCRIPT APIS

Lots of developers share their scripts through a range of websites. Some are relatively simple scripts with a single purpose (such as sliders, lightboxes, and table sorters). Others are far more complicated and can be used for a range of purposes (such as jQuery).

In this section, you will meet two different types of scripts whose code you can make use of when you have learned their API:

• A set of jQuery plugins known as jQuery UI.
• A script that makes it easier to create web apps called AngularJS.

JQUERY PLUGINS

Many developers have written code that adds extra functionality to jQuery. These scripts add methods to extend the jQuery object, which are known as jQuery plugins.

When you use these plugins, first you include the jQuery script, followed by the plugin script. Then, when you select elements (as you do with standard in jQuery methods), the plugin allows you to apply new methods that it has defined to that selection, offering new functionality that was not in the original jQuery script.

ANGULAR

Angular.js is another JavaScript library, but it is very different from jQuery. Its purpose is to make it easier to develop web applications.

One of the most striking things is that it allows you to access and update the contents of a page without writing code to handle events, select elements, or update the content of an element. We only have space to provide a very basic introduction to Angular in this chapter, but it does help demonstrate the variety of scripts available.

THIRD-PARTY SCRIPTS

Before writing your own script it can pay to check if someone else has already done the hard work for you (there is no point reinventing the wheel).

It is always a good idea to check:

• Whether it has been updated fairly recently
• That the JavaScript is separate from the HTML
• Reviews of the script if they are available

This helps to ensure that the script uses modern practices and is still being updated. It is also worth noting that the instructions for using a script are not always called an API.

JQUERY UI

The jQuery foundation maintain its own set of jQuery plugins called jQuery UI. They help create user interfaces.

WHAT JQUERY UI DOES

jQuery UI is a suite of jQuery plugins that extends jQuery with a set of methods to create:

• Widgets (such as accordions and tabs)
• Effects (that make elements appear and disappear)
• Interactions (such as drag and drop functionality)

jQuery UI not only provides JavaScript you can use, but it also comes with a set of themes that help control how the plugins look on the page.

If you want fine-grained control over how the jQuery plugins look in the browser, you can also use the theme roller, which gives you more precise control over the appearance of the elements.

HOW TO ACCESS IT

To use jQuery UI, first you must include jQuery in your page; then you must include the jQuery UI script (after the jQuery file).

Versions of jQuery UI are available on the same CDNs as the main jQuery file. But, if you only need part of the jQuery UI functionality, you can just download the relevant parts from the jqueryui.com website. This creates a smaller JavaScript file, which in turn makes the script faster to download.

SYNTAX

Once you have included the jQuery and jQuery UI scripts in the page, the syntax is very similar to using other jQuery methods. You create a jQuery selection and then call a method that will be defined in the plugin.

As you will see, the jQuery UI documentation not only has to explain the JavaScript methods and properties it uses, but also how to structure your HTML if you want to use many of its widgets and interactions.

ANGULARJS

AngularJS is a framework that makes it easier to create web apps. In particular, it assists in creating apps that write, read, update, and delete data in a database on a server.

Angular is based on a software development approach called model view controller or MVC. (It is actually variant on MVC, not strict MVC). To use Angular, first you include the angular.js script in your page, and then it makes a set of tools available to you (just like jQuery does).

The point of MVC is that it separates out parts of a web application, in the same way that front-end developers should separate content (HTML), presentation (CSS), and behavior (JavaScript).

We do not have space to go into Angular in detail, but it introduces another example of a very different script with an API, as well as concepts such as the MVC approach, templating, and data binding. You can download Angular and view the full API at http://angularjs.org.

The View is what the user sees. In a web app, it is the HTML page. Angular lets you create templates with spaces for particular types of content. If the user changes values in the view, commands (1) are sent to up the chain to update the model.
There can be different views of the same data, e.g., users and administrators.

This ViewModel (or controller) will update the view if there are changes to the model, and will update the model if there are changes in the view. The task of keeping data synchronized between the two is known as data binding (2).
For example, if a form in the view is updated, it reflects the changes and updates the server.

In a web app, the Model is usually stored in the database, and managed by server-side code that can access and update the model.

When the model has been updated, change notifications (3) are sent to the ViewModel. This info can be passed onto the View to keep it updated.

PLATFORM APIS

Many large websites expose their APIs that allow you to access and update the data on their sites, including Facebook, Google, and Twitter.

WHAT YOU CAN DO

Each site offers different capabilities, for example:

• Facebook offers features such as allowing people to like sites or add comments and discussion to the bottom of a web page.
• Google Maps lets you to include various types of maps in your pages.
• Twitter allows you to display your latest tweets on your web pages or send new tweets.

By exposing some of the functionality of their platforms these companies are advertising their sites and encouraging people back to them. This in turn increase their total amount of activity (and their revenue).

Be aware that companies can change either how you access APIs or change what you are allowed to use the APIs for.

HOW TO ACCESS

On the web, you can access several of these platform APIs by including a script they provide in your page. That script will typically create an object (just like the jQuery script adds a jQuery object). In turn, that object will have methods and properties that you can use to access (and sometimes update) the data on that platform.

Most sites that offer an API will also provide documentation that explains how to use its objects, methods, and properties (along with some basic examples).

Some of the larger sites provide pages where you can get code that you can copy and paste into your site without even needing to understand the API.

Facebook, Google, and Twitter have all made changes to both how you access their APIs and what you can use them for.

THE SYNTAX

The syntax of an API will vary from platform to platform. But they will be documented using tables of objects, methods, and properties like those you saw in the first section of this chapter. You may also see sample code that demonstrates tasks people commonly use the API for (like the examples you have seen in this chapter).

Some platforms offer APIs in multiple languages, so that you can interact with them using server-side languages such as PHP / C# as well as using JavaScript.

In the rest of this chapter we will be focusing on the Google Maps API as an example of what you can do with platform APIs.

If you work on a site for a client, make them aware that APIs can change (and that could result in recoding pages that use them).

GOOGLE MAPS API

Currently, one of the most popular APIs in use on the web is the Google Maps API, which allows you to add maps to web pages.

WHAT IT DOES

The Google Maps JavaScript API allows you to show Google maps in your web pages. It also allows you to customize the look of the maps and what information is shown on them.

You may find it helpful to look at the documentation for the Google Maps API while going through this example. It will show you other things that you can do with the API. https://developers.google.com/maps/

WHAT YOU'LL SEE

We only have space to show a few of the features of the Google Maps API, as it is very powerful and contains a lot of advanced features. But the examples in this chapter will get you used to working with its API.

You will start by seeing how to add a map to your web pages, then you will see how to change the controls, and finally how to change the colors and add markers on top of the map.

API KEY

Some APIs require that you register and request an API key in order to get data from their servers. An API key is a set of letters and numbers that uniquely identify you to the application so the owners of the site can track how much you use the API and what you use it for.

At the time of writing, Google allowed websites to call their maps API 25,000 times per day for free without an API key, but sites that consistently make more requests are required to use a key and pay for the service.

If you run a busy site, or the map is part of the core application, it is good practice to use an API key with Google Maps because:

• You can see how many times your site requests the API
• Google can contact you if they change terms of service or charge for use

To get a Google API key, see https://cloud.google.com/console

BASIC MAP SETTINGS

Once you have included the Google Maps script in your page, you can use their maps object. It lets you display Google maps in your pages.

CREATING A MAP

The maps object is stored within an object called google. This creates scope for all Google objects.

To add a map to your page, you create a new map object using a constructor: Map(). The constructor is part of the maps object, and it has two parameters:

• The element into which you want the map drawn
• A set of map options that control how it is displayed given using object literal notation

Zoom level is typically set using a number between 0 (the full earth) and 16. (Some cities can go higher.)

MAP OPTIONS

The settings that control how the map should look are stored inside another JavaScript object called mapOptions. It is created as an object literal before you call the Map() constructor. In the JavaScript on the right, you can see that the mapOptions object uses three pieces of data:

• Longitude and latitude of the center of the map
• The zoom level for the map
• The type of map data you want to show

The images that make up the map are called tiles. Four map types each show a different style of map.

CHANGING CONTROLS

To show or hide the controls, use the control name followed by a value of true (to show it) or false (to hide it). Although Google Maps tries to prevent overlaps, use judgement to position controls on your map.