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.