.. _`template extensions`:

Template Extensions
-------------------

*New in Cookiecutter 1.4*

A template may extend the Cookiecutter environment with custom `Jinja2 extensions`_,
that can add extra filters, tests, globals or even extend the parser.

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": ["jinja2_time.TimeExtension"]
    }

On invocation Cookiecutter tries to import the extensions and add them to its environment respectively.

In the above example, Cookiecutter provides the additional tag `now`_, after
installing the `jinja2_time.TimeExtension`_ and enabling it in ``cookiecutter.json``.

Please note that Cookiecutter will **not** install any dependencies on its own!
As a user you need to make sure you have all the extensions installed, before
running Cookiecutter on a template that requires custom Jinja2 extensions.

By default Cookiecutter includes the following extensions:

- ``cookiecutter.extensions.JsonifyExtension``
- ``cookiecutter.extensions.RandomStringExtension``
- ``jinja2_time.TimeExtension``

Jsonify extension
~~~~~~~~~~~~~~~~~

The ``cookiecutter.extensions.JsonifyExtension`` extension provides a ``jsonify`` filter in templates
that converts a Python object to JSON:

.. code-block:: jinja

    {% {'a': True} | jsonify %}

Would output:

.. code-block:: json

    {"a": true}

Random string extension
~~~~~~~~~~~~~~~~~~~~~~~

*New in Cookiecutter 1.7*

The ``cookiecutter.extensions.RandomStringExtension`` extension provides a ``random_ascii_string``
method in templates that generates a random fixed-length string, optionally with punctuation.

Generate a random n-size character string. Example for n=12:

.. code-block:: jinja

    {{ random_ascii_string(12) }}

Outputs:

.. code-block:: text

    bIIUczoNvswh

The second argument controls if punctuation and special characters
``!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~`` should be present in the result:

.. code-block:: jinja

    {{ random_ascii_string(12, punctuation=True) }}

Outputs:

.. code-block:: text

    fQupUkY}W!)!

Slugify extension
~~~~~~~~~~~~~~~~~

The ``cookiecutter.extensions.SlugifyExtension`` extension provides a ``slugify`` filter in templates
that converts string into its underscored ("slugified") version:

.. code-block:: jinja

    {% "It's a random version" | slugify %}

Would output:

.. code-block:: json

    it-s-a-random-version

It is diferent from a mere replace of spaces since it also trates some special characters
such as `'` in the example above. The function accepts all arguments that can be passed to
the `slugify` function of python-slugify. For example to change the output from
`it-s-a-random-version` to `it_s_a_random_version`, the parameter `separator='_'` would
be passed to `slugify()`.

.. _`Jinja2 extensions`: http://jinja.pocoo.org/docs/latest/extensions/
.. _`now`: https://github.com/hackebrot/jinja2-time#now-tag
.. _`jinja2_time.TimeExtension`: https://github.com/hackebrot/jinja2-time
.. _`python-slugify`: https://github.com/un33k/python-slugify