Django URL Parameters

Introduction

URL parameters are a crucial aspect of building dynamic web applications. They allow your Django application to respond differently based on the information included in the URL itself. For example, when viewing a specific product on an e-commerce site, the product ID is often included in the URL. This parameter tells Django which specific product to fetch from the database and display to the user.

In this tutorial, we'll explore how to define, capture, and use URL parameters in your Django applications. You'll learn how to:

• Configure URL patterns to capture parameters
• Access these parameters in your views
• Use parameters to dynamically control your application's behavior

Understanding URL Parameters

URL parameters (or URL arguments) are values that are passed to a web application through the URL. In Django, these parameters are specified in the URL pattern and then passed to the view function.

Consider a simple blog website. You might have URLs like:

• /blog/1/ - to show post with ID 1
• /blog/2/ - to show post with ID 2

Instead of creating a separate URL pattern for each post, Django allows you to create a single pattern that captures the post ID as a parameter.

Types of URL Parameters in Django

Django supports several types of URL parameters:

1. Path parameters (positional arguments)
2. Query parameters (GET parameters)
3. Slug parameters (human-readable identifiers)
4. Converter-based parameters (with type specification)

Let's examine each type in detail.

Path Parameters

Path parameters are part of the URL path itself. They are defined in your URL patterns using angle brackets.

Basic Example

Here's how to create a URL pattern that captures a numeric ID:

python

# urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('blog/<int:post_id>/', views.post_detail, name='post_detail'),
]

In this example:

• <int:post_id> defines a parameter named post_id of type int
• The view function will receive this parameter as an argument

Now let's create the corresponding view function:

python

# views.py
from django.shortcuts import render, get_object_or_404
from .models import Post

def post_detail(request, post_id):
    # post_id is automatically passed to the view
    post = get_object_or_404(Post, id=post_id)
    return render(request, 'blog/post_detail.html', {'post': post})

When a user visits /blog/42/, Django will:

1. Match the URL pattern
2. Extract 42 as the post_id
3. Call the post_detail view with post_id=42
4. The view will then fetch the post with ID 42 and render the template

Path Converters

Django provides several built-in path converters to validate and convert URL parameters:

Converter	Description	Example
str	Matches any non-empty string except /	<str:username>
int	Matches positive integers	<int:post_id>
slug	Matches slug strings (letters, numbers, hyphens)	<slug:post_slug>
uuid	Matches UUID strings	<uuid:order_id>
path	Matches any non-empty string including /	<path:file_path>

Example: Using Different Converters

python

# urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('users/<str:username>/', views.user_profile, name='user_profile'),
    path('posts/<slug:post_slug>/', views.post_by_slug, name='post_by_slug'),
    path('files/<path:file_path>/', views.serve_file, name='serve_file'),
]

The corresponding views:

python

# views.py
def user_profile(request, username):
    # Handle user profile view
    return render(request, 'profiles/user.html', {'username': username})

def post_by_slug(request, post_slug):
    # Fetch post by slug
    post = get_object_or_404(Post, slug=post_slug)
    return render(request, 'blog/post.html', {'post': post})

def serve_file(request, file_path):
    # Handle file serving
    return HttpResponse(f"Serving file: {file_path}")

Multiple URL Parameters

You can include multiple parameters in a single URL pattern:

python

# urls.py
path('blog/<int:year>/<int:month>/<int:day>/', views.archive_day, name='archive_day'),

And in your view:

python

# views.py
def archive_day(request, year, month, day):
    # Get posts from specific date
    posts = Post.objects.filter(
        published_date__year=year,
        published_date__month=month,
        published_date__day=day
    )
    return render(request, 'blog/archive.html', {
        'posts': posts,
        'date': date(year, month, day)
    })

Query Parameters (GET Parameters)

Query parameters are not specified in the URL pattern but are appended to the URL after a question mark (?). For example:

/search/?q=django&category=tutorials

To access these parameters in your view:

python

# views.py
def search(request):
    query = request.GET.get('q', '')  # Default to empty string if not provided
    category = request.GET.get('category', 'all')
    
    results = []
    if query:
        results = Article.objects.filter(title__icontains=query)
        if category != 'all':
            results = results.filter(category=category)
    
    return render(request, 'search.html', {
        'query': query,
        'category': category,
        'results': results
    })

The URL pattern for this would be simple:

python

# urls.py
path('search/', views.search, name='search'),

Creating URLs with Parameters

To link to views that require parameters, use the {% url %} template tag (in your templates) or reverse() function (in your Python code):

In Templates:

html

<!-- Link to a specific post -->
<a href="{% url 'post_detail' post_id=42 %}">View Post #42</a>

<!-- Link with multiple parameters -->
<a href="{% url 'archive_day' year=2023 month=10 day=15 %}">Posts from Oct 15, 2023</a>

In Python Code:

python

from django.urls import reverse

# Generate URL for a specific post
post_url = reverse('post_detail', kwargs={'post_id': 42})

# Generate URL with multiple parameters
archive_url = reverse('archive_day', kwargs={'year': 2023, 'month': 10, 'day': 15})

Real-World Example: Product Catalog

Let's build a simple product catalog with category and product detail pages:

Models

python

# models.py
from django.db import models

class Category(models.Model):
    name = models.CharField(max_length=100)
    slug = models.SlugField(unique=True)
    
    def __str__(self):
        return self.name

class Product(models.Model):
    name = models.CharField(max_length=200)
    slug = models.SlugField(unique=True)
    category = models.ForeignKey(Category, on_delete=models.CASCADE)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    description = models.TextField()
    
    def __str__(self):
        return self.name

URLs

python

# urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('', views.product_list, name='product_list'),
    path('category/<slug:category_slug>/', views.category_detail, name='category_detail'),
    path('product/<slug:product_slug>/', views.product_detail, name='product_detail'),
]

Views

python

# views.py
from django.shortcuts import render, get_object_or_404
from .models import Category, Product

def product_list(request):
    categories = Category.objects.all()
    products = Product.objects.all()
    
    # Handle filtering by price
    min_price = request.GET.get('min_price')
    max_price = request.GET.get('max_price')
    
    if min_price:
        products = products.filter(price__gte=min_price)
    if max_price:
        products = products.filter(price__lte=max_price)
    
    return render(request, 'shop/product_list.html', {
        'categories': categories,
        'products': products,
        'min_price': min_price,
        'max_price': max_price
    })

def category_detail(request, category_slug):
    category = get_object_or_404(Category, slug=category_slug)
    products = Product.objects.filter(category=category)
    
    return render(request, 'shop/category_detail.html', {
        'category': category,
        'products': products
    })

def product_detail(request, product_slug):
    product = get_object_or_404(Product, slug=product_slug)
    
    return render(request, 'shop/product_detail.html', {
        'product': product
    })

Templates

Product list template (product_list.html):

html

<h1>Our Products</h1>

<form method="get">
  <label>Min Price: <input type="number" name="min_price" value="{{ min_price }}"></label>
  <label>Max Price: <input type="number" name="max_price" value="{{ max_price }}"></label>
  <button type="submit">Filter</button>
</form>

<h2>Categories</h2>
<ul>
  {% for category in categories %}
    <li>
      <a href="{% url 'category_detail' category_slug=category.slug %}">
        {{ category.name }}
      </a>
    </li>
  {% endfor %}
</ul>

<h2>Products</h2>
<ul>
  {% for product in products %}
    <li>
      <a href="{% url 'product_detail' product_slug=product.slug %}">
        {{ product.name }} - ${{ product.price }}
      </a>
    </li>
  {% endfor %}
</ul>

Category detail template (category_detail.html):

html

<h1>{{ category.name }}</h1>

<h2>Products in this category</h2>
<ul>
  {% for product in products %}
    <li>
      <a href="{% url 'product_detail' product_slug=product.slug %}">
        {{ product.name }} - ${{ product.price }}
      </a>
    </li>
  {% empty %}
    <li>No products found in this category.</li>
  {% endfor %}
</ul>

<p><a href="{% url 'product_list' %}">Back to all products</a></p>

Product detail template (product_detail.html):

html

<h1>{{ product.name }}</h1>
<p><strong>Price:</strong> ${{ product.price }}</p>
<p><strong>Category:</strong> 
  <a href="{% url 'category_detail' category_slug=product.category.slug %}">
    {{ product.category.name }}
  </a>
</p>
<div class="description">
  {{ product.description|linebreaks }}
</div>

<p><a href="{% url 'product_list' %}">Back to all products</a></p>

In this example, we use:

• Path parameters with slugs for category and product pages
• Query parameters for filtering products by price range
• URL reversing to create links between related pages

Common Pitfalls and Best Practices

Pitfalls to Avoid

1. Missing parameters: Always ensure that your view function accepts all parameters defined in the URL pattern.
2. Type mismatches: Use appropriate path converters to validate input before it reaches your view.
3. Forgetting to handle missing query parameters: Always use request.GET.get('param', default_value) instead of request.GET['param'] to avoid KeyErrors.

Best Practices

1. Use named URL patterns: Always give your URL patterns a name for easier referencing.
2. Choose appropriate converters: Use the most specific converter that makes sense (e.g., uuid for UUIDs).
3. Use slugs for SEO-friendly URLs: For content that users might share or bookmark.
4. Keep URLs readable: Design URLs that are easy to understand and remember.
5. Validate parameters: Even with path converters, perform additional validation in your views.

Summary

URL parameters in Django provide a powerful way to create dynamic web applications. In this tutorial, we've covered:

• Different types of URL parameters (path, query)
• How to define URL patterns that capture parameters
• Using path converters to validate input
• Accessing parameters in view functions
• Creating URLs with parameters in templates and Python code
• Building a practical example with a product catalog

By mastering URL parameters, you can create more flexible and user-friendly Django applications that respond dynamically to user input and display the most relevant content.

Additional Resources

• Django URL Dispatcher Documentation
• Django URL Path Converters
• Django Reverse Resolution of URLs

Exercises

1. Create a blog application with URLs for listing posts by year, month, and optionally by day.
2. Build a user profile system where each user has a profile accessible at /users/<username>/.
3. Implement a product search page that accepts query parameters for filtering by category, price range, and search terms.
4. Create a URL scheme for an API that accepts both path parameters and query parameters.