Template Tags

To use any of the following tags, you must load the djpress_tags in your template file:

{% load djpress_tags %}

get_posts

Return all published posts as a queryset.

Returns: queryset of all published posts.

get_posts Examples

This is useful for building an index page with all posts:

{% get_posts as all_posts %}

{% for post in all_posts %}

<ul>
<li>{{ post.title }}</li>
</ul>

{% endfor %}

blog_title

Returns the blog title as configured in the settings with the BLOG_TITLE variable. If no blog title has been configured, this will return the default title: “My DJ Press Blog”.

Returns: the BLOG_TITLE value as a string.

blog_title Examples

This is useful for the HTML title tag:

<title>{% blog_title %}</title>

blog_title_link

This is used to return an HTML link to the index view of the blog.

Returns: an HTML link to the index view marked as safe.

blog_title_link Arguments

link_class (optional): CSS class(es) to apply to the link.

blog_title_link Examples

Just the tag with no argument:

{% blog_title_link %}

Outputs the following:

<a href="/">My DJ Press Blog</a>

The tag with a positional argument:

{% blog_title_link "mycssclass" %}

Outputs the following:

<a href="/" class="mycssclass">My DJ Press Blog</a>

The tag with a keyword argument:

{% blog_title_link link_class="mycssclass" %}

Outputs the following:

<a href="/" class="mycssclass">My DJ Press Blog</a>

The link_class argument can contain multiple CSS tags separated by spaces:

{% blog_title_link link_class="class1 class2" %}

Outputs the following:

<a href="/" class="class1 class2">My DJ Press Blog</a>

blog_page_title

Returns the title of the blog page, depending on the context of the page. A different title is returned for a category page, a blog page, author page, etc. This is useful to be used in the <title> tag of the template.

Returns: A string with no HTML formatting.

Arguments

pre_text (optional): text to be displayed before the page title
post_text (optional): text to be displayed after the page title

Examples

The tag with no options for a single blog page or post:

<title>{% blog_page_title %}</title>

Outputs the following:

<title>My blog post title</title>

The tag can be combined with the blog_title tag as well as using the post_text field.

<title>{% blog_page_title post_text=" | " %}{% blog_title %}</title>

Outputs the following:

<title>My blog post title | My DJ Press Blog</title>

Or you can get creative with an emoji:

<title>{% blog_page_title pre_text="🚀 " post_text=" | " %}{% blog_title %}</title>

Outputs the following:

<title>🚀 My blog post title | My DJ Press Blog</title>

Category pages will show the title of the category, and author pages will show the display name of the author.

get_pages

Get all published pages as an iterable queryset. This can be useful if you want to build your own menu or list of pages on the blog.

Returns: queryset of published pages that are sorted by the menu_order field, and then by the title field.

get_pages Examples

Get the pages and display as a list:

{% get_pages as pages %}
<ul>
  {% for page in pages %}
    <li>
      <a href="{% url 'djpress:single_post' page.slug %}>{{ page.title }}</a>
    </li>
  {% endfor %}
</ul>

Outputs the following:

<ul>
  <li>
    <a href="/about">About me</a>
  </li>
  <li>
    <a href="/contact">Contact me</a>
  </li>
</ul>

Also see blog_pages for a tag that produces similar output to the above but with just a single template tag.

get_categories

Get all categories as an iterable queryset. This can be useful if you want to build your own menu or list of categories on the blog.

Also see blog_categories for a tag that produces similar output to the below example, but with just a single template tag.

Return: queryset of categories that are sorted by the menu_order field, and then by the title field.

get_categories Examples

Get the categories and display as a list:

{% get_categories as categories %}
<ul>
  {% for category in categories %}
    <li>
      <a href="{% url 'djpress:category_posts' category.slug %}>{{ category.title }}</a>
    </li>
  {% endfor %}
</ul>

Outputs the following:

<ul>
  <li>
    <a href="/category/general">General</a>
  </li>
  <li>
    <a href="/category/news">News</a>
  </li>
</ul>

blog_categories

Get a list of all categories wrapped in HTML that can be configured with optional arguments.

Returns: all categories as HTML which has been marked as safe.

blog_categories Arguments

outer (optional): the outer tags that this should be wrapped in. Accepted options are “ul”, “div”, “span”. Default is: “ul”.
outer_class (optional): the CSS classes to apply to the outer tag. Default: “”.
link_class (optional): the CSS classes to apply to the link tag. Default: “”.

blog_categories Examples

Just the tag, with no arguments.

{% blog_categories %}

This will output the same HTML from the get_categories example.

<ul>
  <li>
    <a href="/category/general" title="View all posts in the General category">General</a>
  </li>
  <li>
    <a href="/category/news" title="View all posts in the General category">News</a>
  </li>
</ul>

Wrapped in a div tag with classes added, using positional arguments.

{% blog_categories "div" "class1" "class2" %}

Outputs a comma-separated list of categories, wrapped in a div tag.

<div class="class1">
  <a href="/category/general" title="View all posts in the General category" class="class2">General</a>,
  <a href="/category/news" title="View all posts in the General category" class="class2">News</a>
</div>

Wrapped in a span tag with classes added, using named arguments.

{% blog_categories outer="div" outer_class="class1" link_class="class2" %}

Outputs the same comma-separated list of categories, but wrapped in a span tag.

<span class="class1">
  <a href="/category/general" title="View all posts in the General category" class="class2">General</a>,
  <a href="/category/news" title="View all posts in the General category" class="class2">News</a>
</span>

blog_pages

Get all blog pages as a single-level list, wrapped in HTML that can be configured with optional arguments.

Returns: all blog pages as HTML marked as safe.

blog_pages Arguments

outer (optional): the outer tags that this should be wrapped in. Accepted options are “ul”, “div”, “span”. Default is: “ul”.
outer_class (optional): the CSS classes to apply to the outer tag. Default: “”.
link_class (optional): the CSS classes to apply to the link tag. Default: “”.

blog_pages Examples

Just the tag, with no arguments.

{% blog_pages %}

This will output the same HTML from the get_pages example.

<ul>
  <li>
    <a href="/about">About me</a>
  </li>
  <li>
    <a href="/contact">Contact me</a>
  </li>
</ul>

Wrapped in a div tag with classes added, using positional arguments.

{% blog_pages "div" "class1" "class2" %}

Outputs a comma-separated list of pages, wrapped in a div tag.

<div class="class1">
  <a href="/about" class="class2">About me</a>,
  <a href="/contact" class="class2">Contact me</a>
</div>

Wrapped in a span tag with classes added, using named arguments.

{% blog_pages outer="div" outer_class="class1" link_class="class2" %}

Outputs the same comma-separated list of pages, but wrapped in a span tag.

<span class="class1">
  <a href="/about" class="class2">About me</a>,
  <a href="/contact" class="class2">Contact me</a>
</span>

blog_pages_list

Get all published blog pages and output as a nested list to support parent pages.

Return: HTML which has been marked as safe.

blog_pages_list Arguments

ul_outer_class (optional): The CSS class(es) for the outer unordered list.
li_class (optional): The CSS class(es) for the list item tags
a_class (optional): The CSS class(es) for the anchor tags.
ul_child_class (optional): The CSS class(es) for the nested unordered lists.

blog_pages_list Examples

Just the tag, with no arguments.

{% blog_pages %}

This will output the following HTML:

<ul>
  <li>
    <a href="/about">About me</a>
    <ul>
      <li>
        <a href="/about/hobbies">Hobbies</a>
      </li>
      <li>
        <a href="/about/resume">My Resume</a>
      </li>
    </ul>
  </li>
  <li>
    <a href="/contact">Contact me</a>
  </li>
</ul>

Or arguments can be used to build a Bootstrap-like navbar menu.

{% blog_pages ul_outer_class="navbar-nav" li_class="nav-item" a_class="nav-link" ul_child_class="dropdown-menu" %}

This will output the following HTML:

<ul class="navbar-nav">
  <li class="nav-item">
    <a href="/about" title="View the About me page" class="nav-link">About me</a>
    <ul>
      <li class="nav-item">
        <a href="/about/hobbies" title="View the Hobbies page" class="nav-link">Hobbies</a>
      </li>
      <li class="nav-item">
        <a href="/about/resume" title="View the My Resume page" class="nav-link">My Resume</a>
      </li>
    </ul>
  </li>
  <li class="nav-item">
    <a href="/contact" title="View the Contact me page" class="nav-link">Contact me</a>
  </li>
</ul>

have_posts

Get a list of posts from the current context. This always returns a list, even if the context only contains a single post or page.

This is useful if you want to use a single template to show either a single post or a collection of posts.

Returns: list containing a single Post object, a Page object of posts, or an empty list.

have_posts Examples

The following code will work with a single post or page view, or a page with multiple posts:

{% have_posts as posts %}

{% for post in posts %}
    <h2>{{ post.title }}</h2>
    <p>{{ post.excerpt }}</p>
{% endfor %}

get_post_title

Returns the title of the current post as a plain string.

Returns: A string containing the post title or empty if there’s no post in the context.

get_post_title Examples

<h1>{% get_post_title %}</h1>

Outputs:

<h1>My Post Title</h1>

post_wrap

This is a wrapper tag that is used to add a semantic HTML wrapper tags around a post. By default this will use an <article> tag and will add the necessary microformat tags if microformats are enabled (these are enabled by default.)

Returns: HTML marked as safe.

post_wrap Arguments

Note - keyword arguments are recommended but not required.

tag (optional): The HTML tag to wrap the content in, default is <article>.
class (optional): CSS class(es) to apply to the tag, default is blank.

post_wrap Usage

Basic wrapper with no additional arguments and with microformats enabled.

{% post_wrap %}
<h2>Post Title</h2>
<p>This is my post content</p>
{% end_post_wrap %}

Outputs:

<article class="h-entry">
<h2>Post Title</h2>
<p>This is my post content</p>
</article>

Wrapper with specific HTML tag, a CSS class, and with microformats enabled.

{% post_wrap tag="div" class="blogpost" %}
<h2>Post Title</h2>
<p>This is my post content</p>
{% end_post_wrap %}

Outputs:

<div class="h-entry blogpost">
<h2>Post Title</h2>
<p>This is my post content</p>
</div>

post_title

Returns the title of the current post as a link if it’s part of a collection, or just the title if it’s single post.

The force_link argument can be used to always return the link, regardless if it’s part of a collection or not.

Returns: A string containing just the post title, or HTML text that has been marked as safe.

post_title Arguments

Note - these are keyword-only arguments.

outer_tag (optional): The outer HTML tag to wrap the title in.
link_class (optional): CSS class(es) to apply to the link.
force_link (optional, boolean): Always displays a link when true.

post_title Examples

{% post_title %}

If a single post, this outputs:

My Post Title

Or, if part of a collection of posts:

<a href="/my-post/">My Post Title</a>

With the link_class argument:

{% post_title link_class="post-title-link" %}

Outputs:

<a href="/my-post/" class="post-title-link">My Post Title</a>

Or, to force the link, even when just a single post is displayed:

{% post_title force_link=True %}

Outputs:

<a href="/my-post/">My Post Title</a>

To wrap the title in an HTML tag, use the outer_tag attribute. If microformats are enabled (these are enabled by default), then a class is added to the outer tag. The outer tag must be one of the following types: “h1”, “h2”, “h3”, “h4”, “h5”, “h6”, “p”, “div”, “span”. If anything else is used, or if the outer_tag attribute is ommitted, then no outer tag is added.

{% post_title outer_tag="h2" %}

Outputs:

<h2 class="p-name"><a href="/my-post/">My Post Title</a></h2>

get_post_author

Returns the display name of the post’s author.

Returns: String containing the author’s display name.

get_post_author Examples

<p>Written by {% get_post_author %}</p>

Outputs:

<p>Written by Sam Doe</p>

post_author

Get the author’s display name, wrapped in a span tag, with a link to their author page.

Returns: HTML text containing the author’s name, marked as safe.

post_author Arguments

link_class (optional): CSS class(es) to apply to the link.

post_author Examples

<p>By {% post_author %}</p>

Outputs:

<p>By <a href="/post-author/" title="View all posts by Post Author"><span rel="author">Post Author</span></a></p>

With the link_class argument:

<p>By {% post_author link_class="author-link" %}</p>

Outputs:

<p>By <a href="/post-author/" title="View all posts by Post Author" class="author-link"><span rel="author">Post Author</span></a></p>

post_category_link

Get a link to a post’s category.

Returns: HTML text containing a link to the category.

post_category_link Arguments

category: The Category object to link to.
link_class (optional): CSS class(es) to apply to the link.

post_category_link Examples

{% for category in post.categories.all %}
    {% post_category_link category link_class="category-link" %}
{% endfor %}

get_post_date

Get the date of the current post.

Returns: A string containing the post’s date formatted as “MMM D, YYYY”.

get_post_date Examples

<p>Published on {% get_post_date %}</p>

Outputs:

<p>Published on Jun 5, 2024</p>

post_date

Returns the post’s date as a set of links to date-based archives, if enabled.

Returns: An HTML string containing links to date-based archives, or just the formatted date if date archives are disabled.

post_date Arguments

link_class (optional): CSS class(es) to apply to the links.

post_date Examples

<p>Posted on {% post_date link_class="date-link" %}</p>

Outputs:

<p>Posted on <a href="/archives/2024/06/" title="View all posts in Jun 2024">Jun</a> <a href="/archives/2024/06/05/" title="View all posts on 5 Jun 2024">5</a>, <a href="/archives/2024/" title="View all posts in 2024">2024</a>, 11:06 AM.</p>

post_content

Returns the content of the current post, either full or truncated with a “read more” link. If the post is on a post detail page, the full content is displayed. If the post is on any other type of page, just the truncated content is displayed.

Returns: HTML text containing the post content, or truncated with a “read more” link. The HTML is marked as safe.

post_content Arguments

Note - these are keyword-only arguments.

outer_tag (optional):
read_more_link_class (optional): CSS class(es) to apply to the “read more” link.
read_more_text (optional): Custom text for the “read more” link.

post_content Examples

{% post_content %}

If the post is on a detail page, this will output the full content. But if the post is part of a collection of posts, it will only display truncated content with a read more link:

<p>This is the start of the post content.</p>
<p><a href="/post-title/">Read more...</a></p>

With the optional arguments to control the read more function:

{% post_content read_more_link_class="read-more" read_more_text="Continue reading..." %}

Outputs:

<p>This is the start of the post content.</p>
<p><a href="/post-title/" class="read-more">Continue reading...</a></p>

To wrap the content in an HTML tag, use the outer_tag attribute. Note that if microformats are enabled (these are enabled by default), then e-content will be added to the outer tag class.

{% post_content outer_tag="section" %}

Outputs:

<section class="e-content">
<p>This is the start of the post content.</p>
<p><a href="/post-title/" class="read-more">Continue reading...</a></p>
</section>

category_title

Get the title of the current category, optionally wrapped in an HTML tag.

Returns: A string or HTML-wrapped text containing the category title. The HTML text is marked as safe.

category_title Arguments

outer (optional): The HTML tag to wrap the title in.
outer_class (optional): CSS class(es) to apply to the outer tag.
pre_text (optional): Text to prepend to the category title.
post_text (optional): Text to append to the category title.

category_title Examples

The following will just return the category title as a string:

{% category_title %}

The following will return HTML text:

{% category_title outer="h1" outer_class="category-title" pre_text="Category: " %}

Outputs:

<h1 class="category-title">Category: General</h1>

Or with all arguments:

{% category_title outer="h1" outer_class="category-title" pre_text="Posts in the '" post_text="' category" %}

Outputs:

<h1 class="category-title">Posts in the 'General' category</h1>

author_name

Get the author’s display name, optionally wrapped in an HTML tag.

Returns: A string or HTML-wrapped text containing the author’s display name. The HTML text is marked as safe.

author_name Arguments

outer (optional): The HTML tag to wrap the name in.
outer_class (optional): CSS class(es) to apply to the outer tag.
pre_text (optional): Text to prepend to the author name.
post_text (optional): Text to append to the author name.

author_name Examples

The following will just return the author’s display name

{% author_name %}

The following will return HTML text:

{% author_name outer="h1" outer_class="author-title" pre_text="Author: " %}

Outputs:

<h1 class="author-title">Author: Sam Jones</h1>

Or with all arguments:

{% author_name outer="h1" outer_class="author-title" pre_text="Posts that '" post_text="' wrote" %}

Outputs:

<h1 class="author-title">Posts that 'Sam Jones' wrote</h1>

post_categories

Returns a list of links to the categories of the current post.

Returns: An HTML string containing a list of category links for the current post.

post_categories Arguments

outer (optional): The HTML tag to use for the outer container. Default is “ul”.
outer_class (optional): CSS class(es) to apply to the outer container.
link_class (optional): CSS class(es) to apply to each category link.

post_categories Examples

Just the tag with no arguments:

{% post_categories %}

Outputs:

<ul>
  <li>
    <a href="/general/" title="View all posts in the General category">General</a>
  </li>
</ul>

The tag with all options provided as arguments and using a div for the outer tag:

{% post_categories outer="div" outer_class="post-categories" link_class="category-link" %}

Outputs the following HTML:

<div class="post-categories">
  <a href="/general/" title="View all posts in the General category" class="category-link">General</a>
</div>

The tag with a span for the outer tag:

{% post_categories outer="span" %}

Outputs the following HTML:

<span>
  <a href="/general/" title="View all posts in the General category">General</a>
</span>

pagination_links

This is used to create basic pagination links in the form of “Page x of y” with left and right angled quotes on either side to allow moving backwards and forwards through the pages.

This tag will be ignored if the current view is not a paginated object.

For more control over pagination links, you can create your own pagination controls with the following tags:

is_paginated
get_pagination_range
get_pagination_range
get_pagination_current_page

Returns: An HTML string containing pagination links.

pagination_links Examples

If used on the first page of three:

{% pagination_links %}

Outputs:

<div class="pagination">
  <span class="current">
    Page 1 of 3
  </span>
  <span class="next">
    <a href="?page=2">next</a> <a href="?page=3">last »</a>
  </span>
</div>

If used on the second page of three:

{% pagination_links %}

Outputs:

<div class="pagination">
  <span class="previous">
    <a href="?page=1">« first</a> <a href="?page=1">previous</a>
  </span>
  <span class="current">Page 2 of 3</span>
  <span class="next">
    <a href="?page=3">next</a> <a href="?page=3">last »</a>
  </span>
</div>

If used on the third page of three:

{% pagination_links %}

Outputs:

<div class="pagination">
  <span class="previous">
    <a href="?page=1">« first</a> <a href="?page=2">previous</a>
  </span>
  <span class="current">Page 3 of 3</span>
</div>

If used on paginated page with only one page:

{% pagination_links %}

Outputs:

<div class="pagination">
  <span class="current">Page 1 of 1</span>
</div>

is_paginated

Returns whether the current posts are paginated.

Returns: A boolean indicating if the posts are paginated.

is_paginated Examples

{% if is_paginated %}
    <!-- Show pagination controls -->
{% endif %}

get_pagination_range

Returns the range of pagination pages.

Returns: A range object representing the pagination pages.

get_pagination_range Examples

{% for page_num in get_pagination_range %}
    <a href="?page={{ page_num }}">{{ page_num }}</a>
{% endfor %}

get_pagination_current_page

Returns the current page number.

Returns: An integer representing the current page number.

get_pagination_current_page Examples

<p>You are on page {% get_pagination_current_page %}</p>

page_link

Returns a link to a specific page.

Returns: An HTML string containing a link to the specified page.

page_linkArguments

page_slug: The slug of the page to link to.
outer (optional): The HTML tag to wrap the link in. Default is “div”.
outer_class (optional): CSS class(es) to apply to the outer tag.
link_class (optional): CSS class(es) to apply to the link.

page_link Examples

{% page_link "about" %}
{% page_link "contact" outer="li" outer_class="menu-item" link_class="page-link" %}

rss_url

Returns the URL of the RSS feed.

Returns: A plain text representation of the URL.

get_rss_url Examples

<a href="{% rss_url %}">RSS Feed</a>

<link rel="alternate" type="application/rss+xml" title="Latest Posts" href="{% rss_url %}">

rss_link

Returns the HTML link tag with the correct attributes for the RSS URL. If RSS is disabled, this will return nothing.

Returns: HTML marked as safe.

rss_link Examples

{% rss_link %}

<link rel="alternate" type="application/rss+xml" title="Latest Posts" href="/rss/">