Template tags

django_hosts.templatetags.hosts.host_url(view_name, [view_args, view_kwargs, ]host_name[, host_args, host_kwargs, as_var, scheme])

Now if you want to actually refer to the full URLs in your templates you can use the included host_url template tag. So imagine having a host pattern of:

from django.conf import settings
from django_hosts import patterns, host

host_patterns = patterns('',
    host(r'admin', settings.ROOT_URLCONF, name='our-admin'),
)

and a ROOT_URLCONF of:

from django.conf.urls import patterns, url

urlpatterns = patterns('mysite.admin',
    url(r'^dashboard/$', 'dashboard', name='dashboard'),
)

then this example will create a link to the admin dashboard:

{% load hosts %}

<a href="{% host_url 'dashboard' host 'our-admin' %}">Admin dashboard</a>

which will be rendered as:

<a href="//admin/dashboard/">Admin dashboard</a>

Note

The double slash at the beginning of the href is an easy way to not have to worry about which scheme (http or https) is used. Your browser will automatically choose the currently used scheme. If you’re on https://mysite.com/ a link with an href of //mysite.com/about/ would actually point to https://mysite.com/about/.

For more information see the The protocol-relative URL article by Paul Irish or the appropriate section in RFC 3986.

Changed in version 0.5.

You can override the used default scheme with the HOST_SCHEME setting.

Changed in version 1.0.

You can override the individually used scheme with the scheme parameter.

Override the default url template tag

New in version 1.0.

In case you don’t like adding {% load hosts %} to each and every template that you reverse an URL in you can automatically override the url template tag that is built into Django by adding 'django_hosts.templatetags.hosts_override' to the TEMPLATES['OPTIONS']['builtins'] list.

It won’t hurt to have some {% load hosts %} in some templates and the host_url() template tag will also still work. But that will at least enable the use of templates in 3rd party apps, for example.

Fully qualified domain names (FQDN)

In case you want to append a default domain name to the domain part of the rendered URL you can simply set the PARENT_HOST, e.g:

PARENT_HOST = 'example.com'

This would render the link of the previous section as:

<a href="//admin.example.com/dashboard/">Admin dashboard</a>

Alternatively – in case you don’t want to append this parent domain to all URLs you can also spell out the domain in the host pattern:

from django.conf import settings
from django_hosts import patterns, host

host_patterns = patterns('',
    host(r'admin\.example\.com', settings.ROOT_URLCONF, name='admin'),
)

Host and URL pattern parameters

If your host pattern contains an parameter (or keyed parameter), like:

from django.conf import settings
from django_hosts import patterns, host

host_patterns = patterns('',
    host(r'www', settings.ROOT_URLCONF, name='homepage'),
    host(r'(\w+)', 'path.to.support_urls', name='wildcard'),
    host(r'(?P<username>\w+).users', 'path.to.user_urls', name='user-area'),
)

you can also easily pass parameters to the host_url() template tag:

{% load hosts %}

<a href="{% host_url 'user-dashboard' host 'user-area' username='johndoe' %}">John's dashboard</a>
<a href="{% host_url 'faq-index' host 'wildcard' 'help' %}">FAQ</a>

Which will be rendered (with a PARENT_HOST of 'example.com') as:

<a href="//johndoe.users.example.com/">John's dashboard</a>
<a href="//help.example.com/faq/">FAQ</a>

Changing the scheme individually

It’s not only possible to define the scheme in the hostconf but also on a case-by-case basis using the template tag:

{% load hosts %}

<a href="{% host_url 'user-dashboard' host 'user-area' username='johndoe' scheme 'https' %}">John's dashboard</a>
<a href="//help.example.com/faq/">FAQ</a>

Which will be rendered (with a PARENT_HOST of 'example.com' and a HOST_SCHEME setting defaulting to '//') as:

<a href="https://johndoe.users.example.com/">John's dashboard</a>
<a href="//help.example.com/faq/">FAQ</a>

Storing the url in a context variable

New in version 0.4.

If you’d like to retrieve a URL without displaying it, you can save the result of the template tag in a template variable and use it later on, e.g.:

{% load hosts %}

{% host_url 'homepage' as homepage_url %}
<a href="{{ homepage_url }}" title="Go back to {{ homepage_url }}">Home</a>