├── .gitattributes ├── .gitignore ├── README.md └── docs ├── Makefile ├── basic-usage.rst ├── bootstrap2.rst ├── cdn.rst ├── changelog.rst ├── conf.py ├── configuration.rst ├── faq.rst ├── forms.rst ├── index.rst ├── macros.rst ├── nav.rst ├── sqlalchemy.rst └── translate.rst /.gitattributes: -------------------------------------------------------------------------------- 1 | # Auto detect text files and perform LF normalization 2 | * text=auto 3 | 4 | # Custom for Visual Studio 5 | *.cs diff=csharp 6 | 7 | # Standard to msysgit 8 | *.doc diff=astextplain 9 | *.DOC diff=astextplain 10 | *.docx diff=astextplain 11 | *.DOCX diff=astextplain 12 | *.dot diff=astextplain 13 | *.DOT diff=astextplain 14 | *.pdf diff=astextplain 15 | *.PDF diff=astextplain 16 | *.rtf diff=astextplain 17 | *.RTF diff=astextplain 18 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Windows image file caches 2 | Thumbs.db 3 | ehthumbs.db 4 | 5 | # Folder config file 6 | Desktop.ini 7 | 8 | # Recycle Bin used on file shares 9 | $RECYCLE.BIN/ 10 | 11 | # Windows Installer files 12 | *.cab 13 | *.msi 14 | *.msm 15 | *.msp 16 | 17 | # Windows shortcuts 18 | *.lnk 19 | 20 | # ========================= 21 | # Operating System Files 22 | # ========================= 23 | 24 | # OSX 25 | # ========================= 26 | 27 | .DS_Store 28 | .AppleDouble 29 | .LSOverride 30 | 31 | # Thumbnails 32 | ._* 33 | 34 | # Files that might appear in the root of a volume 35 | .DocumentRevisions-V100 36 | .fseventsd 37 | .Spotlight-V100 38 | .TemporaryItems 39 | .Trashes 40 | .VolumeIcon.icns 41 | 42 | # Directories potentially created on remote AFP share 43 | .AppleDB 44 | .AppleDesktop 45 | Network Trash Folder 46 | Temporary Items 47 | .apdisk 48 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Flask-Bootstrap中文文档 2 | 3 | 文档地址在[http://flask-bootstrap-zh.readthedocs.io/zh/latest/](http://flask-bootstrap-zh.readthedocs.io/zh/latest/)，欢迎创建PR提交改进。 4 | 5 | **译者注：这个项目目前已经很久没有更新，而且不支持Bootstrap 4，你可以尝试使用一个更轻量的的替代品：[Bootstrap-Flask](https://github.com/greyli/bootstrap-flask)。** 6 | -------------------------------------------------------------------------------- /docs/Makefile: -------------------------------------------------------------------------------- 1 | # Makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = -n 6 | SPHINXBUILD = sphinx-build 7 | PAPER = 8 | BUILDDIR = _build 9 | 10 | # User-friendly check for sphinx-build 11 | ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) 12 | $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) 13 | endif 14 | 15 | # Internal variables. 16 | PAPEROPT_a4 = -D latex_paper_size=a4 17 | PAPEROPT_letter = -D latex_paper_size=letter 18 | ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 19 | # the i18n builder cannot share the environment and doctrees with the others 20 | I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 21 | 22 | .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext 23 | 24 | help: 25 | @echo "Please use \`make ' where is one of" 26 | @echo " html to make standalone HTML files" 27 | @echo " dirhtml to make HTML files named index.html in directories" 28 | @echo " singlehtml to make a single large HTML file" 29 | @echo " pickle to make pickle files" 30 | @echo " json to make JSON files" 31 | @echo " htmlhelp to make HTML files and a HTML help project" 32 | @echo " qthelp to make HTML files and a qthelp project" 33 | @echo " devhelp to make HTML files and a Devhelp project" 34 | @echo " epub to make an epub" 35 | @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 36 | @echo " latexpdf to make LaTeX files and run them through pdflatex" 37 | @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" 38 | @echo " text to make text files" 39 | @echo " man to make manual pages" 40 | @echo " texinfo to make Texinfo files" 41 | @echo " info to make Texinfo files and run them through makeinfo" 42 | @echo " gettext to make PO message catalogs" 43 | @echo " changes to make an overview of all changed/added/deprecated items" 44 | @echo " xml to make Docutils-native XML files" 45 | @echo " pseudoxml to make pseudoxml-XML files for display purposes" 46 | @echo " linkcheck to check all external links for integrity" 47 | @echo " doctest to run all doctests embedded in the documentation (if enabled)" 48 | 49 | clean: 50 | rm -rf $(BUILDDIR)/* 51 | 52 | html: 53 | $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 54 | @echo 55 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 56 | 57 | dirhtml: 58 | $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 59 | @echo 60 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." 61 | 62 | singlehtml: 63 | $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 64 | @echo 65 | @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." 66 | 67 | pickle: 68 | $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 69 | @echo 70 | @echo "Build finished; now you can process the pickle files." 71 | 72 | json: 73 | $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json 74 | @echo 75 | @echo "Build finished; now you can process the JSON files." 76 | 77 | htmlhelp: 78 | $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 79 | @echo 80 | @echo "Build finished; now you can run HTML Help Workshop with the" \ 81 | ".hhp project file in $(BUILDDIR)/htmlhelp." 82 | 83 | qthelp: 84 | $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 85 | @echo 86 | @echo "Build finished; now you can run "qcollectiongenerator" with the" \ 87 | ".qhcp project file in $(BUILDDIR)/qthelp, like this:" 88 | @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Flask-Bootstrap.qhcp" 89 | @echo "To view the help file:" 90 | @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Flask-Bootstrap.qhc" 91 | 92 | devhelp: 93 | $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 94 | @echo 95 | @echo "Build finished." 96 | @echo "To view the help file:" 97 | @echo "# mkdir -p $$HOME/.local/share/devhelp/Flask-Bootstrap" 98 | @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Flask-Bootstrap" 99 | @echo "# devhelp" 100 | 101 | epub: 102 | $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub 103 | @echo 104 | @echo "Build finished. The epub file is in $(BUILDDIR)/epub." 105 | 106 | latex: 107 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 108 | @echo 109 | @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." 110 | @echo "Run \`make' in that directory to run these through (pdf)latex" \ 111 | "(use \`make latexpdf' here to do that automatically)." 112 | 113 | latexpdf: 114 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 115 | @echo "Running LaTeX files through pdflatex..." 116 | $(MAKE) -C $(BUILDDIR)/latex all-pdf 117 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 118 | 119 | latexpdfja: 120 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 121 | @echo "Running LaTeX files through platex and dvipdfmx..." 122 | $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja 123 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 124 | 125 | text: 126 | $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text 127 | @echo 128 | @echo "Build finished. The text files are in $(BUILDDIR)/text." 129 | 130 | man: 131 | $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man 132 | @echo 133 | @echo "Build finished. The manual pages are in $(BUILDDIR)/man." 134 | 135 | texinfo: 136 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 137 | @echo 138 | @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." 139 | @echo "Run \`make' in that directory to run these through makeinfo" \ 140 | "(use \`make info' here to do that automatically)." 141 | 142 | info: 143 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 144 | @echo "Running Texinfo files through makeinfo..." 145 | make -C $(BUILDDIR)/texinfo info 146 | @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." 147 | 148 | gettext: 149 | $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale 150 | @echo 151 | @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." 152 | 153 | changes: 154 | $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes 155 | @echo 156 | @echo "The overview file is in $(BUILDDIR)/changes." 157 | 158 | linkcheck: 159 | $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 160 | @echo 161 | @echo "Link check complete; look for any errors in the above output " \ 162 | "or in $(BUILDDIR)/linkcheck/output.txt." 163 | 164 | doctest: 165 | $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 166 | @echo "Testing of doctests in the sources finished, look at the " \ 167 | "results in $(BUILDDIR)/doctest/output.txt." 168 | 169 | xml: 170 | $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml 171 | @echo 172 | @echo "Build finished. The XML files are in $(BUILDDIR)/xml." 173 | 174 | pseudoxml: 175 | $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml 176 | @echo 177 | @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." 178 | -------------------------------------------------------------------------------- /docs/basic-usage.rst: -------------------------------------------------------------------------------- 1 | 基本用法 2 | ==== 3 | 4 | 开始前第一步是导入和加载扩展:: 5 | 6 | from flask import Flask 7 | from flask_bootstrap import Bootstrap 8 | 9 | def create_app(): 10 | app = Flask(__name__) 11 | Bootstrap(app) 12 | 13 | return app 14 | 15 | # do something with app... 16 | 17 | 加载后，新的模板可以从bootstrap蓝本自带的模板文件夹里获取。 18 | 19 | 示例程序 20 | ---- 21 | 22 | 如果你想看一个小的程序示例，可以 `到github上浏览 23 | `_ 。 24 | 25 | 26 | 模板 27 | ---- 28 | .. highlight:: jinja 29 | 30 | 创建一个基于Bootstrap的模板很简单:: 31 | 32 | {% extends "bootstrap/base.html" %} 33 | {% block title %}This is an example page{% endblock %} 34 | 35 | {% block navbar %} 36 |
37 | 38 |
39 | {% endblock %} 40 | 41 | {% block content %} 42 |

Hello, Bootstrap

43 | {% endblock %} 44 | 45 | 所有你要在子模板里做的事情都是基于块（block）的。一些块（像 ``title`` ， ``navbar`` 或 ``content`` ） 46 | 是“convenience blocks（便利块）”。严格来说，它们不是必须的，但是被增加用来优化文档结构（方便使用）。 47 | 48 | 一个非常有用的特性是 `Jinja2的super() 49 | `_ 函数。它可以让你修改块，而不是替换它们。 50 | 51 | .. _block-names: 52 | 53 | 可用的块 54 | ~~~~~~~~ 55 | 56 | ============ =========== ======= 57 | 块名 外部块的目的 58 | ============ =========== ======= 59 | doc 最外部的块。 60 | html doc 包含 ```` 标签的所有内容。 61 | html_attribs doc HTML标签的属性。 62 | head doc 包含 ```` 标签的所有内容。 63 | body doc 包含 ```` 标签的所有内容。 64 | body_attribs body ```` 标签的属性。 65 | **title** head 包含 ```` 标签的所有内容。 66 | **styles** head 包含所有头部的CSS文件 ``<link>`` 标签。 67 | metas head 包含所有头部的 ``<meta>`` 标签。 68 | **navbar** body 直接放在 *content* 上面的空块。 69 | **content** body HTML主体（body）的便利块，把东西放在这里。 70 | **scripts** body 包含所有在HTML文件尾部的 ``<script>`` 标签。 71 | ============ =========== ======= 72 | 73 | 示例 74 | ~~~~ 75 | 76 | * 增加一个自定义的CSS文件:: 77 | 78 | {% block styles %} 79 | {{super()}} 80 | <link rel="stylesheet" 81 | href="{{url_for('.static', filename='mystyle.css')}}"> 82 | {% endblock %} 83 | 84 | * 自定义在Bootstrap的javascript代码 *之前* 加载的Javascript:: 85 | 86 | {% block scripts %} 87 | <script src="{{url_for('.static', filename='myscripts.js')}}"></script> 88 | {{super()}} 89 | {% endblock %} 90 | 91 | * 增加 ``lang="zh"`` 属性到 ``<html>`` 标签:: 92 | 93 | {% block html_attribs %} lang="zh"{% endblock %} 94 | 95 | 静态资源文件 96 | ----------- 97 | 98 | URL端点（url-endpoint） ``bootstrap.static`` 可以让你引用Bootstrap资源文件，但通常不需要这样。 99 | 更好的做法是使用 ``bootstrap_find_resource`` 模板过滤器，它会负责设置CDN。 100 | 101 | 对当前的资源文件系统的详细描述在 :doc:`cdn` 。 102 | 103 | -------------------------------------------------------------------------------- /docs/bootstrap2.rst: -------------------------------------------------------------------------------- 1 | 使用 Bootstrap 2 2 | ================ 3 | 4 | 目前Bootstrap主要的稳定版本是3，它不向后兼容Bootstrap2。除了版本3，Flask-Bootstrap 5 | 继续支持Bootstrap2的最新版本。（不过你不要期待有新特性，只是修正了漏洞而已。） 6 | 7 | 安装 8 | ----- 9 | 10 | 通过安装Flask-Bootstrap，你将总是得到最新版本，即Boostrap3。要安装（或是保持）Flask-Bootstrap 2， 11 | 你必须在你的 ``setup.py`` 或 ``requirements.txt`` 里指定版本，类似这样:: 12 | 13 | # other stuff in setup.py... 14 | install_requires=['flask-bootstrap<3', 'another_package'] 15 | 16 | 把Flask-Bootstrap固定为一个明确的版本是个好主意（例如 ``'flask-bootstrap==2.3.2.2'`` ，以此来避免生产环境中的意外）。 17 | 18 | 文档 19 | ----- 20 | 21 | 在版本3之前，Flask-Bootstrap只有一个README文件来作为文档。你可以在下面找到整个文件。 22 | 23 | 24 | 你也可以在 `GitHub <https://github.com>`_ 上查找之前的版本标签。 25 | 要看主要的版本2的代码或样例程序，在这里 `2.3.2.2 <https://github.com/mbr/flask-bootstrap/tree/2.3.2.2>`_ 。 26 | 27 | Flask-Bootstrap 28 | ^^^^^^^^^^^^^^^ 29 | 30 | Flask-Bootstrap 把 `Bootstrap <http://getbootstrap.com>`_ 打包进一个 31 | 扩展，这个扩展主要由一个叫“bootstrap”的蓝本（blueprint）组成。它也可以创建链接从一个CDN上引用Bootstrap。 32 | 33 | 34 | 用法 35 | **** 36 | 37 | 这儿是一个例子:: 38 | Here is an example:: 39 | 40 | from flask_bootstrap import Bootstrap 41 | 42 | [...] 43 | 44 | Bootstrap(app) 45 | 46 | 这让一些新的模板可供使用，主要是 ``bootstrap_base.html`` 和 ``bootstrap_responsive.html`` 。 47 | 这些是包含所有bootstrap资源文件和预定义块（你可以在块里放你的内容）的空白页。要修改的核心块是 ``body_content`` ， 48 | 另外查看模板的源码寻找更多可能性。 49 | 50 | URL端点（url-endpoint） ``bootstrap.static`` 可以让你引用Bootstrap资源文件，但通常不需要这样。 51 | 更好的做法是使用 ``bootstrap_find_resource`` 模板过滤器，它会负责设置CDN。 52 | 53 | 宏 54 | **** 55 | 56 | .. highlight:: jinja 57 | 58 | 一些可供使用的宏可以让你的生活更加简单。这些需要被导入（我建议创建你自己的“base.html”模板， 59 | 首先扩展bootstrap的基模板，然后在那里包含这个宏）。 60 | 61 | 一个“base.html”的例子:: 62 | 63 | {% extends "bootstrap_responsive.html" %} 64 | {% import "bootstrap_wtf.html" as wtf %} 65 | 66 | 表单 67 | ~~~~ 68 | 69 | ``bootstrap/wtf.html`` 模板包含了帮助你快速输出表单的宏。 70 | 最基本的方式是把它们作为手动创建表单的助手:: 71 | 72 | <form class="form form-horizontal" method="post"> 73 | {{ form.hidden_tag() }} 74 | {{ wtf.form_errors(form, "only") }} 75 | 76 | {{ wtf.horizontal_field(form.field1) }} 77 | {{ wtf.horizontal_field(form.field2) }} 78 | 79 | <div class="form-actions"> 80 | <button name="action_save" type="submit" class="btn btn-primary">Save changes</button> 81 | </div> 82 | </form> 83 | 84 | 然而，你经常只是想快速生成一个表单，而且不需要过度的微调，这时可以直接使用 ``quick_form`` 宏:: 85 | 86 | {{ wtf.quick_form(form) }} 87 | 88 | 配置选项 89 | ********* 90 | 91 | 这里有一些模板使用的配置选项: 92 | 93 | ====================================== ======================================================== === 94 | 选项 默认值 95 | ====================================== ======================================================== === 96 | ``BOOTSTRAP_USE_MINIFIED`` ``True`` 是否使用压缩过的css/js文件。 97 | ``BOOTSTRAP_JQUERY_VERSION`` ``'1'`` 模板里这个版本的jQuery通过Google的CDN加载。另外提一下 ``BOOTSTRAP_USE_MINIFIED`` ，把这个值设为None会不加载jQuery。要注意的是未压缩的Bootstrap资源在Boostrap的CDN上有时会丢失，所以在没有打开 ``BOOTSTRAP_USE_MINIFIED`` 时最好不要用它。 98 | ``BOOTSTRAP_HTML5_SHIM`` ``True`` 加载默认的IE兼容性修复文件，这些文件通常在使用bootstrap时被加载。 99 | ``BOOTSTRAP_GOOGLE_ANALYTICS_ACCOUNT`` ``None`` 如果设置，使用这个账号加载 `Google Analytics <http://www.google.com/analytics>`_ 模板文件（boilerplate）。 100 | ``BOOTSTRAP_USE_CDN`` ``False`` 如果设为 ``True`` ，Bootstrap资源将不会从本地应用实例加载，而是使用CDN（使用 ``BOOTSTRAP_CDN_BASEURL`` 配置）。 101 | ``BOOTSTRAP_CDN_BASEURL`` 用匹配到 ``cdnjs.com`` 的CDN地址建立的字典。 当使用CDN时要添加的Bootstrap和其他文件名的CDN地址。 102 | ``BOOTSTRAP_CDN_PREFER_SSL`` ``True`` 如果 ``BOOTSTRAP_CDN_BASEURL`` 以 ``//`` 开头，会在之前添加 ``'https:'`` 。 103 | ``BOOTSTRAP_CUSTOM_CSS`` ``False`` 如果设为 ``True`` ，将不会加载Bootstrap的CSS文件。如果你编写了一个自定义的css文件，其中已经包含了bootstrap，可以使用这个选项。 104 | ``BOOTSTRAP_QUERYSTRING_REVVING`` ``True`` 如果设为 ``True`` ，会添加一个包含当前所有本地静态文件版本的查询字符串。这会确保一旦升级Flask-Bootstrap，这些文件就会被更新。 105 | ====================================== ======================================================== === 106 | 107 | .. _FontAwesome: http://fortawesome.github.com/Font-Awesome/ 108 | 109 | 安装 110 | **** 111 | 112 | 你可以使用 ``pip`` 从GitHub或是从 `PyPI 113 | <http://pypi.python.org/pypi/Flask-Bootstrap>`_ 安装。 114 | 115 | 版本笔记 116 | ********* 117 | 118 | Flask-Bootstrap 尝试跟随Bootstrap更新的脚步。版本变化通常 119 | 在 ``Bootstrap version`` 和 ``Flask-Bootstrap iteration`` 里。举例来说， 120 | 版本 ``2.0.3.2`` 集成了Bootstrap ``2.0.3`` 版本，并且是Flask-Bootstrap集成这个版本的第二次更新。 121 | 122 | 如果你需要让你的模板不改变，那么在你的setup.py里固定版本就可以了。 123 | 124 | FAQ 125 | *** 126 | 127 | 1. 为什么在我的模板输出里有我不想出现的自动转义？ 128 | 确保你的模板文件后缀为 ``.htm`` ， ``.html`` ， ``.xml`` 或是 ``.xhtml`` 。 129 | Flask依据模板文件扩展名来设置Jinja2自动转义模式（更多信息见 `这个StackOverflow问题 130 | <http://stackoverflow.com/questions/13222925/how-do-i-enable-autoescaping-in-templates-with-a-jhtml-extension-in-flask>`_ 131 | ）。 132 | 133 | 尽管如此，一般的约定是在你的Flask应用里使用 ``.html`` 后缀来命名你的HTML模板。 134 | 135 | 2. 我怎么向模板添加自定义的JavaScript？ 136 | 137 | 使用Jinjia2的 ``super()`` 连同 ``bootstrap_js_bottom`` 块。这个super函数从父模板 138 | 添加块的内容，这种方式甚至可以让你决定是否想要在jQuery/bootstrap之前或之后加载。举例来说:: 139 | 140 | {% block bootstrap_js_bottom %} 141 | {{super()}} 142 | <script src="my_app_code.js"> 143 | {% endblock %} 144 | 145 | 146 | 3. 我在部署时如何加载静态文件？ 147 | 148 | Flask-Bootstrap只是简单的添加一个叫 ``bootstrap`` 的蓝本，在这个意义上来说，它并不特别。 149 | 静态文件被匹配到一个特殊的URL前缀（默认为 ``static/bootstrap`` ）而且通过一个特定的文件夹提供， 150 | 这个文件夹可以在你的virtualenv安装包里找到（比如 ``lib/python2.7/site-packages/flask_bootstrap/static`` ）， 151 | 所以一个典型的安装将会是设定你的web服务器服务上面提到的文件夹的地址。 152 | 153 | 一个更优雅的解决方案是在WSGI服务器前放置一个缓存来处理 ``Cache-Control`` 报头。 154 | 默认情况下，Flask会在加载静态文件时附带一个12小时的过期时间 155 | （你可以使用 ``SEND_FILE_MAX_AGE_DEFAULT`` 改变这个值），这应该足够了。 156 | 157 | 这个方案可以使用 `nginx <http://nginx.org>`_ 158 | （或者，也许你更喜欢 `Varnish <http://varnish-cache.org>`_ ）或者他们的基于 159 | 相同工具的云服务应该也足够了。Flask-Bootstrap2.3.2.2通过提供查询字符串加速支持这些， 160 | 这确保当你更新Flask-Bootstrap时，更新版本的Bootstrap会被加载。 161 | （查看 ``BOOTSTRAP_QUERYSTRING_REVVING`` ） 162 | 163 | 164 | 变更记录 165 | ~~~~~~~~~ 166 | 167 | 168 | 参见 :doc:`changelog` ，那里有包括版本2的变更记录。 169 | -------------------------------------------------------------------------------- /docs/cdn.rst: -------------------------------------------------------------------------------- 1 | CDN 支持 2 | ======== 3 | 4 | Flask-Bootstrap 支持CDN和本地两种方式来调用资源文件，在运行时是可配置的。 5 | 一旦初始化，Flask-Bootstrap会存储一个叫 ``yourapp.extensions['bootstrap']['cdns']`` 的字典到你的程序实例里。 6 | 这个字典会匹配名字到 :py:class:`~flask_bootstrap.CDN` 实例。 7 | 8 | 当使用其他提供CDN的资源，你也可以在你的模板使用 :py:func:`~flask_bootstrap.bootstrap_find_resource` 。 9 | CDN会通过增加新的条目到上面提到的字典里面的方式被添加。 10 | 11 | .. autoclass:: flask_bootstrap.CDN 12 | :members: 13 | 14 | .. autoclass:: flask_bootstrap.StaticCDN 15 | :members: 16 | 17 | .. autoclass:: flask_bootstrap.WebCDN 18 | :members: 19 | 20 | .. autofunction:: flask_bootstrap.bootstrap_find_resource 21 | -------------------------------------------------------------------------------- /docs/changelog.rst: -------------------------------------------------------------------------------- 1 | .. include:: ../CHANGES 2 | -------------------------------------------------------------------------------- /docs/conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | 3 | project = u'Flask-Bootstrap' 4 | copyright = u'2013, Marc Brinkmann / 翻译: <a href="http://greyli.com" target="_blank">李辉</a>' 5 | version = '3.3.7.1' 6 | release = '3.3.7.1.dev1' 7 | 8 | extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'alabaster'] 9 | source_suffix = '.rst' 10 | master_doc = 'index' 11 | exclude_patterns = ['_build'] 12 | pygments_style = 'monokai' 13 | 14 | html_theme = 'alabaster' 15 | html_theme_options = { 16 | 'github_user': 'greyli', 17 | 'github_repo': 'flask-bootstrap-docs-zh', 18 | 'description': 'All Bootstrap, no boilerplate.', 19 | 'github_banner': True, 20 | 'github_button': False, 21 | 'show_powered_by': False, 22 | 23 | # required for monokai: 24 | 'pre_bg': '#292429', 25 | } 26 | html_sidebars = { 27 | '**': [ 28 | 'about.html', 29 | 'navigation.html', 30 | 'relations.html', 31 | 'searchbox.html', 32 | 'donate.html', 33 | ] 34 | } 35 | 36 | intersphinx_mapping = {'http://docs.python.org/': None, 37 | 'http://flask-sqlalchemy.pocoo.org/': None, 38 | 'http://pythonhosted.org/flask-nav/': None, 39 | 'http://flask.pocoo.org/docs/': None, 40 | 'https://wtforms.readthedocs.org/en/latest/': None, } 41 | -------------------------------------------------------------------------------- /docs/configuration.rst: -------------------------------------------------------------------------------- 1 | 配置 2 | ==== 3 | 4 | 这儿有一些Flask-Bootstrap使用的配置选项，这些是普通的Flask配置变量（关于Flask配置变量， `这里 <http://flask.pocoo.org/docs/config/>`_ 有一个指南）。 5 | 6 | .. note:: 有一个Flask扩展可以用来以 7 | `Flask-Appconfig <https://github.com/mbr/flask-appconfig>`_ 的形式协助编写 8 | `Twelve-Factor <http://12factor.net/>`_ 范式的应用程序。它也可以处理其他类型的配置安装 9 | 而且和Flask-Bootstrap兼容很好。 10 | 11 | ====================================== ======================================================== === 12 | 选项 默认值 13 | ====================================== ======================================================== === 14 | ``BOOTSTRAP_USE_MINIFIED`` ``True`` 是否使用压缩过的css/js文件。 15 | ``BOOTSTRAP_SERVE_LOCAL`` ``False`` 如果设为 ``True``，每次都将加载本地的Bootstrap资源文件。具体见：:doc:`cdn` 。 16 | ``BOOTSTRAP_LOCAL_SUBDOMAIN`` ``None`` 传递一个 ``subdomain`` 变量给已经生成的 :class:`~flask.Blueprint` 。当需要加载不同子域的本地文件时会很有用。 17 | ``BOOTSTRAP_CDN_FORCE_SSL`` ``True`` 如果一个CDN资源地址以 ``//`` 开头，会在地址前添加 ``'https:'`` 。 18 | ``BOOTSTRAP_QUERYSTRING_REVVING`` ``True`` 如果设为 ``True`` ，会添加一个包含当前所有本地静态文件版本的查询字符串。这会确保一旦升级Flask-Bootstrap，这些文件就会被更新。 19 | ====================================== ======================================================== === 20 | -------------------------------------------------------------------------------- /docs/faq.rst: -------------------------------------------------------------------------------- 1 | FAQ 2 | === 3 | 4 | 5 | 为什么在我的模板输出里有我不想出现的自动转义？ 6 | ------------------------------------------- 7 | 8 | 确保你的模板文件后缀为 ``.htm`` ， ``.html`` ， ``.xml`` 或是 ``.xhtml`` 。 9 | Flask依据模板文件扩展名来设置Jinja2自动转义模式（更多信息见 `这个StackOverflow问题 10 | <http://stackoverflow.com/questions/13222925/how-do-i-enable-autoescaping-in-templates-with-a-jhtml-extension-in-flask>`_ ）。 11 | 12 | 尽管如此，一般的约定是在你的Flask应用里使用 ``.html`` 后缀来命名你的HTML模板。 13 | 14 | 15 | 我怎么向模板添加自定义的JavaScript？ 16 | ----------------------------------- 17 | .. highlight:: jinja 18 | 19 | 使用Jinja2的 super_ 连同 ``scripts`` 块。这个super函数从父模板 20 | 添加块的内容，这种方式甚至可以让你决定是否想要在jQuery/bootstrap之前或之后加载。举例来说:: 21 | 22 | {% block bootstrap_js_bottom %} 23 | {{super()}} 24 | <script src="my_app_code.js"> 25 | {% endblock %} 26 | 27 | 28 | 为什么Bootstrap的JavaScript不加载？ 29 | ---------------------------------- 30 | 31 | 一个容易忽视的小错误是块名：尽管有一个块叫 ``body`` ，但它通常不是你想替换的那个， 32 | 你应该使用 ``content`` 。 一般地，JavaScript默认在 ``<body>`` 标签的 `最后 33 | <https://stackoverflow.com/questions/436411/where-is-the-best-place-to-put- 34 | script-tags-in-html-markup>`_ 加载 ）。 35 | 36 | :ref:`block-names` 有更多具体内容。 37 | 38 | 39 | 我如何向头部（header）添加自定义内容？ 40 | ------------------------------------- 41 | 42 | 一个经常冒出来的问题是如何添加自定义的内容到 ``<head>`` 元素，像 ``<link>`` 标签或是网站头像（favicon）。 43 | 通过使用 super_ 函数，这也很容易实现:: 44 | 45 | {% block head %} 46 | {{super()}} 47 | <link rel="icon" type="image/png" href="http://example.com/myicon.png"> 48 | {% endblock %} 49 | 50 | 这会刚好在关闭的 ``</head>`` 上面添加你想要的内容。 51 | 另一个用于大型项目的方法是创建一个新的基模板，然后自己添加需要的块:: 52 | 53 | 54 | {% block head %} 55 | {{super()}} 56 | {% block favicon %}<!-- 默认的网站头像（favicon）可以放到这里 -->{% endblock %} 57 | {% block feeds %}{% endblock %} 58 | {% endblock %} 59 | 60 | 然后，这个基模板的子模板可以使用这些块去指定一个自定义的feed或网站头像（favicon）。 61 | 62 | 63 | 我如何添加一个尾部（footer）？ 64 | -------------------------------- 65 | 66 | ``super()`` 函数也可以被用来扩展任何已经被定义的块。 67 | 为确定的样式创建另一个衍生的基模板通常是一个好主意。 68 | 一个例子 ``with-footer.html``:: 69 | 70 | 71 | {% extends "bootstrap/base.html" %} 72 | 73 | {%- block content %} 74 | {{super()}} 75 | {%- block footer %} 76 | <footer>© 2016 Awesome, Inc.</footer> 77 | {%- endblock footer %} 78 | {%- endblock content %} 79 | 80 | 所有扩展自 ``with-footer.html`` 的模板的 ``footer`` 块都将被覆盖。 81 | 82 | 83 | 我在部署时如何加载静态文件？ 84 | -------------------------- 85 | 86 | Flask-Bootstrap只是简单的添加一个叫 ``bootstrap`` 的蓝本，在这个意义上来说，它并不特别。 87 | 静态文件被匹配到一个特殊的URL前缀（默认为 ``static/bootstrap`` ）而且通过一个特定的文件夹提供， 88 | 这个文件夹可以在你的virtualenv安装包里找到（比如 ``lib/python2.7/site-packages/flask_bootstrap/static`` ）， 89 | 所以一个典型的安装将会是设定你的web服务器服务上面提到的文件夹的地址。 90 | 91 | 一个更优雅的解决方案是在WSGI服务器前放置一个缓存来处理 ``Cache-Control`` 报头。 92 | 默认情况下，Flask会在加载静态文件时附带一个12小时的过期时间 93 | （你可以使用 ``SEND_FILE_MAX_AGE_DEFAULT`` 改变这个值），这应该足够了。 94 | 95 | 这个方案可以使用 `nginx <http://nginx.org>`_ 96 | （或者，也许你更喜欢 `Varnish <http://varnish-cache.org>`_ ）或者他们的基于 97 | 相同工具的云服务应该也足够了。Flask-Bootstrap2.3.2.2通过提供查询字符串加速支持这些， 98 | 这确保当你更新Flask-Bootstrap时，更新版本的Bootstrap会被加载。 99 | （查看 ``BOOTSTRAP_QUERYSTRING_REVVING`` ） 100 | 101 | 102 | 我如何使用Bootstrap2/3？ 103 | ----------------------- 104 | .. highlight:: python 105 | 106 | 目前Bootstrap主要的稳定版本是3，很不幸，它不向后兼容Bootstrap2。除了版本3，Flask-Bootstrap 107 | 继续支持Bootstrap2的最新版本，（不过你不要期待有新特性，只是修正了漏洞而已。）当然，还有Bootstrap3。 108 | 109 | 通过安装Flask-Bootstrap，你将总是得到最新版本，即Boostrap3。要安装（或是保持）Flask-Bootstrap 2， 110 | 你必须在你的 ``setup.py`` 或 ``requirements.txt`` 里指定版本，类似这样:: 111 | 112 | # other stuff in setup.py 113 | # ... 114 | install_requires=['flask-bootstrap<3', 'another_package'] 115 | # ... 116 | 117 | 把Flask-Bootstrap固定为一个明确的版本是个好主意（例如 ``'flask-bootstrap==2.3.2.2'`` ，以此来避免生产环境中的意外）。 118 | 119 | 更多细节见 :doc:`bootstrap2` 文档。 120 | 121 | 122 | FontAwesome在哪里？ 123 | ------------------ 124 | .. highlight:: jinja 125 | 126 | 使用Bootstrap2的Flask-Bootstrap版本包含了 FontAwesome_ ，这对Flask-Bootstrap3和更高版本不再是一个问题。 127 | 128 | 起初，Bootstrap确实自带了基于图片的图标，不过它缩放的不好， 129 | FontAwesome通过提供一个基于矢量图的替代品和附加的图标修正了这个问题。 130 | 然而，从Bootstrap3开始，图标被作为字体再次包含了进来，基于这个原因FontAwesome被从扩展里去掉了，以便简化内容。 131 | 132 | 今天， FontAwesome_ 不再是唯一的选择，网上有一个对可选替代品的 `比较 133 | <http://tagliala.github.io/vectoriconsroundup/>`_ 。 134 | 135 | 如果你仍然想要使用FontAwesome，通过在你的继承自基模板的模板里增加style块，你可以很容易的包含它:: 136 | 137 | {% block styles -%} 138 | {{super()}} 139 | <link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet"> 140 | {% endblock styles %} 141 | 142 | .. _FontAwesome: http://fontawesome.io 143 | .. _super: http://jinja.pocoo.org/docs/templates/#super-blocks 144 | 145 | 146 | .. _jquery-faq: 147 | 148 | 为什么你附带了jQuery1而不是jQuery2？ 149 | ----------------------------------- 150 | 151 | 在我写这篇文档的时候（2014年七月），在jQuery1和2之间有两个主要的区别：版本1支持IE6-8， 152 | 然而版本2放弃了这些对支持旧版本的支持，换来了一个更小的内存占用和一下性能提升。市面上至少有20% 153 | 的浏览器（来源 `NetMarketShare 154 | <http://www.netmarketshare.com /browser- market- 155 | share.aspx?qprid=2&qpcustomd=0>`_ ）仍然含有不被jQuery2支持的版本。 156 | 157 | 158 | 除非你有特别需要，jQuery2的优点仍然不会大过它对市面上五分之一浏览器的不支持。 159 | 最后，Bootstrap和jQuery都是为了简化建站时处理问题的难度，而且这个目标能更好的达到， 160 | 离不开对jQuery1的广泛支持。 161 | 162 | 163 | 我如何使用jQuery2而不是jQuery1？ 164 | --------------------------------- 165 | 166 | .. highlight:: python 167 | 168 | 你可以使用Flask-Bootstrap的CDN支持来从不同的来源加载这些资源:: 169 | 170 | from flask_bootstrap import WebCDN 171 | app.extensions['bootstrap']['cdns']['jquery'] = WebCDN( 172 | '//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/' 173 | ) 174 | 175 | 这会加载 ``jquery.js`` 或任何指定的CDN上需要的文件。 176 | 如果你更想要传送你自己本地的jQuery版本，你可以使用类似于下面的代码片段:: 177 | 178 | from flask_bootstrap import StaticCDN 179 | app.extensions['bootstrap']['cdns']['jquery'] = StaticCDN() 180 | 181 | 注意在这个情况下你需要下载一个合适的 ``jquery.js`` 和/或 ``jquery.min.js`` ，然后把它放到你的程序的 ``static`` 文件夹。 182 | 183 | 上面的所有配置也会导致jQuery的 ``BOOTSTRAP_SERVE_LOCAL`` 选项被忽略。 184 | 如果你需要一个更加复杂的配置来支持这个选项，看一下 ``init_app`` 的源码和 :doc:`cdn` 的文档。 185 | -------------------------------------------------------------------------------- /docs/forms.rst: -------------------------------------------------------------------------------- 1 | WTForms 支持 2 | ============= 3 | 4 | ``bootstrap/wtf.html`` 模板包含了帮助你快速输出表单的宏。 5 | Flask-WTF_ 不是Flask-Bootstrap的依赖，但是必须被正确的安装。 6 | 在最近的几个版本中， Flask-WTF_ 的API变化很大，Flask-Bootstrap目前为 Flask-WTF_ 的0.9.2版本开发。 7 | 8 | 最基本的方式是把它们作为手动创建表单的助手。 9 | 10 | .. code-block:: jinja 11 | 12 | <form class="form form-horizontal" method="post" role="form"> 13 | {{ form.hidden_tag() }} 14 | {{ wtf.form_errors(form, hiddens="only") }} 15 | 16 | {{ wtf.form_field(form.field1) }} 17 | {{ wtf.form_field(form.field2) }} 18 | </form> 19 | 20 | 然而，你经常只是想快速生成一个表单，而且不需要过度的微调，可以直接使用 ``quick_form`` 宏:: 21 | 22 | {{ wtf.quick_form(form) }} 23 | 24 | 25 | 表单宏参考 26 | ---------- 27 | 28 | .. py:function:: quick_form(form,\ 29 | action=".",\ 30 | method="post",\ 31 | extra_classes=None,\ 32 | role="form",\ 33 | form_type="basic",\ 34 | horizontal_columns=('lg', 2, 10),\ 35 | enctype=None,\ 36 | button_map={},\ 37 | id="") 38 | 39 | 40 | 为一个完整的 Flask-WTF_ 表单输出Bootstrap-markup。 41 | 42 | :param form: 要输出的表单类实例。 43 | :param method: ``<form>`` 的method属性。 44 | :param extra_classes: 添加到 ``<form>`` 的类。 45 | :param role: ``<form>`` 的role属性. 46 | :param form_type: ``basic`` ， ``inline`` 或是 ``horizontal`` 之一。 47 | 关于不同表单样式的具体内容，见 Bootstrap_ 文档。 48 | :param horizontal_columns: 当使用水平定位的时候，像这样定位表单。必须是一个三元组： 49 | ``(column-type, left-column-size, right-colum-size)``. 50 | :param enctype: ``<form>`` 的enctype属性。如果设为 ``None`` 51 | 而且一个 :class:`~wtforms.fields.FileField` 出现在表单里， 52 | 这个值会被自动设置为 ``multipart/form-data`` 。 53 | :param button_map: 一个匹配按钮样式的字典，匹配按钮字段名称到 ``primary`` ， ``danger`` 或是 ``success`` 。 54 | 在 ``button_map`` 里没有找到的按钮会使用 ``default`` 类型（即 ``btn btn-default``）。 55 | :param id: ``<form>`` 的id属性。 56 | 57 | .. py:function:: form_errors(form, hiddens=True) 58 | 59 | 渲染包含表单错误消息的字段。这通常只用来输出隐藏字段表单的错误，因为其他的被附加到表单字段上了。 60 | 61 | :param form: 应该被渲染错误信息的表单。 62 | :param hiddens: If 如果设为 ``True`` ，也渲染隐藏字段的错误。 63 | 如果设为 ``'only'`` ， *只* 渲染这些。 64 | 65 | 66 | .. py:function:: form_field(field,\ 67 | form_type="basic",\ 68 | horizontal_columns=('lg', 2, 10),\ 69 | button_map={}) 70 | 71 | 渲染单个表单字段及周围的元素。主要通过 ``quick_form`` 使用。 72 | 73 | .. _Flask-WTF: https://flask-wtf.readthedocs.org/en/latest/ 74 | .. _Bootstrap: http://getbootstrap.com/ 75 | 76 | -------------------------------------------------------------------------------- /docs/index.rst: -------------------------------------------------------------------------------- 1 | =============== 2 | Flask-Bootstrap 3 | =============== 4 | 5 | .. tip:: 译者注：这个项目目前已经很久没有更新，而且不支持Bootstrap 4，你可以尝试使用一个更轻量的的替代品：`Bootstrap-Flask <https://github.com/greyli/bootstrap-flask>`_。 6 | 7 | Flask-Bootstrap 把 `Bootstrap <http://getbootstrap.com>`_ 打包进一个 8 | 扩展，这个扩展主要由一个叫“bootstrap”的蓝本（blueprint）组成。它也可以创建链接从一个CDN上引用Bootstrap资源。 9 | 10 | .. toctree:: 11 | :maxdepth: 3 12 | 13 | basic-usage 14 | configuration 15 | macros 16 | forms 17 | sqlalchemy 18 | nav 19 | cdn 20 | faq 21 | bootstrap2 22 | changelog 23 | translate 24 | 25 | 26 | 安装 27 | ---- 28 | 29 | Flask-Bootstrap 可以使用 ``pip`` 从 `PyPI 30 | <http://pypi.python.org/pypi/Flask-Bootstrap>`_ 上获取安装。建议使用 `virtualenv <http://www.virtualenv.org/en/latest/>`_ ——没有特别的原因，只是为了最佳实践。安装很简单:: 31 | 32 | pip install flask-bootstrap 33 | 34 | 开发用途可以克隆 `官方GitHub仓库 <https://github.com/mbr/flask-bootstrap>`_ 然后使用下面的命令安装:: 35 | 36 | python setup.py develop 37 | 38 | 39 | 起步 40 | ---- 41 | 42 | 直接去读 :doc:`基本用法 <basic-usage>` 吧。同时还有一份 :doc:`faq` 清单可供参阅。 43 | 44 | 在写这份文档时，最新的Bootstrap版本已经到了Bootstrap 3（现在已经是4了！）。 45 | 一个Flask-Bootstrap分支仍然支持Bootstrap2，具体细节在这里 46 | :doc:`bootstrap2` 。 47 | 48 | 49 | 版本笔记 50 | ---- 51 | 52 | Flask-Bootstrap 尝试跟随Bootstrap更新的脚步。版本变化的形式通常为 53 | ``<Bootstrap 版本>.<Flask-Bootstrap 版本>`` 。举例来说， 54 | 版本 ``2.0.3.2`` 集成了Bootstrap ``2.0.3`` 版本，并且是Flask-Bootstrap集成这个版本的第二次更新。 55 | 56 | 如果你需要让你的模板不改变，那么在你的setup.py里固定版本就可以了。 57 | -------------------------------------------------------------------------------- /docs/macros.rst: -------------------------------------------------------------------------------- 1 | 宏 2 | === 3 | 4 | .. highlight:: jinja 5 | 6 | Flask-Bootstrap和宏一起让你的生活更简单。它们需要像下面的例子里这样导入:: 7 | 8 | {% extends "bootstrap/base.html" %} 9 | {% import "bootstrap/wtf.html" as wtf %} 10 | 11 | 这会导入包含宏的模板 ``wtf.html`` 并简记为 ``wtf`` （这些在 :doc:`forms` 有一些讨论）。 12 | 13 | 除了这个页面上的较小的宏，对其他库也广泛支持。具体参见 :doc:`forms` 和 :doc:`sqlalchemy` 。 14 | 15 | 16 | 跨浏览器支持 17 | ----------- 18 | 19 | 跨浏览器支持（特别对Internet Explorer < 9的版本来说）通常是 20 | 必要的，但是Flask-Bootstrap没有附加这个功能。你可以下载 `html5shiv 21 | <https://raw.github.com/aFarkas/html5shiv/master/dist/html5shiv.min.js>`_ 和 22 | `Respond.js <https://raw.githubusercontent.com/scottjehl/Respond/master/dest/ 23 | respond.min.js>`_ ，把它们放在你程序的静态文件夹，然后像下面的例子那样包含它们 :: 24 | 25 | {% import "bootstrap/fixes.html" as fixes %} 26 | {% block head %} 27 | {{super()}} 28 | {{fixes.ie8()}} 29 | {% endblock %} 30 | 31 | 32 | 当这些脚本文件没有被包含的时候，会使用CDN链接。所以如果你没有使用 33 | ``BOOTSTRAP_SERVE_LOCAL`` ，它们会自动生效。具体见 :doc:`cdn` 34 | 这里有关于Flask-Bootstrap如何实现CDN设置的细节。 35 | 36 | 37 | Google Analytics 38 | ---------------- 39 | 40 | `Google Analytics <http://www.google.com/analytics/>`_ 的API最近变化的相当快，目前 41 | `analytics.js <https://developers.google.com/analytics/devguides/collection/analyticsjs/>`_ 42 | 是受支持最好的，使用 ``uanalytics(id, options='auto')`` 宏 :: 43 | 44 | {% import "bootstrap/google.html" as google %} 45 | 46 | {% block scripts %} 47 | {{super()}} 48 | {{google.uanalytics('U-XXXX-YY')}} 49 | {% endblock %} 50 | 51 | 可以传入选项给js函数 ``ga()`` 调用, 比如说利用 52 | `User ID <https://developers.google.com/analytics/ 53 | devguides/collection/analyticsjs/user-id>`_ 特性 :: 54 | 55 | {{google.uanalytics('U-XXXX-YY', {'userId': 'myUser'})}} 56 | 57 | 如果你想从外部配置Google Analytics的账户，可以这样 :: 58 | 59 | {{google.uanalytics(config['GOOGLE_ANALYTICS_ID'])}} 60 | 61 | 62 | .. note:: 请确保你至少正确验证（pseudomize）你的用户ID。 63 | 64 | 官方不赞成使用的 `ga.js 65 | <https://developers.google.com/analytics/devguides/collection/gajs/>`_ API 66 | 通过一个类似的叫做 ``analytics(account)`` 的宏被支持 :: 67 | 68 | {{google.analytics(account=config['GOOGLE_ANALYTICS_ID'])}} 69 | 70 | 71 | Utilities 72 | --------- 73 | 74 | 一些额外的模板宏可以在 ``bootstrap/utils.html`` 75 | 文件里获取。 和表单宏一样，这些是打算用来帮助快速开发应用的，在实际成熟的应用里，它们应该被合适的解决方案替换掉。 76 | 77 | .. py:function:: flashed_messages(messages=None, container=True, transform=..., default_category=None, dismissible=False) 78 | 79 | 渲染Flask的 :func:`~flask.flash` 消息。用常用的消息类别名称匹配稍不常用的Bootstrap CSS类名。 80 | （即： ``error -> danger`` ） 81 | 82 | :param messages: 一个消息的列表，如果没有给出，会使用 83 | :func:`~flask.get_flashed_messages` 重新获取它们。 84 | :param container: 如果设为True，会输出一个完整的 。 85 | ``<div class="container">`` 元素，否则只是每条消息被包裹进一个 ``<div>`` 里。 86 | :param transform: 一个匹配消息类别的字典。查询时对大小写敏感。 87 | 默认匹配所有Python loglevel级别的 *名称* 88 | 到Bootdtrap CSS类。 89 | :param default_category: 如果一个类别在transform里没有匹配，那么它会被直接传入，不作改变。 90 | 而如果设置了 ``default_category`` ，那么将会被替换为这个值。 91 | :param dismissible: 如果设为True， 将会输出一个关闭按钮到消息上 92 | 如果想要完整功能的可关闭的消息提示， 93 | 你需要使用JavaScript消息提示（alert）插件。 94 | 95 | 需要注意的是，要想让这些工作正常，显示的消息必须匹配一个有效的bootstrap消息类别。（也就是 ``success`` ， 96 | ``info`` ， ``warning`` ， ``danger`` 之一。） 97 | 98 | 举例来说： 99 | 100 | .. code-block:: python 101 | 102 | flash('Operation failed', 'danger') 103 | 104 | 3.3.5.7之前的Flask-Bootstrap的版本不对 ``flashed_messages`` 的内容进行转义，所以没法使用HTML。 105 | 这个规则已经改变了，现在推荐使用 ``Markup`` 包装器，可以让消息里的HTML生效： 106 | 107 | .. code-block:: python 108 | 109 | from flask import flash 110 | from markupsafe import Markup 111 | 112 | # ... 113 | 114 | flash(Markup('Flashed message with <b>bold</b> statements'), 'success') 115 | 116 | user_name = '<b>ad username' 117 | flash(Markup('<u>You</u> are our favorite user, <i>' 118 | + user_name 119 | + Markup('</i>!'), 120 | 'danger') 121 | 122 | .. py:function:: icon(type, extra_classes, **kwargs) 123 | 124 | 在一个 ``<span>`` 元素里渲染Glyphicon。 125 | 126 | :param messages: 图标的短名字，比如 ``remove`` 。 127 | :param extra_classes: 添加到类属性的附加类的列表 128 | :param kwargs: 附加的HTML属性 129 | 130 | 131 | .. py:function:: form_button(url, content, method='post', class='btn-link',\ 132 | **kwargs) 133 | 134 | 渲染一个被表单包裹的按钮/链接。 135 | 136 | :param url: 要提交到的端点（endpoint）。 137 | :param content: 按钮元素的内容。 138 | :param method: 周围表单的 ``method`` 属性。 139 | :param class: 按钮元素的 ``class`` 属性。 140 | :param kwargs: 按钮元素的额外HTML属性。 141 | 142 | 143 | 一个方便的小方法，可以用来创建像删除按钮这样的东西，而不用使用 ``GET`` 请求。 144 | 一个例子 :: 145 | 146 | {{form_button(url_for('remove_entry', id=entry_id), 147 | icon('remove') + ' Remove entry')}} 148 | -------------------------------------------------------------------------------- /docs/nav.rst: -------------------------------------------------------------------------------- 1 | Flask-Nav 支持 2 | ============== 3 | 4 | Flask-Nav_ 扩展可以让你很容易的创建导航构件，而且Flask-Bootstrap为此附带了一个与Bootstrap相 5 | 兼容的渲染器。一旦你初始化一个程序，Flask-Bootstrap默认会注册这个Bootstrap渲染器。 6 | 7 | 渲染一个简易的（"just works"）导航栏，举例来说 8 | 9 | .. code-block:: jinja 10 | 11 | {% block navbar %} 12 | {{nav.mynavbar.render()}} 13 | {% endblock %} 14 | 15 | 这会自动生成与Bootstrap相兼容的HTML代码。 16 | 一个生成能工作的导航栏的最小化的例子是这样的： 17 | 18 | .. code-block:: python 19 | 20 | from flask_nav import Nav 21 | from flask_nav.elements import Navbar, View 22 | 23 | nav = Nav() 24 | 25 | @nav.navigation() 26 | def mynavbar(): 27 | return Navbar( 28 | 'mysite', 29 | View('Home', 'index'), 30 | ) 31 | 32 | # ... 33 | 34 | nav.init_app(app) 35 | 36 | 你可以看看示例程序，它有关于导航的更加详细的例子。 37 | 38 | Bootstrap渲染器 39 | --------------------- 40 | 41 | 这个用来渲染Bootstrap式HTML的渲染器（通过 ``flask_bootstrap.nav.BootstrapRenderer`` 提供）有一些明确的特性。 42 | 换句话说，任何 :class:`~flask_nav.elements.Navbar` 的 ``title`` 属性也可以是一个 :class:`~flask_nav.elements.Link` 或 :class:`~flask_nav.elements.View` 。 43 | 44 | 如果 ``title`` 不是 ``None`` ，它会被使用 ``brand`` 类来渲染。（具体见 `Bootstrap docs 45 | <http://getbootstrap.com/components/#navbar-brand-image>`_ ） 46 | 而且如果它有一个 ``get_url`` 方法，那么它的返回值将会是 ``brand`` 文本的链接。 47 | 48 | 49 | 50 | 定制导航栏（navbar） 51 | ~~~~~~~~~~~~~~~~~~~ 52 | 53 | 如果想要修改 ``BootstrapRenderer`` 的输出，你可以创建子类，然后注册这个子类作为另一个渲染器。 54 | 你可以看看 Flask-Nav_ 的文档，那儿有 `关于这个话题的更多信息 <http://pythonhosted.org/flask-nav/advanced-topics.html#implementing-custom-renderers>`_ 。 55 | 56 | .. _Flask-Nav: http://pythonhosted.org/flask-nav 57 | -------------------------------------------------------------------------------- /docs/sqlalchemy.rst: -------------------------------------------------------------------------------- 1 | Flask-SQLAlchemy 支持 2 | ===================== 3 | 4 | `Flask-SQLAlchemy <https://pythonhosted.org/Flask-SQLAlchemy/>`_ 通过 5 | 它的 :meth:`~flask_sqlalchemy.BaseQuery.paginate` 对象支持分页。这些可以通过 ``render_pagination`` 宏自动渲染。 6 | 7 | .. code-block:: jinja 8 | 9 | {% from "bootstrap/pagination.html" import render_pagination %} 10 | 11 | {# ... #} 12 | 13 | {{render_pagination(query_results)}} 14 | 15 | .. py:function:: render_pagination(pagination,\ 16 | endpoint=None,\ 17 | prev='«',\ 18 | next='»',\ 19 | ellipses='…',\ 20 | size=None,\ 21 | args={},\ 22 | **kwargs) 23 | 24 | 为分页查询渲染一个分页导航。 25 | 26 | :param pagination: :class:`~flask_sqlalchemy.Pagination` 的实例。 27 | :param endpoint: 指定当一个页数被点击时要调用的端点。 28 | 将会用给定的端点和一个 ``page`` 参数调用 :func:`~flask.url_for` 。 29 | 如果设为 ``None`` 使用当前的请求端点。 30 | :param prev: “上一页”按钮使用的符号或文本。如果设为 ``None`` ，按钮将被隐藏。 31 | :param next: “下一页”按钮使用的符号或文本。如果设为 ``None`` ，按钮将被隐藏。 32 | :param ellipses: 指明跳过的页数使用的符号或文本， 33 | 如果设为 ``None`` ，则不显示指示符号。 34 | :param size: 可以是‘sm’或‘lg’，分别表示小的和大的分页导航。 35 | :param args: 传给 :func:`~flask.url_for` 的附加的变量。如果``endpoint`` 是 ``None`` ，使用 :attr:`~flask.Request.args` 和 36 | :attr:`~flask.Request.view_args` 。 37 | :param kwargs: ``<ul>`` 元素的额外属性。 38 | -------------------------------------------------------------------------------- /docs/translate.rst: -------------------------------------------------------------------------------- 1 | 翻译说明 2 | ========= 3 | 4 | 这是我第一次翻译技术文档，里面难免会有一些小错误，欢迎指正或者到Github上提交修改。 5 | 6 | - 个人主页：`greyli.com <http://greyli.com>`_ 7 | - 邮箱：withlihui@gmail.com 8 | - 项目Github地址： `github.com/greyli/flask-bootstrap-docs-zh <https://github.com/greyli/flask-bootstrap-docs-zh>`_ 9 | --------------------------------------------------------------------------------