.. _dict-variables:

Dictionary Variables (1.5+)
---------------------------

Dictionary variables provide a way to define deep structured information when
rendering a template.

Basic Usage
~~~~~~~~~~~

Dictionary variables are, as the name suggests, dictionaries of key-value
pairs. The dictionary values can, themselves, be other dictionaries and lists
- the data structure can be as deep as you need.

For example, you could provide the following dictionary variable in your
``cookiecutter.json``::

    {
        "project_slug": "new_project",
        "file_types": {
            "png": {
                "name": "Portable Network Graphic",
                "library": "libpng",
                "apps": [
                    "GIMP"
                ]
            },
            "bmp": {
                "name": "Bitmap",
                "library": "libbmp",
                "apps": [
                    "Paint",
                    "GIMP"
                ]
            }
        }
    }


The above ``file_type`` dictionary variable creates
``cookiecutter.file_types``, which can be used like this::

    {% for extension, details in cookiecutter.file_types|dictsort %}
    <dl>
      <dt>Format name:</dt>
      <dd>{{ details.name }}</dd>

      <dt>Extension:</dt>
      <dd>{{ extension }}</dd>

      <dt>Applications:</dt>
      <dd>
          <ul>
          {% for app in details.apps -%}
              <li>{{ app }}</li>
          {% endfor -%}
          </ul>
      </dd>
    </dl>
    {% endfor %}


Cookiecutter is using `Jinja2's for expression <http://jinja.pocoo.org/docs/dev/templates/#for>`_ to iterate over the items in the dictionary.