DIY Custom Tags

We've learned a lot about the built in tools that Django ships with, 0:01 but sometimes you need something even more custom. 0:05 Sometimes it's time to DIY your own template tag. 0:09 Just like you can create templates that you can include on the fly in 0:14 other templates, you can also write template tags 0:18 that you can plug in to templates that will render information. 0:22 For example, if you always wanted to display the newest items added to a store 0:26 or the top-rated game, you can write a custom tag that will dynamically 0:32 figure out what the newest or best item is and display that for you. 0:37 That's exactly what we're going to do in this video. 0:42 We're going to write a custom template tag that will always display the newest 0:46 course available at the top of the page, so people who come to our site frequently 0:51 can easily find courses they might not have seen before. 0:56 So let's get started. 1:00 Template tags are a little special in that they have to live in their own directory 1:03 called, templatetags. 1:07 So, we created a new directory in our courses app, called templatetags. 1:09 Don't forget that in order for Python to recognize template 1:14 tags as a Python package, we had to add an empty init.py file. 1:18 So we created a new file and saved it as __init__.py. 1:23 Then we created a second file in which we will write our custom tags and filters. 1:29 We called that course_extras.py, since these are the extra tags for 1:36 the course's app. 1:41 Now we're ready to get started. 1:42 Since this is a template tag, we need to import the template module from Django. 1:44 That's because the template module contains the function we need to register 1:51 our template. 1:55 When you register your template tag, what you're doing is making it available to 1:57 Django's template language so you can use it. 2:01 So let's go ahead and create a variable called register, 2:04 that calls the class we'll need later, and save ourselves some typing. 2:07 So register equals template.library. 2:11 This is basic Python code, but let's review what we just did. 2:18 We instantiated an instance of the library class located in the template library and 2:22 named that instance register. 2:28 Okay, now we're ready to start writing our template tag. 2:30 A template tag is just a function that does a specific thing and 2:34 you can plug it into your template using regular template syntax. 2:38 Like all functions, it needs to be defined. 2:42 And then we can add a nice doc string to let us know what this function does. 2:47 So it gets the most recent course that was added to the library. 2:53 Now, we need to create our query. 2:59 We know we want to return the latest course from the course model so 3:01 we can use a method called latest to get at that like so. 3:06 We have to pass in the field in the model that we want latest to pay attention to. 3:15 In this case, we're concerned with the creation date, so 3:21 we used the created_at field to get the latest course. 3:25 Now, do you see what I see? 3:29 We're using the course model, but we haven't imported it yet. 3:31 So let's add that to our import statement. 3:34 From courses.models import Course. 3:38 The last thing we need to do is register our tag. 3:44 There are a few different kinds of custom template tags, and 3:47 we'll go over those later. 3:51 This one is a simple tag, which returns its result as a string. 3:53 There are two different ways to register your tag. 3:57 There's the long way. 4:01 Register.simple_tag and then you feed in 4:03 the name of your tag, and that works fine, we just add it right below our function. 4:08 But there's a shorter and slightly cleaner way to do this. 4:13 We can use a decorator right before our function and 4:18 then we don't have to feed in anything. 4:24 Now in order for our template tag to show up, 4:26 we have to let the template we're dropping it into know that it exists. 4:29 Just like you have to use the extends tag to say this template will extend that 4:33 other template, and you use the load tag to say I want to load the static files. 4:38 You can also use the load tag, to load your template tags into a template, and 4:45 make them more accessible to that template. 4:50 We want this tag to appear in our layout.html template, 4:53 so let's open that up. 4:56 We add the load tag to the top of the page. 4:59 Load course_extras, 5:04 and now we can use our template tag to get the most recent course. 5:07 So right here before the block content, we add a p tag and it can say, 5:12 don't miss our latest course and then we just drop in our tag. 5:16 Now let's start our server. 5:23 So we can change directories into our learning site and 5:27 then run python manage.py runserver. 5:31 And now here at the top we can see don't miss our latest course, Python Testing. 5:39 You might be wondering why we created this as a tag instead of just 5:45 getting this information in the view and passing it in through the template. 5:50 And we could have done that. 5:54 But using the template tag for this makes the code more reusable. 5:56 Once we've written that tag, 6:01 we don't have to perform the work of calling the function, 6:03 returning the value, and adding the template variable where we want it. 6:06 We just drop the tag in and we're done, easy huh? 6:11 You can also create template tags that take context, for example, that take 6:17 a string and use it to look something up or that transform it in some way. 6:21 We'll get to that in a later video. 6:26