Flask-FlatPages 使用手册

Flask-FlatPages是Flask应用的一个小工具,规则基于YAML和Markdown,实现了文本文档和模板的结合。用户可以通过编写‘.md’(默认)文本文档即可轻松生成网页。在与Frozen-Flask配合使用是可以更轻松地实现资源管理。

(翻译自官方文档,英文版请点击这里)。

什么是Flask FlatPages

Flask-FlatPages 为你的Flask应用提供了一系列的网页,这些网页基于文本文档(flat text files)而不是关系型数据库。

安装

通过其中一个以下的命令来安装本扩展

$ easy_install Flask-FlatPages

如果你安装了pip

$ pip install Flask-FlatPages

或者你可以通过Github获得源代码

配置

首先你需要初始化一个FlatPages对象 from flask import Flask from flask_flatpages import FlatPages

app = Flask(__name__)#初始化Flask对象
app.config.from_pyfile('mysettings.cfg')#引入配置文件
pages = FlatPages(app)通过Flask对象创建Flask实例

同时你也可以稍后再通过init_app()引入Flask对象

1
2
3
4
5
6
7
pages = FlatPages()

def create_app(config='mysettings.cfg'):
app = Flask(__name__)
app.config.from_pyfile(config)
pages.init_app(app)
return app

以下为Flask-FlatPages配置选项,它们都不是必选的。

FLATPAGES_ROOT
    查找page文件的目录,相对路径为应用根目录,同static/templates文件夹在一起,默认是pages

FLATPAGES_EXTENSION
    查找的文件的扩展名,FLATPAGES_ROOT下无后缀文件都会被忽略。默认为.html

FLATPAGES_ENCODING
    page文件编码,默认为utf-8

FLATPAGES_HTML_RENDERER

FLAT_PAGES_MARKDOWN_EXTENSIONS
    一个列表的有着默认HTML渲染器的Markdown扩展。默认为['codehilite']

FLAT_PAGES_AUTO_RELOAD
    是否进行页面重载。默认为只在DEBUG模式下使用。详情见[Laziness and caching]()

使用说明

当第一次使用(详见Laziness and chaching 了解更多), 该扩展从文件系统加载所有的pages:一个Page实例是被创建在FLATPAGES_ROOT下面的后缀为FLATPAGES_EXTENSION.

每一个实例都和它的路劲相关联: 通过'/'划分开的相对于pages的根目录的路径(不包含扩展).例如,一个位于C:\myapp 有着默认设置的app实例。它的绝对路径是C:\myapp\pages\lorem\ipsum.html 但是它的路径是lorem/ipsum.

每一个文件都是由YAML映射的元数据,空白行和内容首页。

title: Hello   //page.meta.title 或者 page.meta['title']
published: 2010-12-22 ////page.meta.published 或者 page.meta['published']

Hello. *World*!

Lorem ipsum dolor sit amet,...

文章主体格式默认使用Markdown, 如果使用了的话Pygments也是默认选项,但是主要还是根据FLATPAGES_HTML_RENDERER里设置的值来决定。

使用Pygments,你需要单独进行样式声明。你可以使用pygments_style_defs():

1
2
3
@app.route('/pygments.css')
def pygments_css():
    return pygments_style_defs('tango'), 200, {'Content-Type': 'text/css'}

同时在模板里面:

<link rel="stylesheet" href="\{\{ url_for('pygments_css') }}">

使用定制Markdown扩展

默认情况下,Flask-FlatPages 通过MarkdownPygments来渲染文章主体。这也意味着将 ['codehilite']扩展列表传给markdown.markdown函数。

但某些时间你需要定制文件,比如说使用其他扩展或禁用默认方法,这些可以通过传递特殊配置参数来实现。

FLATPAGES_MARKDOWN_EXTENSIONS = ['codehilite', 'headerid']

或者禁用默认配置

FLATPAGES_MARKDOWN_EXTENSIONS = []

偷懒和缓存

FlatPages 不会接触到文件系统直到需要的时候,但是如果它读取数据时,它会从磁盘一次性读取完毕。

然后,pages 不会被再次加载 除非你明确地要求它使用FlatPages.reload().或通过配置接受的新请求。(详见FLATPAGES_AUTO_RELOAD.)

这个设计是在适配Frozen-Flask(Flask生成静态网页的工具)时使用,但是即便你不用他还是可以正常工作:你修改了代码并且已经重启了生产服务器,你只需要修改页面内容就好了。同样的,在版本控制系统下这依然有效。

但是如果你有很多网页并且加载时间很长,你可以让它在初始化过程中强制加载,当第一个请求被使用。

1
2
pages = FlatPages(app)
pages.get('foo') # Force loading now. foo.html may not even exist.

每次全部都加载看起来很浪费,但是这种影响可以通过缓存来减轻:如果文件的修改时间并没有变化,它不会被再次重复加载,之前的Page实例也会被重复利用。

同样地,YAML和Markdown的解析也是偷懒的和被缓存的:用不到的时候就不加载,没更改过就不会重复加载。

API

class flask_flatpages.FlatPages(app=None)

一个page实例集合

范例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
pages = FlatPages(app)

@app.route('/')
def index():

    //Articles are pages with a publication date
    articles = (p for p in pages if 'published' in p.meta)
    // Show the 10 most recent articles, most recent first.
    latest = sorted(articles, reverse=True,key=lambda p: p.meta['published'])
    return render_template('articles.html', articles=latest[:10])

@app.route('/<path:path>/')
def page(path):

    page = pages.get_or_404(path)
    template = page.meta.get('template', 'flatpage.html')
    return render_template(template, page=page)

__iter__() 对所有Page实例进行迭代

get(path, default=None) 返回路径下的Page实例,如果没有则返回默认(default)

get_or_404(path) 返回路径下的Page实例,或者raise一个Flask's的404 Error如果没有

init_app(app)

reload() 统统忘记吧(Forget all pages). 所有的Page都会被重新加载

class flask_faltpages.Page

单一的类来储存所有必要的关于flatpage的信息

主要目的是通过html_renderer函数来渲染页面内容

需要先定义一个hello.html 页面

# hello.html
title: Hello
published: 2010-12-22

Hello, *World*!

Lorem ipsum dolor sit amet, …

以上为test.md

1
2
3
4
5
6
7
8
9
>>> page = pages.get('hello')
>>> page.meta # PyYAML converts YYYY-MM-DD to a date object
{'title': u'Hello', 'published': datetime.date(2010, 12, 22)}
>>> page['title']
u'Hello'
>>> page.body
u'Hello, *World*!\n\nLorem ipsum dolor sit amet, \u2026'
>>> page.html
u'<p>Hello, <em>World</em>!</p>\n<p>Lorem ipsum dolor sit amet, \u2026</p>'

__getitem__(name) 使用元数据的快捷方式

__html__() 在模板中,{{ page }}等同于{{ page.html|safe }}.

html 网页内容,被渲染器渲染 meta 一个在页头被YAML解析的元数据的词典

path= None path就是pages实例获得的地方,在pages.get(path)

flask_flatpages.pygmented_markdown(text, flatpages=None)

  • 将markdown 文本变成HTML
  • 使用CodeHilite扩展当Pygments一起使用.但是如果Pygments不可以使用,就把“codehilite”从扩展列表移除。
  • 如果你需要其他的扩展,请在设置列表里面配置 FLATPAGES_MARKDOWN_EXTENSIONS.之后整个的FlatPages实例都会作为第二个参数被传递到FLATPAGES_HTML_RENDERER.

flask_flatpages.pygments_style_defs(style='default') - Returns: CodeHiliteMarkdown插件的CSS定义 - 参数: style - Pygments style 样式 - 只有当Pygments可用的时候