Heads up! To view this whole video, sign in with your Courses account or enroll in your free 7-day trial. Sign In Enroll
Preview
Start a free Courses trial
to watch this video
Write a more complicated template tag; one that returns a dictionary and has a more complex implementation.
Django Documentation Simple Tag vs. Inclusion Tag
register.inclusion_tag("tag_template.html")(tag_name) or @register.inclusion_tag("tag_template.html") - Registers an inclusion tag. Inclusion tags render a template into wherever they're used.
You're doing great so far.
0:00
Now you're ready to write a template tag,
that can serve as a navigation menu for
0:02
your site.
0:07
Basically, we want to add a menu on
the left that lists all the courses,
0:08
and links to the course details page for
each one.
0:13
It'll show up on each page, and
make it easier to move around the site.
0:17
So let's get started.
0:22
Let's open up course extras.py again.
0:23
We need to create a new function,
0:27
so define nav courses list.
0:32
Again, this function isn't
going to take any arguments.
0:37
We just want to get all of the courses and
return them, so
0:41
this function is pretty straight forward.
0:44
Let's add a doc string that explains that.
0:47
So, Returns dictionary of courses
to display as navigation pane.
0:49
We've already imported the course model,
because we used it in our last template
0:59
tag, so
now we just need to write our query.
1:03
So courses = Course.objects.all, and
1:06
then return dictionary,
like we said we would, courses.
1:11
So we're assigning the variable courses
1:18
to the result of the query
course.objects.all.
1:21
Which does exactly what it says.
1:25
It gets all of the course objects.
1:28
We then return those
courses in a dictionary.
1:30
Before we're finished with course
extras.py, we need to register this tag.
1:33
The type of tag we're writing here,
is called an inclusion tag.
1:38
And it's different than a simple tag,
1:42
because it returns its data as a whole
other template, not just a string.
1:45
That explains its name,
1:50
you're including another template in
the template, in which you use this tag.
1:52
Registering our inclusion tag is
therefore a little bit different,
1:58
than registering the simple
tag we did before.
2:02
So we would type register.inclusion_tag,
and then we pass in
2:06
the path to the template file that
we haven't actually created yet.
2:11
But this is the template that we're going
to include in another template whenever we
2:18
use this tag.
2:22
And then we also have to pass
the name of the function.
2:23
We're using the same register variable,
2:30
which you remember is where we are keeping
the call to the template.library class.
2:33
But instead of calling the simple
tag method on that class,
2:38
we're calling the inclusion tag method.
2:41
We pass it the path to the template
this tag gets included in,
2:44
as well as the name of the tag.
2:48
But that's a lot of typing.
2:50
And there's a shorter way
to register inclusion tags.
2:52
Just like with our simple tag,
we can use a decorator.
2:55
So let's delete that other
registration function and
2:58
replace it with this decorator.
3:02
Register.inclusion_tag, and
3:03
then we just pass it that path,
course_nav.html.
3:07
Now we need to code this template,
this course_nav.html.
3:15
Remember since this is an inclusion tag,
3:19
we're creating a template that
can be dropped in anywhere.
3:21
So over here in courses,
create a new file called course_nav.html.
3:25
This next part should look familiar.
3:32
Since our function gets all of our courses
for us, we can just open up a for loop and
3:35
do for course in courses, and
open up a div, and use the course title.
3:40
Then we just need to close our for loop.
3:50
Now that's a great start, but since we're
using this template to navigate among
3:54
the different courses in our site,
we should probably add some links.
3:58
So right before course title,
we'll open up an anchor tag.
4:03
And this is a great opportunity for
us to review the URL tag and how it works.
4:06
So we pass in the primary key,
4:12
and we move the end of the anchor tag,
to after our course title.
4:20
Now, let's review the URL tag.
4:26
We include the name of the URL,
as the first argument to the URL tag.
4:28
That's the courses:detail part.
4:32
We included courses,
because we've name spaced our URLs and
4:36
detail because that's the name we gave
the URL we want to go in our urls.py file.
4:40
Go double check urls.py
to see what I mean.
4:46
Then we've passed in the primary key
PK that this specific URL needs.
4:50
We can't go to a details page, if we don't
know which course we need details on.
4:56
Now, so that we always have this
navigation section available to us,
5:01
let's drop it into our layout.html page.
5:05
We already have load
course_extras up here, so
5:09
now right inside our site-container,
5:14
we can create a new div and
just drop in nav_courses_list.
5:18
When we do our steps to start our server,
which include changing directories into
5:26
our learning site, and then running
python manage.py runserver on our port.
5:31
We can use the little i to
see our navigation pane.
5:39
Now, in the real world, you would probably
add some CSS to make this navigation pane
5:44
display across the top in
a more attractive way, or
5:49
along the left hand side.
5:52
But we've proved our concept here, and so
5:54
I'll leave it to you to experiment
with CSS in the ways that you want to.
5:56
Have fun.
6:00
I hope by this point you understand why
custom template tags are useful and
6:02
how to get started with them.
6:07
Maybe you're already thinking of
situations where writing your own template
6:09
tag, would make your own projects
better and more flexible.
6:13
But did you know you can
write your own filters too?
6:18
We'll do that in the next video,
so stay tuned.
6:22
You need to sign up for Treehouse in order to download course files.
Sign up