Flask-FlatPages是Flask应用的一个小工具,规则基于YAML和Markdown,实现了文本文档和模板的结合。用户可以通过编写‘.md’(默认)文本文档即可轻松生成网页。在与Frozen-Flask配合使用是可以更轻松地实现资源管理。
(翻译自官方文档,英文版请点击这里)。
什么是Flask FlatPages
Flask-FlatPages 为你的Flask应用提供了一系列的网页,这些网页基于文本文档(flat text files)而不是关系型数据库。
- BSD licensed
- 最新的文档在python.org
- 源码,问题和访问请求在Github
- 发行在PyPI
安装
通过其中一个以下的命令来安装本扩展
$ 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 通过Markdown和Pygments来渲染文章主体。这也意味着将 ['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可用的时候