django-settings-export 1.2.1
This Django app allows you to export certain settings to your templates.
License: BSD

``django-settings-export``
##########################


|version| |travis| |coverage|


Often it is needed to make some of your Django project's settings
accessible from within templates. This app provides a simple mechanism
for doing just that.


**Principles:**

* *Explicit is better than implicit:* Only explicitly listed
  settings keys are exported to templates.
* *Errors should never pass silently:* Accessing an undefined
  or unexported setting key from a template results in an exception.


Tested on Python 2.7+, Django 1.5+.


Installation
============

.. code-block:: bash

    $ pip install django-settings-export


Add ``'django_settings_export.settings_export'`` to
template context processor list in your ``settings.py``:

**Django 1.8 and newer:**

.. code-block:: python

    TEMPLATES = [
        {
            # …
            'OPTIONS': {
                'context_processors': [
                    # …
                    'django_settings_export.settings_export',
                ],
            },
        },
    ]

**Django older than 1.8:**

.. code-block:: python

    TEMPLATE_CONTEXT_PROCESSORS = [
        # [...]
        'django_settings_export.settings_export',
    ]



Usage
=====

All settings that should be made accessible from templates need to be
explicitly listed in ``settings.SETTINGS_EXPORT``:


.. code-block:: python

    # settings.py

    DEBUG = True
    GA_ID = 'UA-00000-0'

    SETTINGS_EXPORT = [
        'DEBUG',
        'GA_ID',
    ]



Now you can access those exported settings from your templates
via ``settings.<KEY>``:


.. code-block:: html

    <!-- template.html -->

    {% if not settings.DEBUG %}
        <script>ga('create', '{{ settings.GA_ID }}', 'auto');</script>
    {% endif %}


The ``settings`` variable is an instance of ``dict`` subclass, so
you use all the methods ``dict`` provides. For example, you can iterate over
the keys and values using , ``settings.keys``, ``settings.values``,
``settings.items``, etc:

.. code-block:: html

    {% for key, value in settings.items %}
        {{ key }}: {{ value }}
    {% endfor %}


Changing the ``settings`` variable name
---------------------------------------

If you wish to change the name of the context variable to something besides
``settings``, add ``SETTINGS_EXPORT_VARIABLE_NAME = 'custom_name'``
to your ``settings.py``. This is useful when some other plugin is already adding
``settings`` to your template contexts.


.. code-block:: python

    # settings.py
    FOO = 'bar'
    SETTINGS_EXPORT = ['FOO']
    SETTINGS_EXPORT_VARIABLE_NAME = 'my_config'



.. code-block:: html

    <!-- template.html -->

    {{ my_config.FOO }}


Exceptions
----------

These custom exceptions can be thrown:

* Listing an undefined setting key in ``SETTINGS_EXPORT`` results in an
  ``UndefinedSettingError``.
* Accessing a unexported setting key on the ``settings`` object in a template
  results in an ``UnexportedSettingError``.

All subclass from ``django_settings_export.SettingsExportError``.




Demo & Tests
------------

See the source code of the bundled
`demo app <https://github.com/jkbrzt/django-settings-export/tree/master/tests>`_.


Development
===========

.. code-block:: bash

    $ cd tests

    # Run demo
    $ python manage.py runserver

    # Run tests on current Python
    $ python manage.py test

    # Run tests on all Pythons
    $ tox


Change Log
==========

See `CHANGELOG <https://github.com/jkbrzt/django-settings-export/blob/master/CHANGELOG.rst>`_.


Licence
=======

BSD. See `LICENCE <https://github.com/jkbrzt/django-settings-export/tree/master/LICENCE>`_ for more details.


Contact
=======


Jakub Roztocil

* http://roztocil.co
* https://github.com/jkbrzt
* https://twitter.com/jkbrzt


.. |travis| image:: https://api.travis-ci.org/jkbrzt/django-settings-export.svg
    :target: http://travis-ci.org/jkbrzt/django-settings-export
    :alt: Build Status of the master branch


.. |version| image:: https://badge.fury.io/py/django-settings-export.svg
    :target: https://pypi.python.org/pypi/django-settings-export
    :alt: PyPi

.. |coverage| image:: https://img.shields.io/coveralls/jkbrzt/django-settings-export.svg?branch=master
    :target: https://coveralls.io/r/jkbrzt/django-settings-export?branch=master
    :alt: Coverage