alphafilter Documentation Release 0.6 coordt September 09, 2013
CONTENTS i
ii
alphafilter Documentation, Release 0.6 Contents: CONTENTS 1
alphafilter Documentation, Release 0.6 2 CONTENTS
CHAPTER ONE INSTALLATION 1. The easiest method is to use pip or easy_install pip install django-alphafilter or easy_install django-alphafilter 2. If you download the source, you can install it by running the setup.py script: cd /path/to/django-alphafilter/ python setup.py install 3. Add alphafilter to your project s settings.py file, so Django will find the templates and template tag. 1.1 Dependencies None. 3
alphafilter Documentation, Release 0.6 4 Chapter 1. Installation
CHAPTER TWO GETTING STARTED There are two ways to incorporate the alphabet filter into your project and applications. The first is modifying one or more application s ModelAdmin classes. The second is when you don t have control of the code and want to add the feature, such as to django.contrib.auth. Both methods require you to override the default admin template for that model or app. 2.1 Overriding the Admin Template In order to properly display the alphabet filter in the admin, the change_list.html template must be slightly changed. django-alphafilter includes a template the makes the proper changes. This template extends the default admin template, so using it must be done on an per-application or per-model basis. You can merge the default Django admin change_list.html template with django-alphafilter s changes to make a single template override. django-alphafilter doesn t do this so it can support multiple Django versions. Within your project s template directory, you need to create an admin directory, and a directory with the name of the application, and optionally the name of the model. For example, if you were adding the filter on the Tag model of an application named cooltags, the directory structure would look like: MyProject templates admin cooltags change_list.html tag change_list.html <-- For every model in the cooltags <-- For just the Tag model The change_list.html file simply needs to contain the line: {% extends "alphafilter/change_list.html" %} Note: You cannot place this template in the admin directory, as it leads to an infinite loop of inheritance. As mentioned above, you can create a new change_list.html template by copying the django.contrib.auth template and make the same adjustments as the django-alphafilter s template. 5
alphafilter Documentation, Release 0.6 2.2 Altering Your Own Model Admin If you have control of the application s code, you can easily support django-alphafilter by adding an alphabet_filter attribute to your ModelAdmin class, like so: class TestNameAdmin(admin.ModelAdmin): model = TestName alphabet_filter = sorted_name The value of alphabet_filter is the name of the field to use for filtering. 2.3 Altering Another Application s Model Admin Sometimes you want to use the alphabet filter, but you don t want to modify someone else s code. A perfect example is django.contrib.auth. To enable the alphabet filter on the User model, you can add a configuration setting in your settings.py. The ALPHAFILTER_ADMIN_FIELDS setting is a dictionary in the form of { <appname>.<modelname> : <fieldname>, [... ] } For example: ALPHAFILTER_ADMIN_FIELDS = { auth.user : username, auth.group : name, } 6 Chapter 2. Getting Started
CHAPTER THREE THE DEFAULT ALPHABET django-alphafilter will always show the letters that are filterable based on data in the model, regardless of the language or encoding. It also displays, by default, the ASCII alphabet and digits as disabled characters. 3.1 Changing the Default Alphabet The configuration setting DEFAULT_ALPHABET can be a string, tuple, list or callable that returns a string, list or tuple. If you only what the ASCII characters, no digits: DEFAULT_ALPHABET = u ABCDEFGHIJKLMNOPQRSTUVWXYZ For the German alphabet: DEFAULT_ALPHABET = u 0123456789A\xc4BCDEFGHIJKLMNO\xd6PQRS\xdfTU\xdcVWXYZ For the Icelandic alphabet: DEFAULT_ALPHABET = u 0123456789A\xc1BD\xd0E\xc9FGHI\xcdJKLMNO\xd3PRSTU\xdaVXY\xdd\xde\xd6 To show nothing except the characters in the data: DEFAULT_ALPHABET = u Add DEFAULT_ALPHABET to the project s settings.py to for a global change. Add a DEFAULT_ALPHABET attribute on your model to change it on a model-by-model basis. 7
alphafilter Documentation, Release 0.6 8 Chapter 3. The Default Alphabet
CHAPTER FOUR THE QS_ALPHABET_FILTER TEMPLATE TAG If you wanted to have an alphabet filter in a regular template, the qs_alphabet_filter template tag will generate this for you. 4.1 Requirements Make sure that Django s TEMPLATE_CONTEXT_PROCESSORS setting in your settings.py includes django.core.context_processors.request, which is not included by default. TEMPLATE_CONTEXT_PROCESSORS = ( "django.core.context_processors.auth", "django.core.context_processors.debug", "django.core.context_processors.i18n", "django.core.context_processors.media", "django.core.context_processors.request", ) Without this context processor, the template tag will have no idea which letter was clicked on and can t display the currently selected letter. 4.2 Usage Within your template, load the template tag library and use the qs_alphabet_filter tag, with at least two parameters: the variable containing the QuerySet and the name (or variable containing the name) of the field to apply the alphabet filter. {% load alphafilter %} {% qs_alphabet_filter objects last_name %} With two parameters, the default template alphafilter/alphabet.html is used to render the selection. You may pass a third parameter for your own template (but you can simply override the default). There are three other things that you may need: the alphabet filter template, CSS styles, and a view that returns a filtered QuerySet to display the results. Notice that the queryset passed to the templatetag will be used to generate the list of availabe letters, so it can t be the same as the one used to display the list of filtered objects. Take a look to example project s homepage.html template and the views in Alphafilter.views. 9
alphafilter Documentation, Release 0.6 4.2.1 Alphabet Filter Template The template tag allows you to specify the template that is specifically rendered, alphafilter/alphabet.html and should fit most needs. For those of you who are more adventurous, the context of the template includes: but the default is choices A list of dictionaries containing all the choices to display. This will include all letters of the DEFAULT_ALPHABET setting as well as additional letters contained within the data, and an item to display all of the items. This list is sorted with the All item first, and the other items sorted in alphabetical order. Each list item dictionary contains: has_entries True if the letter has entries in the data set. link The HTML link for the choice, typically rendered as the href of an <a> tag. For example: <a href="{{ choice.link }}"> title The name of the letter, or (localizable) All active This letter is currently selected. The default template looks something like: {% if choices %} <ul class="alphabetfilter"> {% for choice in choices %} <li>{% if choice.has_entries %} <a href="{{ choice.link }}"> {% else %} <span class="inactive"> {% endif %} {% if choice.active %} <span class="selected"> {% endif %} {{ choice.title }} {% if choice.active %} </span> {% endif %} {% if choice.has_entries %} </a> {% else %} </span> {% endif %} </li> {% endfor %} </ul> <br class="clear" /> {% endif %} 4.2.2 CSS Styles For convenience, a template is included for some basic CSS styling, simply include alphafilter/alphafilter_styles.html in the appropriate place in your template: <head> <meta http-equiv="content-type" content="text/html; charset=utf-8"> <title>alphafilter Test</title> 10 Chapter 4. The qs_alphabet_filter Template Tag
alphafilter Documentation, Release 0.6 </head> {% include "alphafilter/alphafilter_styles.html" %} You can also override the template in your project by simply creating a file called alphafilter_styles.html within a directory named alphafilter inside your projects templates directory. The default styles are: <style type="text/css" media="screen"> ul.alphabetfilter { list-style: none; display: inline; } ul.alphabetfilter li { width: 0.7em; display: inline; }.inactive { color: #999; }.selected { color: red; } </style> 4.2.3 The View Django AlphaFilter includes a generic view named alphafilter.views.alphafilter that is useful as an example, but might not be very useful for all situations. The view needs to do two things: look for the filter in request.getand add a filtered QuerySet in the context for rendering the template. The template can then iterate through the QuerySet to display the results. The example view accepts an HttpRequest, a QuerySet, and a template name. It finds the filter by looking for a key in the GET parameters containing istartswith, and uses that to filter the QuerySet. The filtered QuerySet is passed into the context as objects. def alphafilter(request, queryset, template): qs_filter = {} for key in request.get.keys(): if istartswith in key: qs_filter[str(key)] = request.get[key] break return render_to_response( template, { objects : queryset.filter(**qs_filter), unfiltered_objects : queryset}, context_instance=requestcontext(request) ) 4.2. Usage 11
alphafilter Documentation, Release 0.6 12 Chapter 4. The qs_alphabet_filter Template Tag
CHAPTER FIVE REFERENCE 5.1 Settings 5.1.1 DEFAULT_ALPHABET This setting is used to display characters in the admin interface no matter what the data may contain. Characters are always displayed if they are in the data, but not in the DEFAULT_ALPHABET. The DEFAULT_ALPHABET can be a string, list of strings, a tuple of strings, or a callable (a function or class instance with a call method) that returns one of the previous types. DEFAULT_ALPHABET defaults to the string.ascii_uppercase + string.digits. Globally change this value by setting it in your settings.py file, or change it on a single model by setting it in the model s ModelAdmin. 5.1.2 ALPHAFILTER_ADMIN_FIELDS The ALPHAFILTER_ADMIN_FIELDS setting is a dictionary in the form of { <appname>.<modelname> : <fieldname>, [... ] } For example: ALPHAFILTER_ADMIN_FIELDS = { auth.user : username, auth.group : name, } 13
alphafilter Documentation, Release 0.6 14 Chapter 5. Reference
CHAPTER SIX INDICES AND TABLES genindex modindex search 15