Metadata-Version: 2.0
Name: fancy-tag
Version: 0.2.0
Summary: A powerful replacement for Django's simple_tag decorator that adds supports for positional, keyword arguments and template variable assignment.
Home-page: https://github.com/trapeze/fancy_tag
Author: Sam Bull
Author-email: sam@pocketuniverse.ca
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Framework :: Django
Classifier: License :: OSI Approved :: BSD License
Requires-Dist: Django (>=1.0)

Fancy Tag
=========

Overview
--------

``fancy_tag`` is a template tag decorator designed to replace Django's built in
``simple_tag`` decorator. It's backwards compatible with ``simple_tag`` and adds
new calling options like named arguments.

Features
--------

* Keyword arguments - arguments can be explicitly assigned to parameter
  specific parameters in the template tag function

* Variable length arguments - The "``*args``" and "``**kwargs``" notation

* The trailing "``as <varname>``" to assign the output of the template tag to
  a variable in the template's context.

Installation
------------

1. Add the fancy_tag package to your Python path


2. Instead of::

    @register.simple_tag
    def some_tag(arg1, arg2):
        return '%s %s' % (arg1, arg2)


   Use::

    @fancy_tag(register)
    def some_tag(arg1, arg2):
        return '%s %s' % (arg1, arg2)

Examples
--------

Keyword Arguments
~~~~~~~~~~~~~~~~~

Python Code::

    @fancy_tag(register)
    def say_cheese(name, thing_to_say='cheese'):
        return 'Hey, %s! Say %s!' % (name, thing_to_say)

Template Code::

    {% say_cheese "Jacob" %} -> "Hey, Jacob! Say Cheese!"
    {% say_cheese "Malcolm" thing_to_say="Vegemite" %} -> "Hey Malcolm! Say Vegemite!"

Variable Length Arguments
~~~~~~~~~~~~~~~~~~~~~~~~~

Python Code::

    @fancy_tag(register)
    def greet_people(*args):
        return 'Hello, %s' % ', '.join(args)


Template Code::

    {% greet_people "Larry" "Darryl" "Darryl" %}

Produces:

Hello, Larry, Darryl, Darryl

Variable Length Keyword Arguments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Python Code::

    @fancy_tag(register)
    def watch_your_mouth(s, **kwargs):
        for key, value in kwargs.items():
            s = s.replace(key, value)
        return s

Template Code::

    {% watch_your_mouth "You damn dirty ape!" "damn"="doggone" "dirty"="handsome" %}

Produces:

You doggone handsome ape!"

Assigning Output To A Variable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Python Code::

    @fancy_tag(register)
    def now(format_string):
        df = DateFormat(datetime.now())
        return df.format(format_string)

Template Code::

    {% now as just_now %}
    Oh no, it's already {{ just_now }}!

Produces:

Oh no, it's already February 20th, 2010!

Accessing the Template Context
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Python Code::

    @fancy_tag(register, takes_context)
    def say_hello_to_user(context, phrase):
        return u'%s, %s!' % (phrase, context['user'])

Template Context::

    {'user': 'Tobias'}  # Provided by a template context processor, for example

Template Code::

    {% say_hello_to_user "Hallo" %}

Produces:

Hallo, Tobias!

Testing
-------

With Django in your python path, run ``tests/run_tests.py`` or use 
`tox <http://tox.testrun.org/>`_ to run the tests using multiple
Python and Django versions.

Source
------

http://github.com/trapeze/fancy_tag

License
-------

fancy_tag is Copyright (c) 2010-2012 Sam Bull, Trapeze. It is free software, and
may be redistributed under the terms specified in the LICENSE file.

Credits
-------

fancy_tag is maintained by `Sam Bull <sam@pocketuniverse>`_, with support from
`Trapeze <http://trapeze.com>`_.


