Skip to main content

Managing Collections

In etchblok-test-api, you organize bookmarks into groups using the Collection model, which supports both manual membership and dynamic filtering via smart rules.

Creating a Collection​

You create collections by passing a dictionary to BookmarkService.create_collection. This method handles the instantiation via Collection.from_dict and persists the object using the BookmarkRepository.

from app.services.bookmark_service import BookmarkService
from app.models.collection import CollectionType

service = BookmarkService()

# Create a manual collection
manual_data = {
    "name": "Reading List",
    "type": "manual"
}
collection, error = service.create_collection(manual_data)

# Create a smart collection with a filter rule
smart_data = {
    "name": "Python Articles",
    "type": "smart",
    "filter_rule": "python"
}
smart_collection, error = service.create_collection(smart_data)

Collection Types​

The CollectionType enum in app/models/collection.py defines two modes:

  • MANUAL: Bookmarks are added and removed explicitly by the user.
  • SMART: Bookmarks are intended to be included automatically based on a filter_rule.

Managing Bookmark Membership​

For manual collections, you manage membership using the add_to_collection and remove_from_collection methods in the BookmarkService.

# Add a bookmark to a collection
success = service.add_to_collection(
    collection_id="coll_123", 
    bookmark_id="book_456"
)

# Remove a bookmark from a collection
success = service.remove_from_collection(
    collection_id="coll_123", 
    bookmark_id="book_456"
)

These service methods wrap the underlying Collection model methods:

  • add_bookmark(bookmark_id): Appends the ID to bookmark_ids if it is not already present and the collection is not smart.
  • remove_bookmark(bookmark_id): Removes the ID from the list.

Organizing Collections​

The Collection model provides methods to control how collections and their contents are displayed.

Pinning Collections​

You can toggle the is_pinned attribute to signal that a collection should appear at the top of the sidebar.

collection = service.get_collection("coll_123")
collection.pin()
# Or to remove from the top:
collection.unpin()

# Save changes via repository
service._repo.save_collection(collection)

Reordering Bookmarks​

To change the display order of bookmarks within a collection, use the reorder method. This method requires a complete list of the existing bookmark IDs in the new desired order.

# Current IDs: ["a", "b", "c"]
new_order = ["c", "a", "b"]
collection.reorder(new_order)

Smart Collection Filtering​

Smart collections use a filter_rule string to identify relevant bookmarks. The Collection._apply_filter method performs a case-insensitive search against bookmark titles and descriptions.

# Internal logic used to identify matches
def _apply_filter(self, bookmarks: list) -> List[str]:
    if not self.filter_rule:
        return []
    keyword = self.filter_rule.lower()
    return [b.id for b in bookmarks if keyword in b.title.lower() or keyword in b.description.lower()]

Troubleshooting​

Bookmark Addition Fails​

The add_bookmark method returns False (and add_to_collection will subsequently fail) if:

  1. The collection is a SMART collection. Smart collections do not support manual overrides.
  2. The bookmark ID is already present in the collection.

Reorder Raises ValueError​

The reorder(bookmark_ids) method in app/models/collection.py validates that the new list contains exactly the same set of IDs as the current list. If you attempt to add or remove IDs during a reorder operation, it raises a ValueError:

# This will raise ValueError if "d" is not already in the collection
# or if "a" is missing from the list.
collection.reorder(["a", "b", "d"])