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
-----------------------------------

.. code-block:: python

    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
----------------------------------------

.. code-block:: python

    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
----------------------------------------

.. code-block:: python

    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
----------------------------------------------

.. code-block:: python

    def view_articles_for_category(request, category_id):

        ...

        objects = Article.get_from_category_qs(category)

        ...


Get all ties by categories
--------------------------

.. code-block:: python

    from sitecats.toolbox import get_tie_model

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

