It looks like you're offline.
Open Library logo
additional options menu
Last edited by tmanarl
January 11, 2023 | History

How to Create Curated Collections

Collections are another way of showcasing books on a theme or subject. While lists allow you to add a book from the book's page, collections are created by writing a small amount of code for a carousel in a new collection page. You must be a curator to create or edit collections.

This is an example carousel:

Table of Contents

  1. Check Your Permissions
  2. Organize the Collection
  3. Build the Carousels
  4. Finish the Collection Page
  5. Add a Link to the Collection

1. Check Your Permissions

Creating a collection is currently a curator-only feature, so your user account will need to have the correct curator permissions to create and edit collection pages. To find out if your account has the permissions, first log into the Open Library site. Then visit the Collections page and click on the 'Edit' button. If the page opens up with a text box that you can edit, click 'cancel' at the bottom. Your account has permissions and you can go on to step 2.

However, if you see a "permission denied" message, your account doesn't have the curator permissions. To become a curator, check out our pages about volunteering as a librarian and librarianship. When you email us, please tell us that you're interested in creating collections.

If you're already contributing as a librarian and you ought to have (or would like!) curator permissions, please reach out on Slack!

In the meantime, anyone can start preparing a collection by creating lists, cleaning up the work records, adding cover images, and thinking about organizing their collection.

2. Organize the Collection Page

Collection pages are the sort of pages that go viral, so it's good to think about a visitor arriving at a collection's page with an interest in the subject but without knowing anything about Open Library.

Collection pages usually have
1. an eye-catching header graphic
2. some introductory text explaining the collection's subject and how to borrow a book with a free account
3. a table of contents, if the collection is big enough
4. carousels full of books!

However! These are just ideas. The carousels are the only required part of a collection page, so you can design your page any way you want.

All collections are linked from the Collections page, so you can see how other curators have arranged collections in many different ways.

If you have curator permissions, you can create a collection's page. If you don't have permission yet, you can begin with a document, like a google doc. Here's an example of the Star Wars collection's Google doc, which tmanarl started before he had permissions. He created lists of works he wanted in the carousel, then sent the document to a curator who created the page for him, from his lists. You can compare his google doc to the finished Star Wars collection page.

Name & Create the Collection Page

First, you'll need to decide on a collection name for both the title and the url.

For example, "Newbery Medal Winners" is a title and "newbery-medal-winners" will go in the url. You can use underscores and hyphens in the url, but no spaces. For example, any of these would work: newbery-medal-winners, Newbery-Medal-Winners, Newbery_Medal_Winners.

If you don't have permissions, just note all this on your document.

First, create the new collection page by entering https://openlibrary.org/collections/collection-name?m=edit in your browser address bar, where collection-name should be replaced with the collection name used in the URL. Choose wisely. You may change the name on the collection page after it’s been created, but you can't change the URL.

Some example page urls and names are:

Keeping Track of the Collection Page

All pages created under the collections/ directory will show up on the very bottom of the Curated Collections page, so you can find it while you're working on it.

Think About the Carousels

Each carousel loads the results of a search query. For tips on different kinds of Open Library search queries, click here. You can search by subject, place, person, language, and publisher, but you can't combine the queries in a carousel.

If you want to fill a carousel with a specific set of works, there are two methods:

By subject
First, you can manually add a unique subject to those records. This is how the LGBTQ collection is arranged. When you build a carousel using a subject, you only have to edit the collection page when you create the carousel. Later, to add a work to the carousel, you can just add the subject to the work record. Since you're probably editing records anyway, to add covers and clean up descriptions, you can easily add the subject while you're in the record.

When adding a unique subject, the subject should begin with the prefix "collection:" and use underscores instead of spaces. For example, "collection:LGBTQ_history" or "collection:star_wars". This way, the subject's context is clear, the librarians will know the subject should not be moved or changed, and the format matches our other subjects such as "award:pulitzer_prize=fiction".

By Identifier
Second, you can collect the work identifiers (in the form OL...W) and write them directly in the search query. This is how the Star Wars collection is arranged. The easiest way to collect the work identifiers is to create a list of works, one per carousel, and then use a script to create a carousel from the list automatically.

Important: Carousels don't let you specify editions (OL...M) of works, so always click "use this work" when you add works to a list!

To create a list, search for a work and find the green "Want to Read" button. Click the dropdown arrow, click "Use this Work," and either click "Create a new list" or add the work to an existing list by clicking on the list name.

Editing & Merging Works

Creating a collection gives you a chance to clean up the related records.

It's very common for records to have no description, no language, and/or no book cover. Carousels are eye-catching because of the book covers, so it's important to look up the ISBNs of editions without covers and try to find descriptions and covers.

It's also common to find editions of a book spread across multiple identical works. To request those works to be merged, either reach out on Slack or submit the merge request through the website.

For more about general librarian tasks, click here.

3. Build the Carousels

For everything you need to know about carousels, with examples, click here. Have questions? Please ask!

If you're making a collection using search queries without needing any explicit work identifiers, you can skip to step 4.

Turning Lists into Carousels

If you don't feel comfortable with scripting, you can send your document and/or your list to a curator or librarian and we'll create the carousels for you.

Once you have a list of works, you can get the list of identifiers from the JSON export.

Every list has a JSON export that includes the identifiers of every entry in the list. For example, the Lambda Literary Awards list has a JSON export with the identifiers in the entries array. You can also scroll down to the bottom of a list's page and click on the JSON export manually.

However, the easiest way is to to get the list of the IDs quickly is to go to the list page in your browser and open the developer tools console.

If your list contains works only, run this code:

var seeds = await fetch('https://openlibrary.org/people/[USERNAME]/lists/[LIST-ID]/seeds.json')
.then(r => r.json());
seeds.entries.map(e => e.url).join(' OR ');

If it contains both works and editions, run this code:

var urls = [];
var promises = [];
var seeds = await fetch('https://openlibrary.org/people/[USERNAME]/lists/[LIST-ID]/seeds.json').then(r => r.json());
seeds.entries.forEach((item) => {
    if(item.type === 'work') urls.push(item.url);
    else if(item.type === 'edition') {
        promises.push(fetch(item.url+'.json')
            .then(r => r.json())
            .then((record) => {
                urls.push(record.works[0].key);
            })
        );
    }
    else console.warn('garbage', item);
})
Promise.all(promises).then(() => urls.join(' OR '));

Copy the list of IDs and paste it into your carousel.

4. Finish the Collection Page

Collections can take a lot of work and feel very personal to a curator, so it's best not to edit other collections pages without talking with the curator first. However, feel free to click 'Edit' on other collections pages so you can see how the introduction, table of contents, and other carousels were created. Feel free to copy language and code!

For two different approaches to introductions, check out the LGBTQ and Star Wars collections. And, of course, you don't have to write any introduction at all if you don't want to.

There's a glitch at the moment where not all borrowable editions are showing up in the carousels, so it might be helpful to add the following:

You can read or borrow a book if the bar underneath the cover says "Borrow" or "Read." **If a book says it is "not in library" or "checked out," a copy might still be available!** Click on the book's cover to see if you can borrow one of the other editions.

The time has come! Your collection page exists, your introduction is fantastic, and the carousels look great. It's time to add a link on the Curated Collections page.

First, decide where you want to put your link. Then, click 'Edit', add your link exactly like the other links, and click 'Save'.

Next, spread the word! Give the link to your friends! Tell us about it! We want to share it far and wide!

History

January 11, 2023 Edited by tmanarl updated code
January 6, 2023 Edited by AgentSapphire remove confusing brackets
December 31, 2022 Edited by SmCvgPed Add code for lists containing both works and editions
January 26, 2022 Edited by AgentSapphire add headings
June 24, 2021 Edited by Jenner Move around section 3