函数与数据处理

函数的调用通过{{ function_name(v1, v2, v3=something, .etc) }}的语法，有些函数并不会返回值。
函数是晚于默认变量运行的，除非默认变量被嵌套在macro内，才会打破这个优先级。

文档处理

has

判断数据、文件有无的一个函数, 接受一个参数。

  1. has('posts') 网站中有无日志
  2. has('images') 网站中有无图片
  3. has('categories') 网站目录的1级子目录中有无日志的分类目录
  4. has(), 比如has('about.md')有无具体路径的文件

add_doc_actions

这里的doc是指post/image/file类型的数据对象。
执行这个函数并不会返回任何值，但可以让doc对象获取访问数统计、评论等功能。

{% set post=get_doc(type='post', path='this-is-article.txt') %}
{{ add_doc_actions(post) }}

那么当前URL被访问的时候，并且加上后面的action=xxx则会有特定的数据返回。（如果是日志，那么需要其status=='public'才会对以下几个action生效）

  1. URL?action=show_raw， 如果是post类型的，会返回文章的原始文字。
  2. URL?action=show_json, 如果是post类型的，会返回JSON格式的post数据。
  3. URL?action=edit, 如果是post类型，会跳转到Web版的编辑其中。

另外，通过POST的方式请求当前URL，则可以对该文档进行评论。

使用这个函数后，对应的doc文档在被访问的时候，其visits这个属性会+1.

put

接受3个参数，一个为path, 一个为content，以及from_url(表示从哪个地址下载，默认为None)。

put('hello.txt', 'this is content') 表示文件名为hello.txt，内容为this is content会增加，并重新推送回Dropbox端。

注意事项：

  1. 一个页面内，最多运行2个put函数；
  2. 5分钟内调用不能超过1,000次。
  3. 谨慎使用from_url，如果被系统侦测为恶意使用，当前账户会被直接封禁。

append

可以将一段文本增加到某个文本文件中，接受以下参数：

  • path: 文件路径(必须)
  • content: 需要增加的文字内容 (必须)
  • lines: 默认为1，最大值为10，表示与原来内容的间隔行
  • check: 默认为False，如果为True，表示最后一次append的内容被重复，则直接忽略
  • reverse: 默认为False，表示插入文件尾部；如果为True，则插入头部

开发者相关

开发者相关的函数，本身的权限比较大，后续只有特定的账户类型才能进行调用。

get_hash

接受任意参数，其中hashlib(默认为md5)与sort(默认为True)为特殊参数，前者表示散列的方式，支持md5或者sha1，后者表示是否对传入的参数进行排序。

代码示例(微信公众平台的验证):

rv = request.values
if rv.signature != get_hash('<your token>', rv.nonce, rv.timestamp, hashlib='sha1')
    +raise_404()

get_outbound_link_password

可以获取外链图片的密码，并且组装URL，做为outbound_link_password的GET参数。

get_outbound_link_password接受一个参数days，表示外链密码的有效期。默认为3天，days的取值范围为1-60（天）。

get_var/set_var

可以存储变量到当前网站，以实现一些特殊的定制。需要注意，这些变量并不会同步到Dropbox的存储中。

key与value不能过长（64字节内），变量总数不能超过100.如果value是数值，那么其应该是介于正负4294967296之间的。

通过set_var('test', 1)， 再get_var('test')得到的就是1了。

send_request

可以发送外部请求到其它网站。

接受以下参数：

  • url: 外部请求的URL
  • method: 默认为GET，也可以是POST
  • headers： 默认为{}, 可以指定特殊的头部信息
  • 其它k/v： 比如send_request(<url>, k1=v2, k2=v2), 后面可以跟任意k/v类型参数，如果GET则是自动补足倒URL中，如果是POST，则是作为data发送。

send_request会返回一个response对象，response=send_request('http://google.com/')， response则有以下字段：

  • text: 返回的数据，文本格式（如有必要，重新编码为utf8或unicode）。
  • status_code: HTTP状态码
  • cookies: resposne被目标URL写入的Cookie
  • headers: 返回的页面头部信息
  • json: 如果是json格式的话，可以直接调用
  • ok: 当前结果（即response））是否正常

注意事项:

  1. 如果被服务器认为属于外部攻击行为，则会被封禁当前账户。
  2. 不可用来进行proxy，特别是被GFW封禁的源站。
  3. 一个页面内最多不超过3次调用；5分钟内，最多不超过200次调用。
  4. 不要请求大尺寸文件（比如一张图片），页面首先会超时，其次会被认定一次危险行为。

timestamp_diff

timestamp_diff(<a unix timestamp>)， 可以返回当前时间与指定时间戳的相差秒数。

cronjob

接受一个参数hours，表示cronjob每隔几个小时运行，最小值为1，最大值为30.

如果一个页面中使用了cronjob这个函数，那么这个页面在第一次被访问（或者当前站长访问时）会被激活，之后再访问则会抛出400错误，而转为后台定时运行。

页面渲染相关的函数

load

这是一个快捷方式，可以载入多个CSS/JS文件，用空格隔开，比如load("/hello.css /word.js")会转化成以下HTML代码:

<link  type="text/css" rel="stylesheet" href="/hello.css"/>
<script type="text/javascript" src="/world.js"></script>

我们内置了以下快捷的资源：

name Lib Version
jquery Jquery 2.0.3
font Font Awesome 4.0.3
fonts Font Awesome 4.0.3
mathjax MathJax 2.3
pure Pure 0.3.0
essage Essage -

比如 load("jquery")就会自动载入Jquery 2.0.3的版本。

调用方法

load是懒人的用法，支持以下这些写法；万一最终解析的结果不正确，请使用原生的HTML写法。

  • load(<path or shortcut>)
  • load(<path or shortcut>, version)
  • load('<shortcut1>#version <shortcut2>#version')
  • load(<prefix_path>, [sub_filename, sub_filename2])
  • load( [<path or shortcut>, <path or shortcut 2>] )
  • load('<path or shortcut> <path or shortcut 2>')
  • load('<path or shortcut>, <path or shortcut 2>')
  • load('<path or shortcut> <path or shortcut 2>, <path or shortcut 3>')

get_request_path

可以获得当前URL偏移的路径，接受一个参数offset，默认值为1。
假设当前访问/requested/path/sub_path,那么：
1, get_request_path(offset=1) --> path/sub_path
2, get_request_path(offset=2) --> sub_path

但路径中有~~符的会特殊处理，永远都会以第一个~~作为计算offset的起点。
比如访问/requested/path/~sub_path/sub_sub_path, 那么:
1， get_request_path(offset=1) --> sub_path/sub_sub_path
2, get_request_path(offset=2) --> sub_sub_path

这个函数通常会和get_data配合使用，以获取通过URL传递的数据对象。

set_content_type

这个函数可以更改页面输出的类型，在输出JSON、XML等特殊类型页面的时候会有作用，这个函数本身不返回任何值。

比如JSON的页面{{ set_content_type('application/json') }}

set_no_inject

表示页面中不嵌入任何可能的代码（比如数学公式脚本、AutoReload脚本）。

redirect

接受一个参数url，比如{{ redirect('http://google.com')}}, 可以强制页面跳转到Google的主页。

raise_404

如果使用，将会触发404页面。不接受任何参数，调用方法为{{ raise_404() }}

权限相关

need_login

如果当前访客没有登录，会进行登录的跳转；反之则不返回值。

need_admin

  1. 如果当前访客没有登录，则进行登录的跳转；
  2. 如果已经登录，但不是网站的所有者，那么会提示出错；
  3. 如果已经登录，并且是网站的所有者，不返回任何值。

HTML生成函数

a_with_selected

会生成一个A标签的HTML代码片段，如复合匹配，它会有一个selected的class；接受参数(url, title, dom_id=None)。

  • url, 也就是href的值
  • title, 是包裹在A标签中的字符
  • dom_id, 如果有声明，则会是A标签的id值

自动生成一个A标签的HTML源码。

{{ a_with_selected('/hello', 'Hello, I am Title') }}

上面这段代码一般情况下，会生成<a href="/hello">Hello, I am Title</a>
在equal=False的情况下，如果当前访问的URL为/hello，则会生成<a href="/hello" class="selected">Hello</a>.

bread_nav

可以讲一个指定的path字符串，转为一段面包屑导航的HTML代码，接受参数(path, prefix='', prefix_name='/', split_by='/')。

  • path，指完整的路径
  • prefix，表示导航中所有超级链接的前缀
  • prefix_name表示第一级时候显示的文本
  • split_by表示各部分连接符。

假设<path> 为 /folder 22/img_3851.jpg；
那么 {{ bread_nav(path,'/folder/', prefix_name='Albums>'), split_by='>' }} 最终转化为一下HTML代码:

<ul class="bread_nav">
    <li>
        <a href="/folder/">Albums></a>
    </li>
    <li>
        <a href="/folder/folder 22/">folder 22></a>
    </li>
    <li>img_3851.jpg</li>
</ul>