django-spurl 0.6.8

Adding query parameters to URLs

Say you have a list of external URLs in your database. When you create links to these URLs in a template, you need to add a referrer=mysite.com query parameter to each. The simple way to do this might be:

{% for url, title in list_of_links %}
    <a href="{{ url }}?referrer=mysite.com">{{ title }}</a>
{% endfor %}

The problem here is that you don’t know in advance if the URLs stored in your database already have query parameters. If they do, you’ll generate malformed links like http://www.example.com?foo=bar?referrer=mysite.com.

Spurl can fix this. Because it knows about the components of a URL, it can add parameters onto an existing query, if there is one.

{% for url, title in list_of_links %}
    <a href="{% spurl base=url add_query="referrer=mysite.com" %}">{{ title }}</a>
{% endfor %}

Note that when you pass a literal string to Spurl, you have to wrap it in double quotes. If you don’t, Spurl will assume it’s a variable name and try to look it up in the template’s context.

SSL-sensitive external URLs.

Suppose your site needs to display a gallery of images, the URLs of which have come from some third-party web API. Additionally, imagine your site needs to run both in secure and non-secure mode - the same content is available at both https or http URLs (depending on whether a visitor is logged in, say). Some browsers will complain loudly (displaying “Mixed content warnings” to the user) if the page being displayed is https but some of the assets are http. Spurl can fix this.

{% for image_url in list_of_image_urls %}
    <img src="{% spurl base=image_url secure=request.is_secure %}" />
{% endfor %}

This will take the image URL you supply and replace the scheme component (the http or https bit) with the correct version, depending on the return value of request.is_secure(). Note that the above assumes you’re using a RequestContext so that request is available in your template.

Using alongside {% url %}

Notice that Spurl’s functionality doesn’t overlap with Django’s built-in {% url %} tag. Spurl doesn’t know about your urlconf, and doesn’t do any URL reversing. In fact, Spurl is mostly useful for manipulating external URLs, rather than URLs on your own site. However, you can easily use Spurl with {% url %} if you need to. You just have to use the as keyword to put your reversed URL in a template variable, and then pass this to Spurl. As it’s a relative path (rather than a full URL) you should pass it using the path argument. For example, say you want to append some query parameters to a URL on your site:

{% url your_url_name as my_url %}
<a href="{% spurl path=my_url query="foo=bar&bar=baz" %}">Click here!</a>

There is another way to use Spurl with {% url %}, see Embedding template tags below.

Available arguments

Below is a full list of arguments that Spurl understands.

{% spurl base="http://example.com" scheme="ftp" %}

{% spurl base="http://example.com/some/path/" host="google.com" %}

{% spurl base="https://example.com" auth="user:pass" %}

{% spurl base="http://example.com/some/path/" path="/different/" %}

{% spurl base=STATIC_URL add_path="javascript" add_path="lib" add_path="jquery.js" %}

{% spurl base="http://example.com" fragment="myfragment" %}

{% spurl base="http://example.com/some/path/" port="8080" %}

{% spurl base="http://example.com/" query="foo=bar&bar=baz" %}

# views.py
def my_view(request):
    my_query_params = {'foo': 'bar', 'bar': 'baz'}
    return render(request, 'path/to/template.html', {'my_query_params': my_query_params})

<!-- template.html -->
{% spurl base="http://example.com/" query=my_query_params %}

{% spurl base="http://example.com/" query="foo={{ variable_name }}" %}

{% spurl base="http://example.com/?foo=bar" add_query="bar=baz" %}

{% spurl base="http://example.com/" add_query="foo=bar" add_query="bar=baz" %}

{% spurl base=request.get_full_path toggle_query="sort=ascending,descending" %}

# views.py

SORT_PARAM = 'sort'
ASCENDING = 'ascending'
DESCENDING = 'descending'

def my_view(request):

    if request.GET.get(SORT_PARAM, ASCENDING) == DESCENDING:
        object_list = MyModel.objects.order_by('-somefield')
    else:
        object_list = MyModel.objects.order_by('somefield')

    return render(request, 'path/to/template.html', {
        'object_list': object_list,
        'sort_params': {SORT_PARAM: (ASCENDING, DESCENDING)},
    })

<!-- template.html -->
<a href="{% spurl base=request.get_full_path toggle_query=sort_params %}">Reverse order</a>

{% spurl base="http://example.com/?foo=bar&bar=baz" remove_query_param="foo" %}

{% spurl base="http://example.com/?foo=bar&bar=baz" remove_query_param="foo" remove_query_param="bar" %}

{% spurl base="http://example.com/?foo=bar&bar=baz&foo=baz" remove_query_param="foo" remove_query_param="foo=baz" %}

{% spurl base="http://example.com/?foo=bar&bar=baz" remove_query_param="{{ variable_name }}" %}

{% spurl base="http://example.com/" secure="True" %}

Added bonus: _from parameters

As well as those listed above, Spurl provides a family of parameters for combining URLs. Given a base URL to start with, you can copy a component from another URL. These arguments expect to be passed a full URL (or anything that can be understood by URLObject.parse). This URL will be parsed, and then the component in question will be extracted and combined with the base URL.

Below is a full list of the available _from methods. They have identical semantics to their counterparts above (except they expect a full URL, not just a URL component).

• query_from

• add_query_from

• set_query_from

• scheme_from

• host_from

• path_from

• add_path_from

• fragment_from

• port_from

Example:

{% spurl base="http://example.com/foo/bar/?foo=bar path_from="http://another.com/something/?bar=foo" %}

This will return http://example.com/something/?foo=bar

Building a URL without displaying it

Like Django’s {% url %} tag, Spurl allows you to insert the generated URL into the template’s context for later use. Example:

{% spurl base="http://example.com" secure="True" as secure_url %}
<p>The secure version of the url is {{ secure_url }}</p>

Embedding template tags

As mentioned above, Spurl uses Django’s template system to individually parse any arguments which can be passed strings. This allows the use of syntax such as:

{% spurl base="http://example.com" add_query="foo={{ bar }}" %}

This works fine for variable and filters, but what if we want to use other template tags inside our Spurl tag? We can’t nest {% and %} tokens inside each other, because Django’s template parser would get very confused. Instead, we have to escape the inner set of tag markers with backslashes:

{% spurl base="http://example.com" add_query="next={\% url home %\}" %}

Note that any tags or filters loaded in your template are automatically available in the nested templates used to render each variable. This means we can do:

{% load url from future %}
{% spurl base="{\% url 'home' %\}" %}

Be careful with your quotation marks! If you use double-quotes to surround the nested template, you have to use single quotes inside it.

Warning! This functionality only exists to serve the most complex of use cases, and is extremely magical (and probably a bad idea). You may prefer to use:

{% url "home" as my_url %}
{% spurl base=my_url %}

How to run the tests

Spurl is tested with nose. Clone the repository, then run pip install -r requirements.txt to install nose and Django into your virtualenv. Then, simply type nosetests to find and run all the tests.

0.6.8 (2021-11-15)

• Fix toggle_query support when one word is a fragment of the other.

0.6.7 (2020-05-22)

• Fixed MANIFEST.in

0.6.6 (2019-03-29)

• Added support for an except clause to remove all but specifed query vars.

0.6.5 (2018-05-09)

• Added support for Django 2.x and dropped support for older and non-LTS version of Django.

0.6.4 (2015-12-26)

• Getting ready for Django 1.10 release.

• Dropped support for Django 1.3 and older.

0.6.3 (2015-12-17)

• Django 1.9 compatible (Albert Koch)

0.6.2 (2015-09-17)

• Add support for template variables to remove_query_param.

• Handle auth parameters to be able to add username:password to URLs.

0.6.1 (2015-07-14)

• Python 3 compatible!

0.6.0 (2012-02-23)

• Upgrade URLObject dependency to 2.0

0.5.0 (2011-12-14)

• Fix typos in changelog.

• Add family of arguments (_from) for combining URLs.

• Add toggle_query argument.

0.4.0 (2011-12-07)

• Upgrade URLObject dependency to 0.6.0

• Add remove_query_param argument.

• Add support for template tags embedded within argument values.

• Extensive refactoring.

0.3.0 (2011-08-18)

• Add set_query argument.

0.2.0 (2011-08-08)

• Add as argument to insert generated URL into template context.

0.1.0 (2011-07-29)

• Initial release.