/help/faq/collections-carousel-examples.en
Type: /type/page
body: value: Collections are essentially pages of **query carousels** that look like a row of front-facing book covers on a shelf, colorful and easy to browse. 

&bull; For more information on using carousels to create collections, <a href="https://openlibrary.org/help/faq/collections">click here</a>. 

&bull; To read the QueryCarousel macro in the code, <a href="https://github.com/internetarchive/openlibrary/blob/master/openlibrary/macros/QueryCarousel.html">click here</a>. 

&bull; To read the ListCarousel macro in the code, <a href="https://github.com/internetarchive/openlibrary/blob/master/openlibrary/macros/ListCarousel.html">click here</a>. 

QueryCarousels should be used to run a search query. 

ListCarousels should be used for a list of explicitly defined works. 

{{QueryCarousel('key:(/works/OL10673093W OR /works/OL73356W OR /works/OL73385W OR /works/OL73375W OR /works/OL73384W OR /works/OL73382W OR /works/OL73387W)')}}

Carousels can be either very general, covering a broad subject like `art` or a very prolific author such as `Stephen King`, or very specific, displaying an explicit list of work identifiers. At minimum, a carousel needs a one argument: the **query.** If you skip the query, you'll get an error. 

`{​{QueryCarousel(QUERY)}}`

These are examples of carousels with just the query:

`{​{QueryCarousel('subject:"dragons"')}}`

`{​{QueryCarousel('key:(/works/OL10673093W OR /works/OL73356W OR /works/OL73385W)')}}`

This is an example of a carousel with all the options specified:

`{​{QueryCarousel('subject:"dragons"', title="Dragons", sort="new", key="", limit=20, search=True, has_fulltext_only=False, url=None)}}`

This is boilerplate for a carousel without a title or search, with a limit of 20 and sorted by scans and editions:

`{​{QueryCarousel('subject:"dragons"', sort="scans,editions", limit=20, has_fulltext_only=False)}}`

## Table of Contents

1. <a href="https://openlibrary.org/help/faq/collections-carousel-examples#query-search">Query by Search String</a>
2. <a href="https://openlibrary.org/help/faq/collections-carousel-examples#query-key">Query by Key</a>
3. <a href="https://openlibrary.org/help/faq/collections-carousel-examples#title">Add a Title</a>
4. <a href="https://openlibrary.org/help/faq/collections-carousel-examples#search">Add a Search Bar</a>
5. <a href="https://openlibrary.org/help/faq/collections-carousel-examples#search-title">Add a Search Bar and Title</a>
6. <a href="https://openlibrary.org/help/faq/collections-carousel-examples#sort">Sort Options</a>
7. <a href="https://openlibrary.org/help/faq/collections-carousel-examples#full-text">Full Text Only</a>
8. <a href="https://openlibrary.org/help/faq/collections-carousel-examples#limits">Limits</a>
9. <a href="https://openlibrary.org/help/faq/collections-carousel-examples#key">Key=?</a>
10. <a href="https://openlibrary.org/help/faq/collections-carousel-examples#url">URL</a>

<h2 id="query-search">Query by Search String</h2>

The query can be any string in a format you'd use in the search bar, such as `subject:dragons` or `author:mccaffrey`. 

Enclose multi-word search strings in quotes, such as `subject:"dragonriders of pern"`.

For more about search strings, <a href="https://openlibrary.org/search/howto" target="_blank">click here</a>.

`{​{QueryCarousel('subject:"dragons"')}}`

{{QueryCarousel('subject:"dragons"')}}

<h2 id="query-key">Query by Key</h2>

The query can be a list of specific works. It's not (yet!) possible to specify the exact order of the book covers. See the <a href="https://openlibrary.org/help/faq/collections-carousel-examples#sort">sort section</a> for some options.

`{​{QueryCarousel('key:(/works/OL10673093W OR /works/OL73356W OR /works/OL73385W OR /works/OL73375W OR /works/OL73384W OR /works/OL73382W OR /works/OL73387W)')}}`

{{QueryCarousel('key:(/works/OL10673093W OR /works/OL73356W OR /works/OL73385W OR /works/OL73375W OR /works/OL73384W OR /works/OL73382W OR /works/OL73387W)')}}

<h2 id="title">Add a Carousel Title</h2>

Add a title above the carousel, which links to the query page.

See the <a href="https://openlibrary.org/help/faq/collections-carousel-examples#url">url section</a> for instructions to override the link destination. 

`{​{QueryCarousel('subject:"dragons"', title="Dragons")}}`

{{QueryCarousel('subject:"dragons"', title="Dragons")}}

<h2 id="search">Add a Carousel Search Bar</h2>

`{​{QueryCarousel('subject:"dragons"', search=True)}}`

{{QueryCarousel('subject:"dragons"', search=True)}}

<h2 id="search-title">Add a Title and a Search Bar</h2>

The search bar always appears above the title. 

`{​{QueryCarousel('subject:"dragons"', title="Dragons", search=True)}}`

{{QueryCarousel('subject:"dragons"', title="Dragons", search=True)}}

<h2 id="sort">Sort Options</h2>

You can sort by publication date (oldest or newest) or by the number of scans or editions. 

**Oldest to Newest**

Use `sort='old'` to list the works by oldest publication date first, which is useful to give you the works of a series in order. 

`{​{QueryCarousel('key:(/works/OL73356W OR /works/OL73385W OR /works/OL73375W OR /works/OL73384W OR /works/OL73382W OR /works/OL73387W)', sort='old')}}`

{{QueryCarousel('key:(/works/OL73356W OR /works/OL73385W OR /works/OL73375W OR /works/OL73384W OR /works/OL73382W OR /works/OL73387W)', sort='old')}}

**Newest to Oldest** 

Use `sort='new'` to list the works by publication date, with the most recently published works appearing first. 

`{​{QueryCarousel('key:(/works/OL73356W OR /works/OL73385W OR /works/OL73375W OR /works/OL73384W OR /works/OL73382W OR /works/OL73387W)', sort='new')}}`

{{QueryCarousel('key:(/works/OL73356W OR /works/OL73385W OR /works/OL73375W OR /works/OL73384W OR /works/OL73382W OR /works/OL73387W)', sort='new')}}

**Scans, Editions**

This option should (and usually does) sort the carousel so that the borrowable works are displayed first.

`{​{QueryCarousel('key:(/works/OL73356W OR /works/OL73385W OR /works/OL73375W OR /works/OL73384W OR /works/OL73382W OR /works/OL73387W)', sort='scans,editions')}}`

{{QueryCarousel('key:(/works/OL73356W OR /works/OL73385W OR /works/OL73375W OR /works/OL73384W OR /works/OL73382W OR /works/OL73387W)', sort='scans,editions')}}

<h2 id="full-text">Full Text Only</h2>

By default, carousels will only include works that are in the lending library. To include all works, set `has_fulltext_only=False`.

`{​{QueryCarousel('subject:"dragons"', has_fulltext_only=True)}}`

{{QueryCarousel('subject:"dragons"', has_fulltext_only=True)}}

`{​{QueryCarousel('subject:"dragons"', has_fulltext_only=False)}}`

{{QueryCarousel('subject:"dragons"', has_fulltext_only=False)}}

<h2 id="limits">Limits</h2>

This is not a limit of how many works the carousel will ever display. Carousels do not have a total limit for how many works they will display. If there are 500 items in a search result for your carousel's query and you keep clicking on the right-hand arrow, the carousel will continue making search queries and rendering the next works until all 500 items have been rendered. 

**The limit is the number of items retrieved from the search query at a time.** The default limit is 20 and should be left at 20, because increasing the limit also increases the loading time.  

If you set the limit to less than the number of works the carousel displays, such as in the example of below, the right-hand arrow doesn't ever appear and you won't be able to click to get more entries. 

`{​{QueryCarousel('subject:"dragons"', limit=20)}}`

{{QueryCarousel('subject:"dragons"', limit=20)}}

`{​{QueryCarousel('subject:"dragons"', limit=1)}}`

{{QueryCarousel('subject:"dragons"', limit=1)}}

<h2 id="key">Key=?</h2>

The key is the unique name of the carousel. 

It is used for both analytics and for receiving the results of "load more" feature. This can be left empty. When left empty, the carousel's key will be generated from the hash of the search query. Since keys must be unique, if you have multiple carousels with the same query, you must assign keys to them.


<h2 id="url">URL</h2>

By default, setting a carousel's `title` parameter creates a clickable title linked to the search results page for the carousel's query. You can set an explicit alternative `url` parameter to change that title link. Be sure you use the entire url, starting with `https://`. 

The first carousel below has the default title link, while the second carousel takes you to the Open Library homepage.

`{​{QueryCarousel('subject:"dragons"', title="Dragons")}}`

{{QueryCarousel('subject:"dragons"', title="Dragons")}}

`{​{QueryCarousel('subject:"dragons"', title="Dragons", url="https://openlibrary.org")}}`

{{QueryCarousel('subject:"dragons"', title="Dragons", url="https://openlibrary.org")}}

<h2>Test ListQuery</h2>

`{​{ListCarousel("/people/mekBot/lists/OL104041L")}}`

{{ListCarousel("/people/mekBot/lists/OL104041L")}}

`{​{ListCarousel("/people/panfilomaria/lists/OL199150L")}}`

{{ListCarousel("/people/panfilomaria/lists/OL199150L")}}

`{​{ListCarousel("/people/jehanni/lists/OL197286L")}}`

{{ListCarousel("/people/jehanni/lists/OL197286L")}}
m: edit
title: Collections: Carousel Examples