Permalink
Browse files

better docstrings in tag utils

  • Loading branch information...
1 parent 2ceede6 commit 822905ef498bea834054d02fb3dd9de7ec46998c @ryanpitts ryanpitts committed Feb 18, 2013
Showing with 55 additions and 0 deletions.
  1. +51 −0 source/tags/models.py
  2. +4 −0 source/tags/utils.py
View
@@ -1,3 +1,54 @@
+'''
+We currently use tags for filtering on these content models:
+
+- Article
+- Code
+
+Originally there was but one `tags` field on each model, and it was good.
+But lo and verily, @slifty asked for split tagfields, to differentiate
+between technologies and concepts. And this seemed beautiful to our eyes.
+
+It also seemed so very simple to implement. But as I have discovered,
+django-taggit is in no way designed to accommodate multiple TaggableManagers
+on a given model. This app gives us a way to work around this limitation.
+But beautiful it is not.
+
+To implement split tagfields, a model should keep its original `tags` field,
+and then add `technology_tags` and `concept_tags` fields as TaggableManagers
+with `through` properties pointing at this app's FooTaggedItem fields.
+
+Additionally, that model's admin class should set the original `tags` field
+to readonly, and implement a `save_model` that automatically populates `tags`
+with a concatenated list of `technology_tags` and `concept_tags`.
+
+Yes, this denormalizes things somewhat. But it enables much simpler code for
+displaying lists of tags, and because of the way django-taggit operates,
+having *something* in that `tags` field turns out to be critical for proper
+filtering of querysets, *even against the two split tagfields*. You would
+think that a filter like so ...
+
+ queryset.filter(
+ Q(tags__slug=tag_slug) |
+ Q(technology_tags__slug=tag_slug) |
+ Q(concept_tags__slug=tag_slug)
+ )
+
+... would work just fine, but because of something deep down inside
+django-taggit, this filter will *not* return an object that has a null
+value in `tags`. Even if you entirely remove the `tags` field from
+the filter, this problem still exists. Even if you remove the `tags` field
+from the model itself, the problem still exists; it just migrates to
+`technology_tags` (or whichever TaggableManager appears first in the model
+code.)
+
+Patches against django-taggit have thus far failed to solve the problem. And
+"problem" might not be the right way to put it; that app was never designed
+to support a use case with multiple kinds of tags. Because the denormalized
+version that keeps `tags` around *does* offer some benefits, however, this is
+where we stand for now.
+
+TODO: Figure out that filter bug wtf
+'''
from django.db import models
from taggit.models import GenericTaggedItemBase, TagBase
View
@@ -23,6 +23,10 @@ def filter_queryset_by_tags(queryset, tag_slugs, tags=[]):
This assumes the model for the queryset includes `tags`, `technology_tags`
and `concept_tags` fields.
+ The `get_validated_tag_list` and `get_tag_filtered_queryset` functions
+ are split into separate pieces so they can be used independently. By the
+ feeds framework, for example.
+
TODO: remove support for original `tags` field
'''

0 comments on commit 822905e

Please sign in to comment.