How to use routablepageurl tag in wagtail HTML template - wagtail

Question

I reviewed official docs for several times and still quite confusing in regards to how to use routablepageurl tag exactly.
below are from official doc
wagtail.contrib.routable_page.templatetags.wagtailroutablepage_tags.routablepageurl(context,page, url_name, *args, **kwargs)
routablepageurl is similar to pageurl, but works with pages using RoutablePageMixin. It behaves like a hybrid between the built-in reverse, and pageurl from Wagtail.
page is the RoutablePage that URLs will be generated from.
url_name is a URL name defined in page.subpage_urls.
Positional arguments and keyword arguments should be passed as normal positional arguments and keyword arguments.
Q1: How the required parameter context is provided?
Q2: What exactly page and url_name stands for ? I did not see an attribute (subpage_url) in page model. Official doc explanation is quite confusing.
Q3: Why sometimes category.slug is used as a argument for routablepageurl template tag as show in this blog post.
{{ category.name }}

Answer 1

Overview
The docs section for the routablepageurl template tag is quite short and it can come across as a bit confusing due to it being quite densely packed with references to concepts in Wagtail and Django.
Let's unpack the line:
routablepageurl is similar to pageurl, but works with pages using RoutablePageMixin. It behaves like a hybrid between the built-in reverse, and pageurl from Wagtail.
Firstly, this is a custom template tag which is a function that takes some known arguments/params in a specific order that can be made available to template tags. The important thing to note here is that context is something that gets passed into the template tag function call but you do not have to pass it in explicitly when using the template tag.
Understanding this requires a bit of an understanding of how Django's URL system works and it would be good to read through the Django docs on this topic https://docs.djangoproject.com/en/3.2/topics/http/urls/
pageurl here is a reference to a different template tag that has similar behaviour, you can view the docs for the pageurl template tag.
routablePageMixin is a Page mixin that allows the use of multiple sub-page routes to be made available, each with a name with a decorator like #route(r'^past/$').
Behaves like reverse is a reference to the django.urls.reverse function which takes a URL name and will return the URL. Reverse provides a way not only to get a URL based on a name but to pass arguments in that will build up the full URL based on those arguments.
In all of these references, the concept of a name is also a Django concept where when you declare URL patterns (e.g. all 'blog/DD-MM-YYYY' pages) with a name to reference them elsewhere.
Specific Answers
Q1: How the required parameter context is provided?
context is provided by default for all template tag function calls.
Q2: What exactly do page and url_name stand for?
page is a modal instance, this would be the page that is using RoutablePageMixin.
url_name is the name of the URL pattern as defined in your page, this can come across a bit unclear but it is the function name that is used to create the sub routes, in the code example below (from the docs), the url name will be current_events.
class EventIndexPage(RoutablePageMixin, Page):
#...
#route(r'^$') # will override the default Page serving mechanism
def current_events(self, request):
"""
Q3: Why can category.slug be used as an argument for this template tag
This is an example of passing extra params/arguments to the template tag, these in turn get passed to the URL resolver system to build up a URL.
For example, in the code snippet below (from the blog post) if the category.slug was 'coffee shops' (a category), this is what will happen:
Given the tag usage {{ category.name }}
The blog_page will be a variable that is the current page instance
The "post_by_category" says to find the URL sub-route with the name (method name) of post_by_category.
Any other params after that will be used to build the URL based on the URL pattern, let's say that category.slug is 'coffee-shops' (the slug being a URL valid string) of the category 'Coffee Shops'.
In the code below the pattern is r'^category/(?P<category>[-\w]+)/$', where the <category> (angled brackets) is a variable usage, the URL resolver will inject the slug and build a URL path of 'category/coffee-shops'
class BlogPage(RoutablePageMixin, Page):
description = models.CharField(max_length=255, blank=True,)
#...
#route(r'^category/(?P<category>[-\w]+)/$')
def post_by_category(self, request, category, *args, **kwargs):
self.search_type = 'category'
It is important to understand that ANY key word arguments or arguments can be passed in to the template tag and these values will in turn be passed to the URL resolver which reads the URL pattern syntax and attempts to build a URL based on how those arguments are used in the pattern.