Usage examples

Let’s suppose we have a simple two-level categories hierarchy:

|-- Language (alias: langs)
|   |-- Russian
|   |-- English
|
|-- OS (alias: os)
|   |-- Linux
|   |-- Android
|   |-- OS X
|
|-- Direction (alias: dir)
    |-- North
    |-- South
    |-- East
    |-- West

And we have two models inherited from ModelWithCategory: Article and Comment.

Now to what we can do with it.

Get categories for a certain object

def view_article_details(request, article_id):

    article = get_object_or_404(Article, pk=article_id)

    # Setting init keyword arguments for for every CategoryList.
    #
    # E.g.: if this article is in the `Linux` and `English` categories,
    # two CategoryLists objects will be created:
    # one for `OS` and the other for `Language` parent categories.
    #
    # With `show_title`=True `{% sitecats_categories from article %}` template tag
    # will render parent categories titles alongside with `Linux` and `English` categories.
    article.set_category_lists_init_kwargs({'show_title': True})

    ...

    return ...

Get category editor for a certain object

from sitecats.toolbox import get_category_aliases_under

def view_article_edit(request, article_id):

    article = get_object_or_404(Article, pk=article_id)

    ...

    article.enable_category_lists_editor(request,
        # By default editor will render only parent categories
        # for children associated with this article.
        # If we want other parent categories to be available, we should
        # give the editor their aliases with `additional_parents_aliases`.
        #
        # Here we use `get_category_aliases_under()` helper without arguments
        # to get aliases of root categories (Language, OS, Direction).
        additional_parents_aliases=get_category_aliases_under(),

        # Setting up editor parameters.
        # Here `allow_add` allows adding this article into existing categories;
        # `allow_remove` allows removing this article from associated categories;
        # `allow_new` allows superusers to create new subcategories and add this articles into them.
        editor_init_kwargs={'allow_add': True, 'allow_remove': True, 'allow_new': request.user.is_superuser}

        # Setting up category editor requests handler.
        # Passing extra tags for error messages generated by with `error_messages_extra_tags`
        # for error messages styling purposes.
        handler_init_kwargs={'error_messages_extra_tags': 'alert alert-danger'},

        # Setting init keyword arguments for for every CategoryList.
        lists_init_kwargs={'show_title': True},
    )

    # Now {% sitecats_categories from article %}` template tag will render
    # a category editor with set properties.

    ...

    return ...

Get categories having associated objects

from sitecats.toolbox import get_category_lists, get_category_aliases_under

def view_categories(request):
    lists = get_category_lists(
        # We need to render categories under root parents (Language, OS, Direction).
        additional_parents_aliases=get_category_aliases_under(),
        init_kwargs={
            # We'll show parent categories titles.
            'show_title': True,
            # We'll create links for category details pages.
            # Let's suppose we have `category-details` URL pattern defined.
            'show_links': lambda cat: reverse('category-details', args=[cat.id])
        })

    # Now {% sitecats_categories from article %}` template tag will render
    # all categories having associated objects.

    return ...

Get model instances associated with a category

def view_articles_for_category(request, category_id):

    ...

    objects = Article.get_from_category_qs(category)

    ...

Get all ties by categories

from sitecats.toolbox import get_tie_model

linked_objects = get_tie_model().get_linked_objects(by_category=True)