trove-js

A JavaScript library to access the National Library of Australia's (NLA) Trove API.

The Trove website can be found at https://trove.nla.gov.au.

Trove's v2 API is documented here.

This library works with: https://api.trove.nla.gov.au/v2

A simple live search example is here.

If you just want to use the library in your webpage

1. Get a Trove API key: see here
2. Download dist/trove-api.js or dist/trove-api.min.js
3. Include it in your web page
4. Use it

Developing the library

Source files are in src, concatenated and minified distribution files are in dist.

You'll need npm, babel and webpack installed to generate the distribution files.

Clone this repository, and go to the directory created. Type:

npm install

This will install the dependencies for building and testing.

There are a number of npm scripts defined, but be aware that the unit tests will need a Trove API key in the __key_file__ file.

Task	Description
build	Check code style, package the library.
docs	Generate html docs.
docs:md	Generate markdown docs.
lint	Check code style.
test	Runs unit tests (you'll need an API key to run the tests).

To build the dist/trove-api.js after modifying a source file just type:

npm run build

which should check your files for code style and produce the concatenated file.

Getting an API key

You'll need to get an API key first, by signing up and requesting one. Instructions for doing so are found at Trove Help.

Both the unit tests and the demo page will load a key from the __key_file__ file. So if you want to run the tests or try out the demo page, put your key in this file (DON'T commit and push this change to GitHub).

Please comply with the conditions of use, an put "powered by trove" somewhere on your site.

Library initialisation

In your JavaScript, initialise the library first giving it your key:

Trove.init(your_key);

Asynchrony

Remember that each time you make a call for data, the data will not be available until the Trove servers respond. For example, if you were to write:

var article = new Trove.NewspaperArticle({
    init: 18342701
});
console.log(article.heading);

you would, more than likely, see 'undefined' at the console. For this reason, the API provides a parameter for a function to be called when the request completes:

var article = new Trove.NewspaperArticle({
    init: 18342701,
    done: function (a) {console.log(a.heading)};
});

You could also write:

function done_callback(a) {
    console.log(a.heading);
}

var article = new Trove.NewspaperArticle({
    init: 18342701,
    done: done_callback
});

to get the same result. The parameter to the called function is the object that has been updated by the request.

Examples and Documentation

Please see the wiki for examples

There are API docs here and you can build HTML API pages using npm run docs.

There is a simple search example at http://chrrrisw.github.io/trove-js/