Django-Headline
===============

Complex of tags and filters for easy replacement of text
with alternative font faces. For browsers, who doesn`t
support it by themselves.


1. Copyright
2. Regards
3. Reqirements
4. Installation and configuration
5. Usecase
6. Known improvements


1. Copyright
------------

Copyright (C) 2009 Igor "SkAZi" Potapov <igor@potapoff.org>

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.



2. Regards
----------

Based on django-image-replacement:
http://code.google.com/p/django-image-replacement/
Thanx to Ned for trully transparent text algorythm:
http://nedbatchelder.com/blog/200801/truly_transparent_text_with_pil.html
Thanx to Iola for ideas and technics from django-rendertext
http://code.google.com/p/django-rendertext/
Thanx to Anton Gritsay (http://angri.ru/) for moral encouragement and useful 
hints.



3. Reqirements
--------------

- Python 2.4+
- Python Image Library
- Freetype2
- Django 1.0+



4. Installation ad configuration
--------------------------------

Put headlines.py into templatetags folder of your project.

settings.py

# Cache files folder, based on settings.MEDIA_ROOT 
HEADLINE_CACHE_DIR = 'tmp/textcache'

# Fonts files folder, based on settings.MEDIA_ROOT 
HEADLINE_FONTS_DIR = 'fonts'

# Template for % output, default is:
# <img alt="%(text)s" src="%(url)s" class="png" width="%(width)s" height="%(height)s" />
HEADLINE_TEMPLATE = """
    <img alt="%(text)s" src="%(url)s" />
"""

# Png optimizer. Optional.
HEADLINE_PNG_OPTIMIZER = "optipng -q -o7 %(file)s"

# Class presets
HEADLINE_CLASSES = {
   "<class_name>": {
       'font': <file>,
       'size': <size>,
       'color': <hex color>,
       'decoration': {  # Optional
            'underline': -10,
            'strikeout': 0,
            'opacity': 0.5,
        }
   }
}



5. Usecase
----------

template.html

{% load headline %}

Param string:
   <class>[, <break type>]
   <font file>, <size>, <color>[, <break type>][, <decorations>]
Break type:
   none, br, all (spaces + br)
Decorations:
   underlined[:<shift>], 
   strikeout[:<shift>], 
   opacity[:<value>]


Filter:
   {{ foo|headline:"font.ttf,20,#000" }}
   {{ foo|headline:"font.ttf,20,#000,underline,all" }}
   {{ foo|headline:"base,br" }}

Inclusion tag:
   {% headline "font.ttf,20,opacity:0.5,#000" %}Big {{ foo }}{% endheadline %}
   {% headline "font.ttf,20,#000,strikeout:-5,none" %}Big {{ foo }}{% endheadline %}
   {% headline "base" %}Big {{ foo }}{% endheadline %}

Context modifier tag:
   {% headlines foo_list bar_dict baz_var "And some text" as headers "font.ttf,20,#000" %}
   {% headlines foo_list bar_dict baz_var "And some text" as headers "font.ttf,20,#000,all" %}
   {% headlines foo_list bar_dict baz_var "And some text" as headers "base" %}



6. Known improvements
---------------------
- Some bold handed fonts, that not to be able to get into bounding box
  provides an error

You must know that:
- optipng recompression does not works with IE6