The model

class Tag(SQLObject):

    class sqlmeta:
        defaultOrder = 'name'

    name = UnicodeCol(alternateID=True, length=100, notNull=True)

    @classmethod
    def byLabel(cls, value):
        """Retrieve tag in case-insensitive manner."""

        try:
            return cls.select(func.LOWER(cls.q.name) == value.lower())[0]
        except IndexError:
            raise SQLObjectNotFound(value)

class Taggable(SQLObject):

    tags = SQLRelatedJoin('Tag', orderBy='name')

The controller

We want to allow the user to add tags to a taggable object by simply entering a comma-separated list of tag labels. (I chose commas as separators rather than spaces, so that we can have tag labels with spaces in them, e.g. "Web development" or "Ruby On Rails".) Suppose we have a form where the user can edit a taggable object, we just add another text entry field with the name "tags" and, in controllers.py, add a few lines to the controller method that handles the form submissions. In this example, I call this method update_taggable and it requires the ID of the taggable object and a string with the list of tag labels as arguments:

class TaggableController(controllers.Controller):

    @expose()
    def update_taggable(self, id, tags='', *args, **kwargs):
        taggable = Taggable.get(id)

        # update any other properties of the taggable object here...

        hub.begin()
        taglist = [tag.strip() for tag in tags.split(',')]
        taggable.update_tag(taglist)
        hub.commit()

What this method does, is also very simple: the string with the comma-separated tag list is split into a real list of tag labels and whitespace around every label is stripped. The resulting list is passed to the update_tags method of the taggable object. We will add this method to the definition of the Taggable class in the next section.

Updating tags

The list of tags given by the user may contain existing tags or new ones and tags that were formerly attached to the taggable object might have been removed from the list. The following method handles all these cases. We have to add this method to the class Taggable in model.py:

def update_tags(self, taglist):
    """Update tags associated with entry to given iterable of tagnames."""

    old_tagset = set(list(self.tags))
    new_tagset = []
    for tagname in set(taglist):
        # skip empty tag labels
        if not tagname:
            continue
        try:
            # retrieves existing tag regardless of case
            tag = Tag.byLabel(tagname)
            # --> Tag reused
        except SQLObjectNotFound:
            tag = Tag(name=tagname)
            # ---> new Tag created
        # add tag to object if not already attached
        if tag not in old_tagset:
            self.addTag(tag)
        new_tagset.append(tag)
    # remove old tags
    for tag in old_tagset.difference(new_tagset):
        self.removeTag(tag)

The approach adopted by this method is the following:

1. Retrieve the list of tags that are presently attached to the object.
2. Convert the list of tag labels to a set to remove duplicates.
3. Iterate over the set of tag labels and for each label:

• Look if the tag is already saved in the database and, if yes, use that.
• If not, create a new tag object.
• Add the tag to the object, if it's not already in the set of old tags created in step 1.
• Add the tag to a list of new tags.

4. Compare the list of new tags (A) with the set of old tags (B) and remove every tag from the object that is in B but not in A.

Where to go from here

That's all the code needed to handle tags. Of course, there are several other interfaces to handle tags you can provide to the user to make life easier for him.

If you want to make it easier for the user to add and remove tags, you can generate a tag cloud from the the list of saved tags. When the user clicks on a tag in the tag cloud, add/remove tags from the "tags" entry field via JavaScript. To see an example of this kind of interface, head over to ma.gnolia [5]. It also sports a nice ajaxian auto-completion feature for the tags text entry field.

Also, you should provide an interface to remove tags from the database or rename them. It might also be useful to allow tagging of several objects at once. Since this can be achieved easily with the existing SQLObject facilities, I will not enter further in to this topic here.

Lastly, you should add a back reference to your taggable objects to the Tag class, so that you can fetch all objects with a certain tag easily. Just add another attribute to the Tag class in model.py:

entries = SQLRelatedJoin('Taggable')

How you should name this attribute depends on the type of your taggable objects, instead of the generic entries, something like articles, bookmarks etc. might be more appropriate. Then, if you want to get all objects with the tag "AJAX", you can use this:

tag = Tag.byLabel('AJAX')
entries = list(tag.entries)

That's all for now. I will post the code for a small sample application that implements this pattern later, so stay tuned!

References