Metadata-Version: 1.1
Name: emencia.django.countries
Version: 0.2.2
Summary: List of manageable countries for your Django projects
Home-page: https://github.com/emencia/emencia-django-countries
Author: Fantomas42
Author-email: support@emencia.com
License: BSD License
Description: .. _Django: https://www.djangoproject.com/
        
        ========================
        Emencia Django Countries
        ========================
        
        A Django application who contains world country list that can be displayed with a priority order.
        
        Usefull for forms or for models which needs a country list ordered.
        
        .. contents::
        
        Links
        *****
        
        * Download his `PyPi package <https://pypi.python.org/pypi/emencia.django.countries>`_;
        * Clone it on his `repository <https://github.com/emencia/emencia-django-countries>`_;
        
        Requires
        ********
        
        * ``setuptools``;
        * `Django`_ >= 1.4 (should be compatible to *Django 1.8* and beyond);
        
        Install
        *******
        
        First install the package: ::
        
            pip install emencia.django.countries
        
        Add it to your installed Django apps in settings:
        
        .. sourcecode:: python
        
            INSTALLED_APPS = (
                ...
                'emencia.django.countries',
                ...
            )
            
        Finally run the Django commands ``migrate`` to install app database tables, this will also fill ``Country`` model with initial datas for countries.
        
        Usage
        *****
        
        By default when the fixture is loaded all the countries a leveled to 0, 
        the default and displayed by alphabetical order.
        
        .. sourcecode:: python
        
            >>> from emencia.django.countries.models import Country
            >>> Country.objects.all()
            [<Country: Afghanistan>, <Country: Albania>, <Country: Algeria>, '...(remaining elements truncated)...']
        
        So if you don't want to display *Afghanistan* as the first country of your list, 
        you have a set a high value to the **level** attribute for all the countries you want.
        
        Now if you want to retrieve your country list ordered do this:
        
        .. sourcecode:: python
        
            >>> france = Country.objects.get(iso='FR')
            >>> france.level = 100
            >>> france.save()
        
            >>> Country.objects.all()
            [<Country: France>, <Country: Afghanistan>, <Country: Albania>, '...(remaining elements truncated)...']
        
        But if you only want a short list of countries with the level attribute set, you can do this:
        
        .. sourcecode:: python
        
            >>> Country.objects.leveled()
            [<Country: France>]
        
        This will return only the countries with a level value different than 0.
        
        Template Context Processors
        ---------------------------
        
        Sometimes it can be usefull to have all the countries in the context for rendering templates,
        so a template context processor is provided.
        
        .. sourcecode:: python
        
            >>> TEMPLATE_CONTEXT_PROCESSORS = (
            ...      # Your template context processors
            ...      'emencia.django.countries.context_processors.countries',
            ... )
        
        This template context processor, provides 2 variables in the context :
        
        * COUNTRIES_LIST
        * COUNTRIES_LIST_LEVELED
        
        Template tags
        -------------
        
        But in general it's a waste of ressources to have all the countries loaded in the context,
        because it make a database request for each request, so template tags have been implemented.
        
        In your templates, to get the countries list, simply do this. ::
        
            {% load countries_tags %}
        
            {% get_countries %}
        
        It will load the countries list in the local context of the template, in a variable named **COUNTRIES**
        But if you want to change the name of this variable use this syntax. ::
        
            {% get_countries as MY_COUNTRIES %}
        
        If you only want to have the short list of countries, use this tag. ::
        
            {% get_countries_leveled as MY_COUNTRIES %}
        
        Of course the same syntax apply to this tag.
        
        
        Changelog
        =========
        
        Version 0.2.1 - 2015/12/10
        --------------------------
        
        * Fixed bad path for ``HISTORY.rst`` in ``setup.py``;
        
        Version 0.2.0 - 2015/12/10
        --------------------------
        
        * Ensure compatibility with ``Django>=1.7``:
          
          * Added compatibility support in model manager with ``get_queryset`` method;
          * Added Django migration;
          * Now loading initial data fixtures from a data migration since ``Django>=1.7`` don't do it automatically anymore;
        
        * Update setup.py for better package classifier and packages infos;
        
        Version 0.1.1 - 2013/09/26
        --------------------------
        
        * Fix package MANIFEST for missing rule for fixture data file;
        
        Version 0.1 - 2013/05/03
        ------------------------
        
        * First release as a package;
        
Keywords: django,countries
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 1.4
Classifier: Framework :: Django :: 1.5
Classifier: Framework :: Django :: 1.6
Classifier: Framework :: Django :: 1.7
Classifier: Framework :: Django :: 1.8
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
