Smart lists

Smart lists are stored combinations of filters that can be applied to your database, generating pseudo-lists on the fly. They are a powerful tool for organizing your books in a way that makes sense to you.

Components

There are three main components to a smart list:

• Name: The name of the smart list, which is used to identify it in the UI and must be unique per user
• Description: An optional description of the smart list
• Filters: The magic sauce that makes smart lists work

Filters

Filters are the core of a smart list. They are used to determine which books are to be included in the generated smart list.

Filters are made up of two parts:

• Filter groups: Groups of filters that are combined together using a joiner
• Joiner: The combination method used to join groups together, i.e. AND or OR

Grouping

Not to be confused with the filter groups, grouping is a way of grouping matched books together by a common attribute. At the time of writing, there are 3 grouping options:

1. BY_SERIES: Groups books together by their series
2. BY_LIBRARY: Groups books together by their library
3. BY_BOOKS: Does not group books together. The name is perhaps confusing, but you can think of it as "no grouping"

Access

The smart list feature, itself, is gated behind the smartlist:read user permission. This means that only users with this permission will be able to interact with smart lists.

Sharing

Smart lists can be shared with other users, and has 3 visibility options:

• Private: Only the owner of the smart list can see it
• Public: Anyone can see the smart list
• Shared: Only users that the smart list has been shared with can see it

Views

While interacting with a smart list on the UI, you can manipulate the view to your liking. This includes:

• Sorting states for the table
• Column visibility, i.e. which columns are visible or hidden
• Column order, i.e. the order in which columns are displayed

By default, any changes you make won't be persisted. However, the UI will detect and allow you to save any adjustments as a view. This view will then be available to you in the future, along with any other views you create. If you have a view selected, the changes will provide you with the additional option of updating the view.

Creating a Smart List

Currently, the only way to create a smart list is to use the Stump API directly. You can use the swagger UI to do this, or use a tool like Postman.

An example POST request might look like this:

{
	"name": "Spider-Man Collection",
	"description": "A smart list that aggregates all of my Spider-Man-related comics into one place",
	"filter": {
		"groups": [
			{
				"or": [
					{
						"name": {
							"contains": "spider"
						}
					},
					{
						"metadata": {
							"characters": {
								"contains": "spider-man"
							}
						}
					}
				]
			},
			{
				"and": [
					{
						"series": {
							"library": {
								"name": {
									"excludes": "Books"
								}
							}
						}
					}
				]
			}
		],
		"joiner": "AND"
	},
	"default_grouping": "BY_SERIES"
}