.. _decorators:


Decorators
===========================

.. highlight:: python
.. automodule:: native_tags.decorators

The decorators that come with this app are there for convienence but are not necessary to use.
Their purpose is to just set some important attributes on the wrapped function and maintain docstrings.

The normal syntax (without decorators)::

    def myfunc(context):
        return context['myvar'].split()
    myfunc.function = 1
    myfunc.takes_context = 1
    myfunc.name = 'my_function_tag'
    myfunc.cache = 3600
    
Is equivalent to::

    from native_tags.decorators import function
    
    @function(takes_context=1, cache=3600, name='my_function_tag')
    def myfunc(context):
        return context['myvar'].split()
        
And can be used in the template using the `name`::

    {% my_function_tag as varsplit %}

Important Attributes
--------------------

    ``function``, ``filter``, ``comparison``, ``block`` - boolean. Determines which kind of tag the function represents.
    A function can have multiple uses (eg. function and filter)

    ``name`` - string. The actual name of the tag to use in the template. Defaults to the function name.

    ``resolve`` - boolean. If ``True``, all argments are resolved in the context of the tag.
    Set to ``False`` to parse your own raw text arguments. Default is ``True``
    
    ``takes_context`` - boolean. If ``True`` the context itself is prepended to the function arguments. Default is ``False``

    ``takes_request`` - boolean. If ``True`` the request object is prepended to the function arguments.
    Make sure ``django.core.context_processors.request`` is in your ``TEMPLATE_CONTEXT_PROCESSORS`` setting. Default is ``False``
    
    ``inclusion`` - boolean. If ``True`` then the function is treated as an inclusion tag. Inclusion tags work a bit differently in
    native tags, the function must return a tuple of (``template_name``, ``context``). This lets you dynamically define the name of
    the template to use in rendering.
    
    ``apply_filters`` - boolean. If ``True``, the filter expressions are resolved for each argument and keyword argument if present.
    Default is ``True``
    
    ``cache`` - integer. The cache timeout time in seconds to use if any.
    Default is no caching.

    ``test`` - dictionary. Configuration data for a unittest.
    Keys are: ``args``,``kwargs``, and ``result``. When testing native_tags it will
    assert that the tag called with args/kwargs will return the expected result.
    Default expected result is ``True``.
    
    ``fallback`` - arbitrary object. If for any reason the native tag you are running encounters an error,
    return this fallback value instead. Providing a default (like an empty list) is a good way to fail elegantly and not have your site crash.
    

Decorator Types
---------------
    
    .. autofunction:: function
    .. autofunction:: comparison
    .. autofunction:: block
    .. autofunction:: filter