Skip to main content

DRY way to manage url parameters associated with a model instance based on Jingo.

Project description

# Django Model URLs

[![Build Status](](

This app makes urls usage DRYer.
It maps URL keywords to a model object instance by passing the object
instance as argument to the URL.

In short, having an `article` model instance, you can write this:

<a href="{{ url('article:detail', article) }}">View this article</a>

While you have been writing this so far:

<a href="{{ url('article:detail', year=article.year, month=article.month, slug=article.slug) }}">View this article</a>

This is for your templates as well as for your `reverse()` and preserves
other urls to work.

> Right now it is build for [Jinja2]( using the
easy-to-use [Jingo]( adapter.
> If you are using plain Django template, refer to version 0.3.1.
> A new version for plain Django should come out later on.

## Installation

Download via pip ![pip badge](

pip install django-model-urls

or get the bleeding edge version:

pip install git+

Add _model\_urls_ to your _settings_ file:


And you're done!

## How to use it

In the examples below we will consider this model:

class Article(models.Model):
slug = models.SlugField()
title = models.CharField(max_length=50)
date = models.DateField()

def year(self):

def month(self):

and this urls:

urlpatterns = patterns('',
ArticleView.as_view(), name="article_details"),

and `article` being an instance of the `Article` class.

### In a template

url('article_details', article)

#### In a view

from model_urls.urlresolvers import reverse

reverse('article_details', article)

Both will generate a url in this format:


## Extra tools

Basically you should be able to use `url()` and `reverse()` in all cases.
However, these tools are also available:

#### Template helpers

- `url(viewname, *args, **kwargs)` will try to detect an instance in arguments
and choose wheter to use _simple\_url()_ or _model\_url()_ otherwise.
- `simple_url(viewname, *args, **kwargs)` is an alias to Jingo's `url()`
helper to force using it.
- `model_url(viewname, instance, *args, **kwargs)` will generate the url from
the instance in first argument.

#### Url reversing

These functions are available in `model_urls.urlresolvers`.

- `model_reverse(viewname, instance, urlconf=None, args=None, kwargs=None,
prefix=None, current_app=None)` will generate the url based on the instance
- `reverse(viewname, *args, **kwargs)` will fallback to _model\_reverse()_ if
an instance is found in arguments or to Django's _reverse()_ otherwise.

## Configuration

An optional configuration is for your settings is:


This option will not allow the Jingo's `url()` helper to be overriden by the
one from model_urls.

In this case you should use `model_url()` to use an instance.

### Further examples

#### Use cases

A common use case is switching from pk based url to slug.
Using django-model-urls means updating the _urls.py_ file to consider slug
without altering views or template files.

#### Read tests

Refer to [](
to see more usages.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-model-urls, version 0.4.0
Filename, size File type Python version Upload date Hashes
Filename, size django-model-urls-0.4.0.tar.gz (5.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page