Filters

A filter is a class extending one of the controls below, all nested in EntryFilter. Katari changes its state as the user picks, and passes the whole list to getSearchContent.

Three more are covered below: EntryDateFilter for dates, and Autocomplete and PagedGroup for options the site provides and long lists. EntryFilter and EntryFilterList are in eu.kanade.tachiyomi.source.entry; the metadata, dates and validation on this page are in eu.kanade.tachiyomi.source.entry.filter.

Here are Example Comics' filters. The metadata in each is explained in the next sections:

class SortFilter :
    EntryFilter.Select<String>("Sort by", arrayOf("Popular", "Newest", "A–Z")),
    EntryFilterMetadataProvider {
    override val filterMetadata = EntryFilterMetadata(
        id = "sort",
        role = EntryFilterRole.ORDERING,
        optionIds = listOf("popular", "newest", "title"),
    )
}

class StatusFilter :
    EntryFilter.Select<String>("Status", arrayOf("Any", "Ongoing", "Completed")),
    EntryFilterMetadataProvider {
    override val filterMetadata = EntryFilterMetadata(
        id = "status",
        optionIds = listOf("any", "ongoing", "completed"),
        neutralOptionId = "any",
    )
}

class Genre(name: String, val slug: String) : EntryFilter.TriState(name), EntryFilterMetadataProvider {
    override val filterMetadata = EntryFilterMetadata(id = "genre-$slug")
}

class GenreFilter(genres: List<Genre>) : EntryFilter.Group<Genre>("Genres", genres), EntryFilterMetadataProvider {
    override val filterMetadata = EntryFilterMetadata(id = "genres")
}

fun exampleComicsFilters() = EntryFilterList(
    SortFilter(),
    StatusFilter(),
    GenreFilter(listOf(Genre("Action", "action"), Genre("Romance", "romance"))),
)

getFilterList returns a new list each time. Katari works on its own copies of the filters and sets the user's values on yours only while it calls getSearchContent:

override fun getFilterList() = exampleComicsFilters()

In getSearchContent, read each filter's state and turn it into the site's parameters. The option IDs from the metadata make good parameter values:

private val EntryFilter.Select<*>.selectedOption: String
    get() = (this as EntryFilterMetadataProvider).filterMetadata.optionIds[state]

fun EntryFilterList.applyTo(url: HttpUrl.Builder) {
    forEach { filter ->
        when (filter) {
            is SortFilter -> url.addQueryParameter("sort", filter.selectedOption)
            is StatusFilter -> if (filter.selectedOption != "any") url.addQueryParameter("status", filter.selectedOption)
            is GenreFilter -> filter.state.forEach { genre ->
                when (genre.state) {
                    EntryFilter.TriState.STATE_INCLUDE -> url.addQueryParameter("genre", genre.slug)
                    EntryFilter.TriState.STATE_EXCLUDE -> url.addQueryParameter("exclude", genre.slug)
                }
            }
            else -> Unit
        }
    }
}

An exception thrown by a filter while Katari draws, counts or checks it affects only that filter: Katari carries on without its summary and checks, and says so under it.

Users can save a set of filter values as a filter preset, and feeds in Browse › Feeds are built on them. Without metadata, Katari finds a saved filter again by its label and its position among the filters, and a choice by its index. Renaming a filter, translating its label, moving it, or adding a choice before others then breaks the presets that use it, and the user is asked to repair each one.

EntryFilterMetadataProvider gives filters an identity that doesn't depend on how they look. Give one to every filter from the first release, since adding it later takes the extra steps below. EntryFilterMetadata holds:

Once a filter has an id, presets saved before it had one find it only through legacyNames, so a source that has already shipped filters without metadata lists each filter's old label there, even if the label hasn't changed. A Select or Sort also needs legacyOptionIds, or its saved choice is lost:

class StatusFilter :
    EntryFilter.Select<String>("Publication", arrayOf("Any", "Ongoing", "Completed", "On hiatus")),
    EntryFilterMetadataProvider {
    override val filterMetadata = EntryFilterMetadata(
        id = "status",
        optionIds = listOf("any", "ongoing", "completed", "hiatus"),
        neutralOptionId = "any",
        legacyNames = setOf("Status"),
        legacyOptionIds = listOf("any", "ongoing", "completed"),
    )
}

Katari refuses to search with a filter list whose identities are ambiguous, and shows Ambiguous filter identity with the filter's name. That happens when:

• An id or alias is blank, or used by two filters.
• optionIds doesn't have exactly one non-blank, distinct ID per choice, or the state points past the last choice.
• neutralOptionId, or a target in optionAliases, isn't one of optionIds.

A text value is saved as it is. If its format changes, as with a Text, Autocomplete, EntryDateFilter or PagedGroup state, implement EntryFilterValueMigration on the filter. Values saved before it have version 1, so raise filterStateVersion to 2 and above, and convert older values in migrateFilterValue(value, previousVersion), or return null for ones that can't be converted. Katari also passes values saved at the current version, so return those unchanged. Without it, only values from version 1 restore. A preset whose value can't be restored, or fails validation once restored, asks the user for repair.

The search sheet shows how many filters are active and offers to clear them:

For a filter Katari can't count, implement EntryFilterStateSemantics, as in Rarely needed.

EntryDateFilter opens a date editor instead of a text field. It takes a year, a month or a full date, and needs an id in its metadata:

class ReleaseDate(name: String, id: String) : EntryDateFilter(
    name = name,
    filterMetadata = EntryFilterMetadata(id = id),
    allowedPrecisions = setOf(EntryDatePrecision.YEAR, EntryDatePrecision.MONTH),
    minimum = EntryPartialDate(1950),
)

Read the picked date from dateValue, an EntryPartialDate(year, month, day) whose month and day are null when the user didn't pick them, or null when it is empty. Its toString() gives 2024, 2024-05 or 2024-05-17. Years run from 1 to 9999, and EntryPartialDate.parse returns null for text that isn't such a date.

An EntryDateFilter already rejects dates outside its limits, and an empty one when required = true. For a rule across several filters, such as a range whose end must not come before its start, implement EntryFilterValidator on the group that holds them. Katari passes copies of the group's filters to validateFilter. They carry the values but aren't your own classes, so read them as EntryDateFilter, EntryFilter.Text and so on, and don't change them:

class ReleasedFilter :
    EntryFilter.Group<ReleaseDate>(
        "Released",
        listOf(ReleaseDate("From", "released-from"), ReleaseDate("To", "released-to")),
    ),
    EntryFilterMetadataProvider,
    EntryFilterValidator {
    override val filterMetadata = EntryFilterMetadata(id = "released")

    override fun validateFilter(values: List<EntryFilter<*>>): List<EntryFilterValidationIssue> {
        val (from, to) = values.map { EntryPartialDate.parse((it as EntryDateFilter).state) }
        if (from == null || to == null || from.earliestDayKey() <= to.latestDayKey()) return emptyList()
        return listOf(
            EntryFilterValidationIssue(setOf("released-from", "released-to"), EntryFilterValidationCode.DATE_RANGE),
        )
    }

    fun applyTo(url: HttpUrl.Builder) {
        val (from, to) = state
        from.dateValue?.let { url.addQueryParameter("from", it.toString()) }
        to.dateValue?.let { url.addQueryParameter("to", it.toString()) }
    }
}

Each EntryFilterValidationIssue(filterIds, code, message) names the IDs of the filters it is about. Katari marks those filters, lists the problems at the top of the sheet, and won't apply the filters or save a preset until they are fixed, so getSearchContent only receives valid values. Katari words the problem from its code: REQUIRED, INVALID_DATE, DATE_PRECISION, DATE_BOUNDS or DATE_RANGE. For a rule of your own, use SOURCE and give the text as message; a message given with any other code replaces Katari's wording too.

A Group lists its choices in your code. When the site has too many to list, or they change too often, let Katari ask the site instead:

• Autocomplete is a text field that suggests values from the site as the user types, such as author names. Its state is still the plain text, so a preset never depends on a suggestion being found again.
• PagedGroup is a list of choices that Katari loads page by page, with a search field, such as a site's thousands of tags. It opens on a screen of its own and can show what is selected separately.

An Autocomplete decides what part of the text to look up, fetches suggestions, and returns the text after the user picks one. Katari schedules the lookups and cancels those that are no longer needed:

class AuthorFilter : EntryFilter.Autocomplete(
    "Author",
    options = EntryFilterAutocompleteOptions(minimumQueryLength = 2),
) {
    override fun getSuggestionQuery(input: EntryFilterTextInput): String? = input.text.trim()

    override suspend fun getSuggestions(input: EntryFilterTextInput, query: String): List<EntryFilterSuggestion> =
        findAuthors(query).map { EntryFilterSuggestion(id = it.slug, label = it.name) }

    override fun applySuggestion(input: EntryFilterTextInput, suggestion: EntryFilterSuggestion) =
        EntryFilterTextEdit(suggestion.label, selectionStart = suggestion.label.length)
}

A PagedGroup<S>(name, initialState, options) keeps the user's choices in one immutable state of your own type S. The items Katari loads, and the controls made from them, are only views of that state, and Katari throws them away as the user scrolls:

@Serializable
data class PickedTag(val label: String, val state: Int)

class TagFilter :
    EntryFilter.PagedGroup<Map<String, PickedTag>>("Tags", emptyMap()),
    EntryFilterMetadataProvider {
    override val filterMetadata = EntryFilterMetadata(id = "tags")

    override suspend fun getPage(request: EntryFilterPageRequest): EntryFilterPage {
        if (request.scope == EntryFilterPageScope.SELECTED) {
            return EntryFilterPage(state.map { (slug, tag) -> EntryFilterPageItem(slug, tag.label) })
        }
        val page = request.continuationToken?.toInt() ?: 1
        val result = findTags(request.query, page, request.requestedSize)
        return EntryFilterPage(
            items = result.tags.map { EntryFilterPageItem(id = it.slug, label = it.name) },
            nextContinuationToken = if (result.hasMore) (page + 1).toString() else null,
        )
    }

    override fun projectItem(item: EntryFilterPageItem, previous: EntryFilter<*>?): EntryFilter<*> {
        val current = state[item.id]?.state ?: EntryFilter.TriState.STATE_IGNORE
        return object : EntryFilter.TriState(item.label, current) {}
    }

    override fun reduceItemUpdate(item: EntryFilterPageItem, updatedFilter: EntryFilter<*>): Map<String, PickedTag> {
        val picked = (updatedFilter as EntryFilter.TriState).state
        return if (picked == EntryFilter.TriState.STATE_IGNORE) {
            state - item.id
        } else {
            state + (item.id to PickedTag(item.label, picked))
        }
    }

    override fun selectedItemCount(state: Map<String, PickedTag>): Int = state.size

    override fun encodeState(state: Map<String, PickedTag>): String = Json.encodeToString(state)

    override fun decodeState(value: String): Map<String, PickedTag>? =
        runCatching { Json.decodeFromString<Map<String, PickedTag>>(value) }.getOrNull()
}

• EntryFilterGroupSummary on a Group replaces the text under it while it is collapsed: selectionSummary(values) returns the text for the filters inside, or null to keep Katari's.
• EntryFilterStateSemantics tells Katari how to count and clear a filter whose state it can't read, such as a Text holding a whole query. activeSelectionCount(value) returns the count, or null when it can't tell; canClearSelection says whether clearing is offered; clearSelection(value) clears it. Read and change only the value Katari passes, never the filter's own state.