The Flask Mega-Tutorial 之 Chapter 9: Pagination

小引

作爲 social network 的特性之一， Chapter 8 已經完成 “followers - followed” 的 db 設置。
前面幾節，一直使用 fake posts 作爲權宜之計；本節將去掉 fake posts，替換成真的posts，並使 app能夠接受 user 填寫的 post，然後將其在 home & profile 頁顯示。

---

Submission of Blog Posts

Home 頁面創建 post 提交功能。

1、創建 post submission form 。
app / forms.py: blog submission form.

class PostForm(FlaskForm):
    post = TextAreaField('Say something', validators=[
        DataRequired(), Length(min=1, max=140)])
    submit = SubmitField('Submit')

2、將 post submission form 加到 index template
app / templates / index.html:

{% extends "base.html" %}

{% block content %}
    <h1>Hi, {{ current_user.username }}!</h1>
    <form action="" method="post">
        {{ form.hidden_tag() }}
        <p>
            {{ form.post.label }}<br>
            {{ form.post(cols=32, rows=4) }}<br>
            {% for error in form.post.errors %}
            <span style="color: red;">[{{ error }}]</span>
            {% endfor %}
        </p>
        <p>{{ form.submit() }}</p>
    </form>
    {% for post in posts %}
    <p>
    {{ post.author.username }} says: <b>{{ post.body }}</b>
    </p>
    {% endfor %}
{% endblock %}

插入<form>..</form>，其中 {{ form.post(cols=32, rows=4) }} 尺寸，對應 form 中的 140 。

3、更改路由 ‘index’， 添加 PostForm
app / routes.py: post submission form in index view function.

from app.forms import PostForm
from app.models import Post

@app.route('/', methods=['GET', 'POST'])
@app.route('/index', methods=['GET', 'POST'])
@login_required
def index():
    form = PostForm()
    if form.validate_on_submit():
        post = Post(body=form.post.data, author=current_user)
        db.session.add(post)
        db.session.commit()
        flash('Your post is now live!')
        return redirect(url_for('index'))
    posts = [
        {
            'author': {'username': 'John'},
            'body': 'Beautiful day in Portland!'
        },
        {
            'author': {'username': 'Susan'},
            'body': 'The Avengers movie was so cool!'
        }
    ]
    return render_template("index.html", title='Home Page', form=form,
                           posts=posts)

• 引入 Post 及 PostForm
• methods 添加 'POST' （需要接受 user 提交數據）
• 利用 Post 類處理 logic，完成 db 提交。
• render_template 增加 form 參數，完成渲染

注： form 完成驗證提交後，設置了 重定向至 ‘index’，即所謂的 POST/Redirect/GET 模式。
因爲瀏覽器的 re-fresh 操作，默認issue last request。
如果 form submission 完成提交後未設置重定向，則 user 在提交表單後而刷新，則會使瀏覽器二次提交表單（last request is POST）；瀏覽器對此感到異常，會讓 user 確認duplicate submission。
如果 form submission 完成提交後設置了重定向，則 browser 的 last request 變成 GET。

It avoids inserting duplicate posts when a user inadvertently refreshes the page after submitting a web form.

---

Displaying Blog Posts

將 index 頁面的 fake posts 替換爲真實 posts

app / routes.py:： display real posts in home page.

@app.route('/', methods=['GET', 'POST'])
@app.route('/index', methods=['GET', 'POST'])
@login_required
def index():
    # ...
    posts = current_user.followed_posts().all()
    return render_template("index.html", title='Home Page', form=form,
                           posts=posts)

注：

• index 頁展示 followed 的 users 的 posts
• PostForm 亦展示，供 user 發佈新 post
• User 定義的 followd_posts()，已按照 post.timestamp desc() 排序
• 舊的 index.html ，因爲完美匹配，無需更改

---

Making It Easier to Find Users to Follow

創建 Explore 頁面，顯示所有的 users 發佈的 posts，便於查找 user 並 follow

1、創建路由 ‘explore’

app / routes.py:

@app.route('/explore')
@login_required
def explore():
    posts = Post.query.order_by(Post.timestamp.desc()).all()
    return render_template('index.html', title='Explore', posts=posts)

• Explore 頁面，無發佈新 post 的位置，故無 PostForm
• 用 Post 類，獲取所有 posts，並按 timestamp 逆向排序
• template，借用 index.html，因爲佈局類似
  
  

2、更改模板 index.html， 爲 其中<form></form> 添加條件語句，使其兼容 'index' 與 'explore'

{% extends "base.html" %}

{% block content %}
    <h1>Hi, {{ current_user.username }}!</h1>
    {% if form %}
    <form action="" method="post">
        ...
    </form>
    {% endif %}
    ...
{% endblock %}

3、在底板 base.html 中的導航欄，添加 Explore 鏈接

app / templates / base.html: link to explore page in navigation bar.

<a href="{{ url_for('explore') }}">Explore</a>

4、爲 index 及 explore 頁面中的 post 的 user 添加鏈接，便於查看並follow

app / templates / _post.html: show link to author in blog posts.

    <table>
        <tr valign="top">
            <td><img src="{{ post.author.avatar(36) }}"></td>
            <td>
                <a href="{{ url_for('user', username=post.author.username) }}">
                    {{ post.author.username }}
                </a>
                says:<br>{{ post.body }}
            </td>
        </tr>
    </table>

注：

• 調用此 _post.html 的頁面包括 index、explore、user，分別對應 Home、Explore、Profile 頁面
• 因爲 Home 及 Explore 共用 一個模板 index.html，故可改一處，使得兩處生效

    ...
    {% for post in posts %}
        {% include '_post.html' %}
    {% endfor %}
    ...

• Profile 對應的 user.html ，亦會調用此 sub_template（見後續下文）

---

Pagination of Blog Posts

• 完成 Home、Explore 頁面的設置（新 post 提交、各自頁面限定的 posts 的顯示），現對各頁面的 posts 進行編頁（pagination）。

• pagination 的方法即，給定 page size（POSTS_PER_PAGE），然後將總的 posts 按照要求的順序排序，調用 paginate() 。

• The paginate method can be called on any query object from Flask-SQLAlchemy.
  >>> user.followed_posts().paginate(1, 20, False).items

  • 1，page number
  • 20, the number of items per page（可在 config 中設定）
  • 標識符：如 True，則超出範圍時，對客戶端發出 404 錯誤；如 False，則超出範圍時發送 空的 list。

1、 設定 paginate(page_num, page_size, error_flag) 的 page size

config.py: posts per page configuration.

class Config(object):
    # ...
    POSTS_PER_PAGE = 3

2、利用 query string argument，將 page_num 添加到 URLs，爲 Home、Explore 進行 Paginating

app / routes.py:

@app.route('/', methods=['GET', 'POST'])
@app.route('/index', methods=['GET', 'POST'])
@login_required
def index():
    # ...
    page = request.args.get('page', 1, type=int)
    posts = current_user.followed_posts().paginate(
        page, app.config['POSTS_PER_PAGE'], False)
    return render_template('index.html', title='Home', form=form,
                           posts=posts.items)

@app.route('/explore')
@login_required
def explore():
    page = request.args.get('page', 1, type=int)
    posts = Post.query.order_by(Post.timestamp.desc()).paginate(
        page, app.config['POSTS_PER_PAGE'], False)
    return render_template("index.html", title='Explore', posts=posts.items)

注：

• posts 經過 paginate()，爲 Pagination 類的 對象，所以 render_template() 中的 posts 爲 posts.items
  

The return value from paginate is a Pagination object. The items attribute of this object contains the list of items in the requested page.

---

Page Navigation

paginate() 返回的是 Flask-SQLAlchemy 的 Pagination 類的對象，除了上面的 items 屬性外，還有四類：

• has_next: 當前頁後，至少還有一頁，則 True
• has_prev: 當前頁前，至少還有一頁，則 True
• next_num: 下頁的頁碼
• prev_num: 前頁的頁碼
  
  

1、在 index 及 explore 路由函數中，設置 next_url, prev_url

app / routes.py: next and previous page links.

@app.route('/', methods=['GET', 'POST'])
@app.route('/index', methods=['GET', 'POST'])
@login_required
def index():
    # ...
    page = request.args.get('page', 1, type=int)
    posts = current_user.followed_posts().paginate(
        page, app.config['POSTS_PER_PAGE'], False)
    next_url = url_for('index', page=posts.next_num) \
        if posts.has_next else None
    prev_url = url_for('index', page=posts.prev_num) \
        if posts.has_prev else None
    return render_template('index.html', title='Home', form=form,
                           posts=posts.items, next_url=next_url,
                           prev_url=prev_url)

 @app.route('/explore')
 @login_required
 def explore():
    page = request.args.get('page', 1, type=int)
    posts = Post.query.order_by(Post.timestamp.desc()).paginate(
        page, app.config['POSTS_PER_PAGE'], False)
    next_url = url_for('explore', page=posts.next_num) \
        if posts.has_next else None
    prev_url = url_for('explore', page=posts.prev_num) \
        if posts.has_prev else None
    return render_template("index.html", title='Explore', posts=posts.items,
                          next_url=next_url, prev_url=prev_url)

注： 如果 next_url 或 prev_next 爲 None，則根據模板的條件邏輯，最終不顯示（見下面模板）。

2、在模板中增加 next_url 及 prev_url 的鏈接

app / templates / index.html: render pagination links on the template.

    ...
    {% for post in posts %}
        {% include '_post.html' %}
    {% endfor %}

    {% if prev_url %}
    <a href="{{ prev_url }}">Newer posts</a>
    {% endif %}

    {% if next_url %}
    <a href="{{ next_url }}">Older posts</a>
    {% endif %}
    ...

注：因爲按照 timestamp 的 desc 排序，所以 next_url 爲 Older posts。

---

Pagination in the User Profile Page

Home 及 Explore 已經完成 pagination & page navigation，按相同方式 修改 Profile 頁。

1、改路由 user

app / routes.py: pagination in the user profile view function.

@app.route('/user/<username>')
@login_required
def user(username):
    user = User.query.filter_by(username=username).first_or_404()
    page = request.args.get('page', 1, type=int)
    posts = user.posts.order_by(Post.timestamp.desc()).paginate(
        page, app.config['POSTS_PER_PAGE'], False)
    next_url = url_for('user', username=user.username, page=posts.next_num) \
        if posts.has_next else None
    prev_url = url_for('user', username=user.username, page=posts.prev_num) \
        if posts.has_prev else None
    return render_template('user.html', user=user, posts=posts.items,
                           next_url=next_url, prev_url=prev_url)

注： 利用 user.posts 獲取此 user 的所有posts（posts 爲 virtual field）

2、更改 Profile 的模板 user.html

app / templates / user.html: pagination links in the user profile template.

    ...
    {% for post in posts %}
        {% include '_post.html' %}
    {% endfor %}
    {% if prev_url %}
    <a href="{{ prev_url }}">Newer posts</a>
    {% endif %}
    {% if next_url %}
    <a href="{{ next_url }}">Older posts</a>
    {% endif %}

---

根據實際情況，設置 page_size

config.py: posts per page configuration.

class Config(object):
    # ...
    POSTS_PER_PAGE = 25