Liviu, Agile Bear

In our previous post we discovered how to obtain in Kay templates the same behavior as Django's inclusion tag. Another question pops in. What about template tags?

What is a template tag?

"A template tag is code that displays information dynamically in the template."

In other words, it's a method that handles the data based on the context and outputs it in the desired manner. The Django docs example is pretty clear:

<p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p>

#output
The time is 2010-09-03 11:13 PM

Kay framework doesn't allow you do import .py files to use their functions inside a template, because it's not transforming it in a list of nodes, like Django does.

CONTEXT_PROCESSORS

"Much like Django’s context processors Kay allows you to define a
number of functions that are run when templates are rendered that
make commonly used data available to your template."

This is exactly what we have been searching for. Let's see how to define such a context processor and how to use it in a template for the Django example:

# my_app.utils - defining the method
import datetime
def current_time(format_string = "%Y-%m-%d %I:%M %p")
    return datetim.datetime.now().strftime(format_string)

# my_app.context_processors - create the processor
from utils import current_time
def current_time_processor(request):
    return {'current_time': current_time}

# settings - include the processor
CONTEXT_PROCESSORS = ( 
    ...
    'my_app.context_processors.current_time_processor'
)

# template usage
<p>The time is {{ current_time("%Y-%m-%d %I:%M %p") }}.</p>

# output
The time is 2010-09-03 11:13 PM

Applying processors for single view, not for the whole project

If the processor will only be used in a few templates, you can skip the part where we include it in the settings.CONTEXT_PROCESSORS tuple and send it when rendering the view's response:

# my_app.views
from kay.utils import render_to_response
from context_processors import current_time_processor

def current_time(request):
    return render_to_response('my_app/current_time.html', {}, processors=(current_time_processor,))

The only functionality that is missing is setting a variable in the context and there doesn't seem to be a solution for it.

Note: The returned value of your function will need the |safe filter applied to it to avoid HTML escaping.

Categories: GAE Kay Framework

Tagged as: context_processor django kay framework template tag

Django inclusion tag helps you when you need to repeat the same HTML block for several times or keeping your design consistent site-wide.

How can you do the same in Kay framework? Is there such an option?

Well, first of all, you need to search in the right place, like the docs say:
Kay uses Jinja2 for rendering HTML templates.
So let's check the Jinja2 Template Designer Documentation. This is where the solution can be found: Macros

Macros

Macros are comparable with functions in regular programming languages. They are useful to put often used idioms into reusable functions to not repeat yourself.
This is exactly what we were searching for.

Lets take the polls results example from Django docs and transform it in a Kay/Jinja2 macro:

Django

# polls.templatetags.poll_tags
from django import template
register = template.Library()

@register.inclusion_tag('results.html')
def show_results(poll):
    choices = poll.choice_set.all()
    return {'choices': choices}

# templates/polls/results.html
<ul>
{% for choice in choices %}
    <li> {{ choice }} </li>
{% endfor %}
</ul>

# templates/polls/view_poll.html
{% load poll_tags %}
{% show_results poll %}

Kay framework

# templates/polls/macros.html
{% macro show_results(poll) %}
<ul>
{% for choice in poll.choices_set.fetch(1000) %}
    <li> {{ choice }} </li>
{% endfor %}
</ul>
{% endmacro %}

# templates/polls/view_poll.html
{% from "polls/macros.html" import show_results %}
{{ show_results(poll) }}

First obvious difference, in Kay, the code doesn't stay in a separate .py file, but in an .html one which needs to be imported directly in the template where it is being used.

Unfortunately, if you need to handle the arguments in some special way, you are limited by normal template syntax only and this might not be the right solution.

Special macro + call

Jinja also comes with something extra by using macro + call together.  This is like calling a macro inside another macro and it is
useful as replacement for loops. 

{% macro dump_users(users) %}
    <ul>
    {% for user in users %}
        <li><p>{{ user.username|e }}</p>{{ caller(user) }}</li>
    {% endfor %}
    </ul>
{% endmacro %}

{% call(user) dump_users(list_of_user) %}
    <dl>
        <dl>Realname</dl>
        <dd>{{ user.realname|e }}</dd>
        <dl>Description</dl>
        <dd>{{ user.description }}</dd>
    </dl>
{% endcall %}

Categories: GAE Kay Framework

Tagged as: django inclusion tag kay framework macro

What to do in those strange situations where you need to use an instance's method, which needs at least one argument, in the template? You can't always generate the values from the views.py and send them in variables, imagine a for loop where you need to get it.

The easy way to do it is using Django filters.

Three solutions. Pick the one that fits your needs.

There are three solution presented in this article:
1. calling one method only which requires one argument;
2. calling one method only which requires more string/int arguments;
3. calling any method which requires one or more arguments.

The no argument case is a simple {{ instance.method }} call, so there is no point discussing it.

To illustrate our examples, we'll use the following model and call the template_call() method:

from django.db import models

class SomeObject(models.Model):
    some_field = models.TextField()

    def template_call(self, *args):
        """ this is the method that will be called """
        return ", ".join(args)

Calling one method only which requires one argument

The simplest case. We only need to call one method which requires only one argument. A normal filter is enough since we can hardcode the method's name in it and send the attribute as a parameter:

#template_filters.py
from django import template
register = template.Library()

@register.filter
def test_simple_template_call(instance, args):
    """ 
    allows only one argument for one exact method
    """
    return instance.test_template_call(args)

# template usage
{{ instance|test_simple_template_call:"value1" }}

# output
value1

Calling one method only which requires more string/int arguments

This approach is similar to the one before, the difference is that the arguments will be passed as key=value pairs separated by '&'. To resolve them, we will use the same class Django uses to parse query strings out of URL's, since it is the same structure.

#template_filters.py

from django.http import QueryDict
@register.filter
def test_advanced_template_call(instance, args):
    """
    allows more arguments like a query dict:
        var_name=value&var_name2=value 
    """
    qd = QueryDict(args)
    return instance.test_template_call(*qd.values())

# template usage
{{ instance|test_advanced_template_call:"var_1=value1&var_2=value2" }}

# output (note the values order)
value2, value1

Calling any method which requires one or more arguments

This is the complex one. You can send any number of arguments and specify which method to call. For this to happen we need not one, but two filters: one to set the arguments in the instance's attributes and one to name the method. The order the filters are called is essential: first the arguments and then the method.

#template_filters.py

@register.filter
def template_args(instance, arg):
    """
    stores the arguments in a separate instance attribute
    """
    if not hasattr(instance, "_TemplateArgs"):
        setattr(instance, "_TemplateArgs", [])
    instance._TemplateArgs.append(arg)
    return instance

@register.filter
def template_method(instance, method):
    """
    retrieves the arguments if any and calls the method
    """
    method = getattr(instance, method)
    if hasattr(instance, "_TemplateArgs"):
        to_return = method(*instance._TemplateArgs)
        delattr(instance, '_TemplateArgs')
        return to_return
    return method()

# template usage
{{ instance|template_args:"value1"|template_args:"value2"|template_args:"value3"|template_method:"test_template_call" }}

# output
value1, value2, value3

With all this filters, you can choose the one that best fits your needs without over doing it.

Category: Django

Tagged as: django template tag

The form validation process is very useful and does not require too much code to be written. But what if you need to save certain fields when the form is not valid?

Let's consider the following models.py, forms.py and situation:

# models.py
from django.db import models

class Avatar(modesl.Model):
    original_image = models.ImageField()

class Character(models.Model):
    name = models.TextField()
    avatar = models.ForeignKey(Avatar, blank=True, null=True)

# forms.py
from django import forms
from models import Character

class CharacterForm(forms.ModelForm):
    name = forms.CharField(required=True, min_length = 3)
    avatar = forms.ImageField(required=True)

    class Meta:
        model = Character
        fields = ['name', 'avatar']

    def clean_avatar(self):
        """
        we need to return a Avatar object to match the model field type
        """
        img = self.cleaned_data.get('avatar')
        if not img:
            raise forms.ValidationError('You must select a character image')
        avatar = Avatar(original_image = img)
        avatar.save()
        return avatar

What will happen to the avatar field if the user inputs a name that is already in use? Its value will get deleted and you risk the user not noticing it, generating another form error page.

What can we do about it?

We don't have access to the session inside the clean method to set avatar.id in it, nor to form.cleaned_data in views.py.

We must use what we can: altering the data used to populate form fields values inside the avatar clean method. So let's add a separate hidden field that will store our avatar.id and we can now make the avatar as not required since it can be empty.

# forms.py
class CharacterForm(forms.ModelForm):
    name = forms.CharField(required=True, min_length = 3)
    avatar_id = forms.CharField(required=False, widget=forms.HiddenInput)
    avatar = forms.ImageField(required=False)

Very important: the order of the Meta fields. We want the avatar_id to be in front of avatar:

# forms.py
    class Meta:
        model = Character
        fields = ['name', 'avatar_id', 'avatar']

This way the avatar_id field is evaluated before we modify its value and we don't risk getting our custom value getting overwritten with POST data.

The avatar_id value is set in the clean_avatar method, because that will still be the only place where we create the avatar.

# forms.py
    def clean_avatar(self):
        img = self.cleaned_data.get('avatar')
        avatar_id = self.cleaned_data.get('avatar_id')
        # avatar or avatar_id must exist
        if not (img or avatar_id):
            raise forms.ValidationError('You must select a character image')
        if not img and avatar_id:
            try:
                avatar = Avatar.objects.get(id=avatar_id)
                return avatar
            except:
                raise forms.ValidationError('You must select a character image')

        avatar = Avatar(original_image = img)
        avatar.save()

        if not self.is_valid() and avatar:
            self.data['avatar_id'] = avatar.id

        return avata

Of course there are other ways, like adding a JavaScript to check all fields value before submitting the form, but this handles cases where the user disabled or the browser does not support JS.

Category: Django

The default django urlize filter is not HTML safe as the docs say.

Note that if urlize is applied to text that already contains HTML markup,
things won't work as expected. Apply this filter only to plain text.

The easy way to solve this problem is to use an HTML parser and make sure the filter is applied only to plain text.

BeautifulSoup functions

To get the HTML tags from a text, .findAll() is the way to go, but if we need the plain text, .contents is what we need. Given a simple example to see what is the difference:

from BeautifulSoup import BeautifulSoup
html = '<p>foo <a href="http://od-eon.com">http://od-eon.com</a> bar</p> foobar'
soup = BeautifulSoup(html)
soup.findAll()
>>> [<p>foo <a href="http://od-eon.com">http://od-eon.com</a> bar</p>, <a href="http://od-eon.com">http://od-eon.com</a>]
soup.contents
>>> [<p>foo <a href="http://od-eon.com">http://od-eon.com</a> bar</p>, u' foobar']

The flow is clear to obtain a safe urlize from this simple example. We need to apply the urlize function on the .contents of each tag that the text contains:
Step 1. iterate over .contents and if its not a tag, do the replacement
Step 2. iterate over the tags, create a new BeautifulSoup instance from each tag
Step 3. if the new BeautifulSoup.findAll() returns more tags, for each of them repeat the process; if it doesn't, apply the urlize function and replace the tag in the main soup object

There is only one minor check that we should add in this case, what kind of tag are we converting now, because the http://od-eon.com inside the anchor tag it shouldn't convert to a new link, it already is one. So at Step 2. we need to check if tag.name is one of our accepted tags.

Here's how the code would look like:

from django.template.defaultfilters import stringfilter
from django.template import Library
from django.utils.html import urlize
register = Library()
def html_urlize(value, autoescape=None):
    """Converts URLs in plain text into clickable links."""
    from BeautifulSoup import BeautifulSoup
    ignored_tags = ['a', 'code', 'pre']
    soup = BeautifulSoup(value)
    tags = soup.findAll(True)
    text_all = soup.contents
    for text in text_all:
        if text not in tags:
            parsed_text = urlize(text, nofollow=True, autoescape=autoescape)
            text.replaceWith(parsed_text)
    for tag in tags:
        if not tag.name in ignored_tags:
            soup_text = BeautifulSoup(str(tag))
            if len(soup_text.findAll()) > 1:
                for child_tag in tag.contents:
                    child_tag.replaceWith(html_urlize(str(child_tag)))
            elif len(soup_text.findAll()) > 0:
                text_list = soup_text.findAll(text=True)
                for text in text_list:
                    parsed_text = urlize(text, nofollow=True, autoescape=autoescape)
                    text.replaceWith(parsed_text)
                try:
                    tag.replaceWith(str(soup_text))
                except:
                    pass
    return mark_safe(str(soup))
html_urlize.is_safe = True
html_urlize.needs_autoescape = True
html_urlize = stringfilter(html_urlize)
register.filter(html_urlize)

Category: Django

Django Docs says that in Admin you can only display the __unicode__ representation of a ForeignKey field in list_display and it also allows you to define a custom function if you want to customize the display.

Let's take a simple Blog, Entry as example:

# models.py
class Blog(models.Model):
    name = models.CharField(_('Blog Name'), max_length=200)
    desc = models.TextField()

class Entry(models.Model):
    blog = models.ForeignKey(Blog)
    title = models.CharField(max_length=200)
    post = models.TextField()

The target is to have the blog name in the Entry admin list view and also having it sortable.

Of course if will not work if you add it in list_display like 'blog__name'.

# amin.py
class EntryAdmin(admin.ModelAdmin):
    list_display = ('title',)

Half is done, you can now see it in admin.

Adding the Blog name in Entry admin

Easy way to do this is to define a function in the Entry model, allowing us to call it in the admin, just like any other field.

# models.py
class Blog(models.Model):
    name = models.CharField(_('Blog Name'), max_length=200)
    desc = models.TextField()

class Entry(models.Model):
    blog = models.ForeignKey(Blog)
    title = models.CharField(max_length=200)
    post = models.TextField()

    def blog_name(self):
        return self.blog.name

Now we can add it in the admin:

# amin.py
class EntryAdmin(admin.ModelAdmin):
    list_display = ('title', 'blog_name')

Making it sortable by

Being a function in the model, it misses an attribute used by the admin admin_oderd_field to order.

# models.py
class Blog(models.Model):
    name = models.CharField(_('Blog Name'), max_length=200)
    desc = models.TextField()

class Entry(models.Model):
    blog = models.ForeignKey(Blog)
    title = models.CharField(max_length=200)
    post = models.TextField()

    def blog_name(self):
        return self.blog.name
    blog_name.admin_order_field = 'blog__name'

Now you can actually order the results in entry admin list display by blog name.

Category: Django

Facebook launched social plugins you can add to your site with just a few lines of HTML code. You can customize how much details should it display and the layout style from their interface.

This is how the code generated looks like:

<iframe src="http://www.facebook.com/plugins/like.php?href=http%3A%2F%2Fdevelopers.facebook.com%2F&amp;layout=standard&amp;show_faces=true&amp;width=450&amp;action=like&amp;colorscheme=light" scrolling="no" frameborder="0" allowTransparency="true" style="border:none; overflow:hidden; width:450px; height:px"></iframe>

It is enough to get you started adding the plugin to your page.

Iframe Properties

All the details you select in that form are found in the src attribute of the iframe tag and you can change them directly from here, even the URL to like by changing:

href=http%3A%2F%2Fdevelopers.facebook.com%2F

to your URL:

href={{ hostname|iriencode }}

Separate Like button for each page

Creating a separate like button for each page will result in changing the same src attribute to something like:

href={{ hostname|iriencode }}{{ request.path_info|iriencode }}

Complete iframe code:

<iframe src="http://www.facebook.com/plugins/like.php?href={{ hostname|iriencode }}{{ request.path_info|iriencode }}&amp;layout=standard&amp;show_faces=true&amp;width=450&amp;action=like&amp;colorscheme=light" scrolling="no" frameborder="0" allowTransparency="true" style="border:none; overflow:hidden; width:450px; height:px"></iframe>

How would this reflect on the Facebook profile?

The plugin will use the page's title tag to print it in the feed list like:

Liviu likes Article Title on Title Tag.

Customizing the FB feed

What if you want to use a different title for the page? It's easy, Facebook also provides custom meta tags for this:

* og:title - The title of your page; if not specified, the title element will be used.
* og:site_name - The name of your web site, e.g., "CNN" or "IMDb".
* og:image - The URL of the best picture for this page. The image must be at least 50px by 50px and have a maximum aspect ratio of 3:1.<meta property="og:title" content="Article Title"/>
<meta property="og:site_name" content="Your Site"/>
<meta property="og:image" content="http://path/to/image"/>

Adding the og:site_name meta tag also changes the feed to:

Liviu likes Article Title on Your Site.

The "Your Site" link is the domain where that page is hosted. Also, adding the og:site_name tag will affect direct link shares on FB site.

Using Facebook's Javascript SDK

If you already added Facebook's javascript SDK, you can use the XFBML tag

<fb:like href="{{ hostname|iriencode }}{{ request.path_info|iriencode }}" layout="standard" show_faces="true" width="300" action="like"></fb:like>

Category: Django

The Django documentation gives explicit details on how you can set a variable in the context using a custom template tag.

class CurrentTimeNode3(template.Node):
    def __init__(self, format_string, var_name):
        self.format_string = format_string
        self.var_name = var_name
    def render(self, context):
        context[self.var_name] = datetime.datetime.now().strftime(self.format_string)
        return ''

Where can I use that variable?

Of course you can use in the template, but the scope depends on the templates structure. Let's take as example a template like this:

{% extends 'site_base.html' %}

{% load my_custom_tags %}

{% block head %}
    {% get_current_time "%Y-%M-%d %I:%M %p" as my_current_time %}
    The current time is {{ my_current_time }}.
{% endblock %}

This will have the expected output, in the head block of the site_base.html template will display the time.

The exception raises when you have multiple blocks where you want to use that variable:

{% extends 'site_base.html' %}

{% load my_custom_tags %}

{% block head %}
    {% get_current_time "%Y-%M-%d %I:%M %p" as my_current_time %}
    The current time is {{ my_current_time }}.
{% endblock %}

{% block content %}
    The current time is {{ my_current_time }}.
{% endblock %}

This usage will not display the time in the content block or if you set a list that you will iterate over, it will raise Caught an exception while rendering: Failed lookup for key [list] in u'[{\'block\': ...

Why is it a problem to call the template tag in both blocks?

Imagine you are doing some queries in that custom template tag, calling it in multiple blocks, increases your queries/page stat.

Why can't I use the variable in any block, since it is set in the context?

{% block %} pushes a new dictionary on the Context stack and pops it off when it reaches the matching {% endblock %}. This means any context value created while in the block has essentially gone out of scope on block exit.

Any solution?

A minor adjustment to set the variable in the main context

def render(self, context):
        context.dicts[0][self.var_name] = datetime.datetime.now().strftime(self.format_string)
        return ''

Category: Django

The FileField or ImageField is used in many situations (for storing avatars, albums etc). Using it's details in the admin can result in high loading times if you add them in the model's __unicode__().

Simple Example

Let's say you use for storing the avatar of your users (UserProfile has a FK to Avatar):

class Avatar(IKImage):
	the_image = models.ImageField(upload_to='/your/path')

In the admin you need to be able to differentiate between Avatars so you need a __unicode__() method.
Ideally you need to show something related to the file and what else if not the url:

def __unicode__(self, *args, **kwargs):
		return u'%s' % self.original_image.url

For a few records, you will not notice any problem, but as your project grows, the loading time of admin Profile edit page will increase.

Why does loading time increase?

When getting the url of the file, django will acces the storage, which response time will always be slow. So make sure you use something that exists in the database.

The fast way

Use database fields to keep things smooth. The field containing the filename in the database is name. You are not used to it but this is a good place to take advantage of it.

def __unicode__(self, *args, **kwargs):
		return u'%s' % self.original_image.name

Firefox has this great tool which allows you to check what's going on inside a page. From css to js, DOM elements and Net traffic, plus a console.

It's easy to read and interact with it on all tabs. My only problem was I didn't had that on my other browsers (IE, Safari, Opera).

Internet Explorer's Dev Tools are really patchy, you cant see an updated version of he DOM on an ajax action or when you load some content. For Opera, it took me around 30 mins to activate it first time, now i don't even remember where I need to go to activate it.

Firebug Lite

I always wanted to use something like Firebug on other browsers. A small link on the Firebug page solved my problems: Firebug Lite. Now you can use the same interface on IE, Safari and Opera with a simple drag and drop on the bookmarks bar.

Keep in mind it's a Lite version

Some of the functionalities you are used to from Firebug might not be available on Firebug Lite version (eg. edit attributes) but it's easier to work on one environment than switching between different ones.