Markup

This is a way to populate your content with extra content in relation to the tags. The most common way would be to replace where the tags are located with links to another section of your site with more information.

Setup

In the settings you will need to have

SUPERTAGGING_SETTINGS = {

    # ... Other settings

    'MARKUP': {
        'ENABLED': True,
    }
}

How It Works

When SuperTagging loads up and markup is enabled, it will add an additional attribute for every field specified in WATCHED_FIELDS.

SUPERTAGGING_SETTINGS = {
    'ENABLED': True,
    'WATCHED_FIELDS': {
        'stories.story':
            {'fields':[
                {'name': 'body',
                 'markup_handler': 'MyCustomHandler'}]},
        'media.image':
            {'fields':[
                {'name': 'caption'}]},
        'blog.entry':
            {'fields':[
                {'name': 'content'},
                {'name': 'tease',
                 'markup': False}]}
    },

    # ... Other settings

    'MARKUP': {
        'ENABLED': True,
        'FIELD_SUFFIX': "tagged",
    },
}

Lets take the code sample above as an example. We notice that markup is enabled and the prefix for the markup fields is tagged. The first module is a story model, and the field named body is marked to be tagged. It also specifies a custom markup handler, which we’ll get to a bit later. The next model is a image model and the caption field is marked for tagging. The last model is an entry model and it has 2 fields marked for tagging, content and tease, but tease is not to be marked up.

After SuperTagging is done loading you will end up with three additional attributes for the three different models.

  • Story model: body__tagged
  • Image model: caption__tagged
  • Entry model: content__tagged

Notice that the a tease__tagged does not exist for the Entry model because the markup flag for that field is False.

Markup handler

Each field will be assigned a MarkupHandler object, which can be found in supertagging/markup.py file. This module does all the markup processing for you on the fly. If an error occurs, since the original content is never touched, the original content is returned.

You can create your own custom handler as well.

from supertagging.markup import MarkupHandler

class MyCustomHandler(MarkupHandler):
    def handle(self, instance):
        # DO YOUR CUSTOM MARKUP HERE
        return "MARKED UP CONTENT"

The handle method needs to return a string of the marked up content.

If you want a create a custom handler but use the default markup method, your code might look something like this:

from supertagging.markup import MarkupHandler, markup_content

class MyCustomHandler(MarkupHandler):
    def handle(self, instance):
        # DO SOMETHING HERE
        return markup_content(instance, self.field)

Markup Template

markup.html

This template is used to render the tags in a marked up state. Below is the default html rendered.

<a href="#">{{ actual_value }}</a>

Context

  • actual_value - the value of the tag, this might be the same as the tag name or a reference to the tag, IE: ‘his’, ‘her’ etc.
  • tag - a SuperTag instance

Caching

There is a build-in cache for the markup, since every time we call this new attribute, a couple database calls need to happen to retrieve all the tags and its meta data for an instance.

You can change the default timeout for this cache by changing the following setting

SUPERTAGGING_MARKUP_CONTENT_CACHE_TIMEOUT = 3600

Gotchas

In some cases, after enabling markup and successfully tagging an instance the markup does not show up. Two things might cause this, 1 is the cache has not expired and 2 the markup did not validate.

Markup validation happens when the markup field is called and the data retrieved does not match what the instance has stored. This usually means that the instance was edited and the field that gets tagged was changed and it has not been re-processed by OpenCalais.