#第 12 篇:解鎖部落格側欄,GoGoGo!
作者:HelloGitHub-追夢人物
文中涉及的示例程式碼,已同步更新到 HelloGitHub-Team 倉庫
我們的部落格側邊欄有四項內容:最新文章、歸檔、分類和標籤雲。這些內容相對比較固定和獨立,且在各個頁面都會顯示,如果像文章列表或者文章詳情一樣,從檢視函式中獲取這些資料然後傳遞給模板,則每個頁面對應的檢視函式裡都要寫一段獲取這些內容的程式碼,這會導致很多重複程式碼。更好的解決方案是直接在模板中獲取,為此,我們使用 django 的一個新技術:自定義模板標籤來完成任務。
使用模板標籤的解決思路
我們前面已經接觸過一些 django 內建的模板標籤,比如比較簡單的 {% static %}
{% for %} {% endfor%}
標籤。這裡我們希望自己定義一個模板標籤,例如名為 show_recent_posts
的模板標籤,它可以這樣工作:我們只要在模板中寫入 {% show_recent_posts %}
,那麼模板中就會渲染一個最新文章列表頁面,這和我們在編寫部落格首頁面檢視函式是類似的。首頁檢視函式中從資料庫獲取文章列表並儲存到 post_list
變數,然後把這個 post_list
變數傳給模板,模板使用 for 模板標籤迴圈這個文章列表變數,從而展示一篇篇文章。這裡唯一的不同是我們從資料庫獲取文章列表的操作不是在檢視函式中進行,而是在模板中通過自定義的 {% show_recent_posts %}
以上就是解決思路,但模板標籤不是隨意寫的,必須遵循 django 的規範才能在 django 的模板系統中使用,下面就依照這些規範來實現我們的需求。
模板標籤目錄結構
首先在我們的 blog 應用下建立一個 templatetags 資料夾。然後在這個資料夾下建立一個 __init__.py 檔案,使這個資料夾成為一個 Python 包,之後在 templatetags 目錄下建立一個 blog_extras.py 檔案,這個檔案存放自定義的模板標籤程式碼。
此時你的目錄結構應該是這樣的:
blog\ __init__.py admin.py apps.py migrations\ __init__.py models.py static\ templatetags\ __init__.py blog_extras.py tests.py views.py
編寫模板標籤程式碼
接下來就是編寫各個模板標籤的程式碼了,自定義模板標籤程式碼寫在 blog_extras.py 檔案中。其實模板標籤本質上就是一個 Python 函式,因此按照 Python 函式的思路來編寫模板標籤的程式碼就可以了,並沒有任何新奇的東西或者需要新學習的知識在裡面。
最新文章模板標籤
開啟 blog_extras.py 檔案,開始寫我們的最新文章模板標籤。
from django import template
from ..models import Post, Category, Tag
register = template.Library()
@register.inclusion_tag('blog/inclusions/_recent_posts.html', takes_context=True)
def show_recent_posts(context, num=5):
return {
'recent_post_list': Post.objects.all().order_by('-created_time')[:num],
}
這裡我們首先匯入 template 這個模組,然後例項化了一個 template.Library
類,並將函式 show_recent_posts
裝飾為 register.inclusion_tag
,這樣就告訴 django,這個函式是我們自定義的一個型別為 inclusion_tag 的模板標籤。
inclusion_tag 模板標籤和檢視函式的功能類似,它返回一個字典值,字典中的值將作為模板變數,傳入由 inclusion_tag 裝飾器第一個引數指定的模板。當我們在模板中通過 {% show_recent_posts %}
使用自己定義的模板標籤時,django 會將指定模板的內容使用模板標籤返回的模板變數渲染後替換。
inclusion_tag 裝飾器的引數 takes_context
設定為 True
時將告訴 django,在渲染 _recent_posts.html 模板時,不僅傳入show_recent_posts
返回的模板變數,同時會傳入父模板(即使用 {% show_recent_posts %}
模板標籤的模板)上下文(可以簡單理解為渲染父模板的檢視函式傳入父模板的模板變數以及 django 自己傳入的模板變數)。當然這裡並沒有用到這個上下文,這裡只是做個簡單演示,如果需要用到,就可以在模板標籤函式的定義中使用 context 變數引用這個上下文。
接下來就是定義模板 _recent_posts.html 的內容。在 templates\blogs 目錄下建立一個 inclusions 資料夾,然後建立一個 _recent_posts.html 檔案,內容如下:
<div class="widget widget-recent-posts">
<h3 class="widget-title">最新文章</h3>
<ul>
{% for post in recent_post_list %}
<li>
<a href="{{ post.get_absolute_url }}">{{ post.title }}</a>
</li>
{% empty %}
暫無文章!
{% endfor %}
</ul>
</div>
很簡單,迴圈由 show_recent_posts
傳遞的模板變數 recent_post_list
即可,和 index.html 中迴圈顯示文章列表是一樣的。
歸檔模板標籤
和最新文章模板標籤一樣,先寫好函式,然後將函式註冊為模板標籤即可。
@register.inclusion_tag('blog/inclusions/_archives.html', takes_context=True)
def show_archives(context):
return {
'date_list': Post.objects.dates('created_time', 'month', order='DESC'),
}
這裡 Post.objects.dates
方法會返回一個列表,列表中的元素為每一篇文章(Post)的建立時間(已去重),且是 Python 的 date
物件,精確到月份,降序排列。接受的三個引數值表明了這些含義,一個是 created_time
,即 Post
的建立時間,month
是精度,order='DESC'
表明降序排列(即離當前越近的時間越排在前面)。例如我們寫了 3 篇文章,分別釋出於 2017 年 2 月 21 日、2017 年 3 月 25 日、2017 年 3 月 28 日,那麼 dates
函式將返回 2017 年 3 月 和 2017 年 2 月這樣一個時間列表,且降序排列,從而幫助我們實現按月歸檔的目的。
然後是渲染的模板 _archives.html 的內容:
<div class="widget widget-archives">
<h3 class="widget-title">歸檔</h3>
<ul>
{% for date in date_list %}
<li>
<a href="#">{{ date.year }} 年 {{ date.month }} 月</a>
</li>
{% empty %}
暫無歸檔!
{% endfor %}
</ul>
</div>
由於 date_list
中的每個元素都是 Python 的 date
物件,所以可以引用 year
和 month
屬性來獲取年份和月份。
分類模板標籤
過程還是一樣,先寫好函式,然後將函式註冊為模板標籤。注意分類模板標籤函式中使用到了 Category
類,其定義在 blog.models.py 檔案中,使用前記得先匯入它,否則會報錯。
@register.inclusion_tag('blog/inclusions/_categories.html', takes_context=True)
def show_categories(context):
return {
'category_list': Category.objects.all(),
}
_categories.html 的內容:
<div class="widget widget-category">
<h3 class="widget-title">分類</h3>
<ul>
{% for category in category_list %}
<li>
<a href="#">{{ category.name }} <span class="post-count">(13)</span></a>
</li>
{% empty %}
暫無分類!
{% endfor %}
</ul>
</div>
<span class="post-count">(13)</span>
顯示的是該分類下的文章數目,這個特性會在接下來的教程中講解如何實現,目前暫時用佔位資料代替吧。
標籤雲模板標籤
標籤和分類其實是很類似的,模板標籤:
@register.inclusion_tag('blog/inclusions/_tags.html', takes_context=True)
def show_tags(context):
return {
'tag_list': Tag.objects.all(),
}
_tags.html:
<div class="widget widget-tag-cloud">
<h3 class="widget-title">標籤雲</h3>
<ul>
{% for tag in tag_list %}
<li>
<a href="#">{{ tag.name }}</a>
</li>
{% empty %}
暫無標籤!
{% endfor %}
</ul>
</div>
使用自定義的模板標籤
開啟 base.html,為了使用剛才定義的模板標籤,我們首先需要在模板中匯入存放這些模板標籤的模組,這裡是 blog_extras.py 模組。當時我們為了使用 static 模板標籤時曾經匯入過 {% load static %}
,這次在 {% load static %}
下再匯入 blog_extras:
templates/base.html
{% load static %}
{% load blog_extras %}
<!DOCTYPE html>
<html>
...
</html>
然後找到側邊欄各項,將他們都替換成對應的模板標籤:
templates/base.html
<aside class="col-md-4">
{% block toc %}
{% endblock toc %}
{% show_recent_posts %}
{% show_archives %}
{% show_categories %}
{% show_tags %}
<div class="rss">
<a href=""><span class="ion-social-rss-outline"></span> RSS 訂閱</a>
</div>
</aside>
此前側邊欄中各個功能塊都替換成了模板標籤,其實實際內容還是一樣的,只是我們將其挪到了模組化的模板中,並有這些自定義的模板標籤負責渲染這些內容。
此外我們定義的 show_recent_posts
標籤可以接收引數,預設為 5,即顯示 5 篇文章,如果要控制其顯示 10 篇文章,可以使用 {% show_recent_posts 10 %}
這種方式傳入引數。
現在執行開發伺服器,可以看到側邊欄顯示的資料已經不再是之前的佔位資料,而是我們儲存在資料庫中的資料了。
注意:
如果你是在開發伺服器啟動的過程中編寫的模板標籤程式碼,那麼一定要重啟一下開發伺服器才能匯入 blog_extras,否則會報
TemplateSyntaxError at /
'blog_extras' is not a registered tag library. Must be one of:
類似這樣的錯誤。
注意:如果你按照教程的步驟做完後發現報錯,請按以下順序檢查。
- 檢查目錄結構是否正確。確保 templatetags 位於 blog 目錄下,且目錄名必須為 templatetags。具體請對照上文給出的目錄結構。
- 確保 templatetags 目錄下有 __init__.py 檔案。
- 確保通過
register = template.Library()
和@register.inclusion_tag
裝飾器將函式裝飾為一個模板標籤。 - 確保在使用模板標籤以前匯入了 blog_extras,即 {% load blog_extras%}。注意要在使用任何 blog_extras下的模板標籤以前匯入它。
- 確保模板標籤的語法使用正確,即 {% load blog_extras %},注意 { 和 % 以及 % 和 } 之間沒有任何空格。
歡迎關注 HelloGitHub 公眾號,獲取更多開源專案的資料和內