docs/source/examples.rst
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)