docs/advanced/local_extensions.rst
.. _`local extensions`:
Local Extensions
----------------
*New in Cookiecutter 2.1*
A template may extend the Cookiecutter environment with local extensions.
These can be part of the template itself, providing it with more sophisticated custom tags and filters.
To do so, a template author must specify the required extensions in ``cookiecutter.json`` as follows:
.. code-block:: json
{
"project_slug": "Foobar",
"year": "{% now 'utc', '%Y' %}",
"_extensions": ["local_extensions.FoobarExtension"]
}
This example uses a simple module ``local_extensions.py`` which exists in the template root, containing the following (for instance):
.. code-block:: python
from jinja2.ext import Extension
class FoobarExtension(Extension):
def __init__(self, environment):
super(FoobarExtension, self).__init__(environment)
environment.filters['foobar'] = lambda v: v * 2
This will register the ``foobar`` filter for the template.
For many cases, this will be unnecessarily complicated.
It's likely that we'd only want to register a single function as a filter. For this, we can use the ``simple_filter`` decorator:
.. code-block:: json
{
"project_slug": "Foobar",
"year": "{% now 'utc', '%Y' %}",
"_extensions": ["local_extensions.simplefilterextension"]
}
.. code-block:: python
from cookiecutter.utils import simple_filter
@simple_filter
def simplefilterextension(v):
return v * 2
This snippet will achieve the exact same result as the previous one.
For complex use cases, a python module ``local_extensions`` (a folder with an ``__init__.py``) can also be created in the template root.
Here, for example, a module ``main.py`` would have to export all extensions with ``from .main import FoobarExtension, simplefilterextension`` or ``from .main import *`` in the ``__init__.py``.