函数与数据处理
函数的调用通过{{ function_name(v1, v2, v3=something, .etc) }}的语法,有些函数并不会返回值。
函数是晚于默认变量运行的,除非默认变量被嵌套在macro内,才会打破这个优先级。
文档处理
has
判断数据、文件有无的一个函数, 接受一个参数。
- has('posts') 网站中有无日志
- has('images') 网站中有无图片
- has('categories') 网站目录的1级子目录中有无日志的分类目录
- 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生效)
URL?action=show_raw
, 如果是post类型的,会返回文章的原始文字。URL?action=show_json
, 如果是post类型的,会返回JSON格式的post数据。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端。
注意事项:
- 一个页面内,最多运行2个put函数;
- 5分钟内调用不能超过1,000次。
- 谨慎使用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))是否正常
注意事项:
- 如果被服务器认为属于外部攻击行为,则会被封禁当前账户。
- 不可用来进行proxy,特别是被GFW封禁的源站。
- 一个页面内最多不超过3次调用;5分钟内,最多不超过200次调用。
- 不要请求大尺寸文件(比如一张图片),页面首先会超时,其次会被认定一次危险行为。
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
- 如果当前访客没有登录,则进行登录的跳转;
- 如果已经登录,但不是网站的所有者,那么会提示出错;
- 如果已经登录,并且是网站的所有者,不返回任何值。
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>