fcms.resources.taxonomy

A taxonomy is a hierarchy of categories used to organize the items in a collection.

A collection may have none, one or many taxonomies and they are independent of each other.

all-taxonomies

(all-taxonomies coll-slug)

Given the slug of the collection, return all the taxonomies it contains as a sequence of maps, or return :bad-collection if there’s no collection with that slug.

categorize-item

(categorize-item coll-slug item-slug category-path)

Given the slug of the collection, a slug of an item in the collection, and a path to a category in a taxonomy, categorize the item as a member of the category. This function is idempotent and categorizing the item again won’t change the item. If this request is to categorize the item with a child of a parent category that is already categorized on the item, then the parent categorization will be removed. :bad-collection is returned if there’s no collection with that slug. :bad-item is returned if there’s no item in the collection with that slug. :bad-taxonomy is returned if there’s no taxonomy with that slug at the start of the category path. :bad-category is returned if there’s no category in the taxonomy with that category path. :duplicate-category is returned if item is already a member of the provided category or one of its children.

category-exists

(category-exists coll-slug category-path)

Given the slug of the collection, and a path to a category return true if the category exists and false if it does not. :bad-collection is returned if there’s no collection with that slug. :bad-taxonomy is returned if there’s no taxonomy with that slug at the start of the category path.

create-category

(create-category coll-slug category-path)(create-category coll-slug category-path category-name)

Given the slug of the collection, a path to a new category, add an optional name for the category, create the category and any missing categories in the path to the category. For example, a path: /taxonomy-slug/existing-a/new-category-a/new-category-b would result in creating two new categories with the slugs new-category-a and new-category-b. If a name is provided, it is the name for the last new category, in this case the new category with the slug new-category-b. The slug from the category path is used as the name where none is provided. :bad-collection is returned if there’s no collection with that slug. :bad-taxonomy is returned if there’s no taxonomy with that slug at the start of the category path. :invalid-category-slug is returned if any of the slugs in the category path are not valid FCMS slugs. :invalid-category-name is returned if a category name is provided and it’s not a non-empty string.

create-taxonomy

(create-taxonomy coll-slug taxonomy-name)(create-taxonomy coll-slug taxonomy-name props)

Create a new taxonomy in the collection specified by its slug, using the specified taxonomy name and an optional map of properties. If :slug is included in the properties it will be used as the taxonomy’s slug, otherwise the slug will be created from the name. :slug-conflict is returned if a :slug is included in the properties and a resource already exists in the collection with that slug. :invalid-slug is returned if a :slug is included in the properties and it’s not valid. :property-conflict is returned if a property is included in the map of properties that is in the reserved-properties set.

delete-taxonomy

(delete-taxonomy coll-slug slug)

Given the slug of the collection containing the taxonomy and the slug of the taxonomy, delete the taxonomy, or return :bad-collection if there’s no collection with that slug, or :bad-taxonomy if there is no taxonomy with that slug.

get-taxonomy

(get-taxonomy coll-slug slug)

Given the slug of the collection containing the taxonomy and the slug of the taxonomy, return the taxonomy as a map, or return :bad-collection if there’s no collection with that slug, or nil if there is no taxonomy with that slug.

items-for-category

(items-for-category coll-slug category-path)

Given the slug of the collection, and a path to a category in a taxonomy, return a sequence of the items contained in the category. :bad-collection is returned if there’s no collection with that slug. :bad-taxonomy is returned if there’s no taxonomy with that slug at the start of the category path. :bad-category is returned if any portion of the category path does not exist in the taxonomy.

items-for-taxonomy

(items-for-taxonomy coll-slug taxonomy-slug)

Given the slug of the collection, and the slug of a taxonomy, return a sequence of the items categorized in the taxonomy. :bad-collection is returned if there’s no collection with that slug. :bad-taxonomy is returned if there’s no taxonomy with that slug at the start of the category path.

normalize-category-path

(normalize-category-path category-path)

Remove the prefix slash and trailing slash from the category-path if they are present.

uncategorize-item

(uncategorize-item coll-slug item-slug category-path)

Given the slug of the collection, a slug of an item in the collection, and a path to a category in a taxonomy, remove the item as a member of the category. :bad-collection is returned if there’s no collection with that slug. :bad-item is returned if there’s no item in the collection with that slug. :bad-taxonomy is returned if there’s no taxonomy with that slug at the start of the category path. :bad-category is returned if the item is not categorized with the provided category path.

update-taxonomy

(update-taxonomy coll-slug slug props)

Update a taxonomy in the collection specified by its slug using the specified map of properties. If :slug is included in the properties the taxonomy will be moved to the new slug, otherwise the slug will remain the same. The same validity conditions and invalid return values as valid-taxonomy-update? apply.

valid-new-taxonomy

(valid-new-taxonomy coll-slug taxonomy-name)(valid-new-taxonomy coll-slug taxonomy-name props)

Given the slug of the collection, the name of the taxonomy, and a map of a potential new taxonomy, check if the everything is in order to create the new taxonomy. It ensures the collection exists or returns :bad-collection. It ensures the name of the taxonomy is specified or returns :no-name. It ensures the slug is valid and doesn’t already exist if it’s specified, or returns :invalid-slug or :slug-conflict respectively. :property-conflict is returned if a property is included in the map of properties that is in the reserved-properties set.

valid-taxonomy-update

(valid-taxonomy-update coll-slug slug props)

Given the slug of the collection, the slug of the taxonomy, and a map of updated properties for the taxonomy, check if the everything is in order to update the taxonomy. Ensure the collection exists or return :bad-collection. Ensure the item exists or return :bad-taxonomy. If a new slug is provided in the properties, ensure it is valid or return :invalid-slug and ensure it is unused or return :slug-conflict. If no item slug is specified in the properties it will be retain its current slug.