Template:Book title/doc

This template uses the Google Books API to retrieve and display a book title for a given ISBN.

It is designed to work with the  produced by Special:BookSources. That page removes punctuation from the supplied ISBN before generating, so this template does not need to handle punctuated or other formatted ISBN numbers.

This template uses JavaScript to manage the connection to the Google Books API. Book titles are retrieved asynchronously, and after the page has loaded.

Usage
Invoke with:

Parameters:
 * isbn: The ISBN for which the title is needed. Must be supplied. Should be a valid 10 character or 13 character ISBN.
 * loading: Value to show during the Google Books API retrieval. Optional. Default is Loading ....

Parameters may also be supplied by position, in the order shown above. This template may be transcluded multiple times on a single page. ISBNs are checked for basic formatting. That is: The final character is a check digit. It must be present, but is not validated. If full validation is required, callers should validate ISBNs before transcluding this template.
 * it must be 10 or 13 characters long after removing any existing hyphen or space formatting; and
 * for 13 character ISBNs, all the characters must be digits, and it must start with 978 or 979.
 * for 10 character ISBNs, all the characters except the final one must be digits, and the final character must be either a digit or X.

Source code
MediaWiki can transform a page's text before sending it out. To prevent this corrupting JavaScript source code, the template wraps its source code in Base64 encoding. A small JavaScript shim runs in the browser to decode and then run this code.

This encoding means that the source code is not directly visible in the wikitext editor. A listing of the decoded source code is shown below.

Design notes
All code elements live in the global. This is to ensure that they do not clash with any other JavaScript shipped by MediaWiki, either now or in future. The book title code is in.

Overview

 * On loading the page,  retrieves the target ISBN, and if it passes validation, it starts an asynchronous call to the Google Books API to retrieve book data. Data is requested in JSON format. Invalid ISBNs are indicated by (Invalid ISBN).
 * When the Google Books API call completes, it changes the text of the associated element to the book title, or (Title not found) if the API response does not contain a book title.

Multiple transclusion

 * The JavaScript code finds the requested ISBN by searching the DOM for elements with class bh-book-title. The value attribute contains the ISBN, and the text inside this element is where the book title is displayed.
 * Template code emits the required element just ahead of the JavaScript source. On page load, the JavaScript finds all existing and matching  elements, and then starts a Google Books API call for the last one found.
 * Because elements appearing later on in the DOM have not yet been parsed, this means that the last one found is always the one written by template code just ahead of this section of JavaScript. This indirect way of moving data from template code into JavaScript works round MediaWiki's framework restrictions.

Portability

 * The code uses a relatively minimal set of JavaScript features. It tries to avoid using features that might not be present in some older browsers.
 * The book title text is emitted without any formatting. Caller code can style it as required.