D & Data

主要是获取一些(原始)数据的函数。 但实际上在一般模板的 API 调用中不会直接使用。
 data与d两者的 namespace 是一致的，一般建议使用d。

get_data

作用: 获得数据的主函数，一般posts、images获取数据的底层都是由get_data获得的。

接受的参数

参数名 说明 专用
types 文档类型, post、folder、image、file、template, 可使用`+`连接，比如`post+folder`，或者['post', 'folder']； 也可以单一类型，比如 `post` (默认值) -
path 默认为`/`(相当于站点根目录), 限定查询数据的路径，比如`path='docs/'`, 则表示仅查询docs/这个目录下的数据。 -
level 所在 path 的深度。如level=1，表示仅查询到其子目录，level=2，则仅查询子目录的子目录 -
sort 排序类型： '-date', 按时间倒序（默认值）； 'date', 按时间正序； 'position', 按照自定义位置正序；'-m_date', 按照文件最后修改时间倒序。 -
limit 一次取出多少条数据 -
render True 或不指定这个参数，这是比较特殊的参数，一般是呈现 post/folder/image 类型混合列表才会调用 -
return_one `True/False`, 如果 return_one为`True`， 则强制`limit=1`，并且最终不返回 list，而是返回单文档数据对象 -
return_count 默认为`False`, 如为`True`，整个查询不返回结果，仅返回一个匹配到的文档数。 -
page 取得第几页的数据，默认为1或者取URL中形如`/URL/page/`作为page的参数。 -
with_page 是否启用分页；如果为True（默认值），则limit将会被当做每页多少条 -
paginator_name 分页标记值，当前URL内可能会产生多个分页对象，调用get_data时为新创建的分页对象指定名称 -
date_start 文档的时间(即date字段)大于某个时间（不包括等于的情况） -
date_end 文档的时间小于某个时间（不包括等于的情况） -
min_posts_count 最少包含多少篇日志，针对post、folder类型的文档有效，所有的post类型，posts_count都为1 -
min_images_count 最少包含多少张图片，针对image、folder类型的，所有的image类型，images_count都为1 -
fields 一个列表型参数，比如`fields=["path", "title"]`, 返回的数据中会仅包含该指定的字段 -
excludes 针对已经获取得到的 list 类型数据，进一步排除能对应到`path`的处理 -
status 指定获取文章的status，默认为 'public'，如果是'all'，则为全部status，也可以是一个list，获得多个 status 的合集 post
url_path 自定义的url查询，如果使用这个参数，则仅返回一条结果或者空值 post
tags 日志标签，以是`'tag1+tag2'`或者`['tag1', 'tag2']`，两者等价 post

全文搜索参数

仅仅针对 post 类型 (文章) 的文档。

说明，sort & search 两个属性来专门用于搜索的扩展属性，都在文章的 Metadata 中声明。

keywords:
 这个查询是针对全文的搜索，关键词最多不超过50个字（会自动进行分词）。查询的范围包括标题、以及正文内容。
 使用keywords的时候，min_images_count、min_posts_count 这些参数不会生效；sort参数不支持 -m_date，另外可以使用两个新的sort参数，为sort与-sort(倒序)。

search_fields:
 这个是对keywords字段的补全，非全文搜索的情况下无效。默认值为['title', 'raw_content'], 表示对标题以及正文进行搜索。
 除了title、raw_content外，另外支持的一个字段是search。

注意:
 在页面内调用全文搜索的API时，可能会有一段时间 (一般10秒内) 用于全文分词索引建立，此时不会获得任何数据。一般情况下，并不影响实际使用。

参数说明及注意事项

0， 参数传入按需即可，不是所有参数都需要传入的；

1，当一个参数具有针对性的type (比如post专用) 的时候，那么多个 types 混合，其它类型的数据则无法获取，比如get_data(types='post+folder', status='public')，那么结果集中仅会有post类型的数据；

2，使用limit参数，会自动产生一个paginator（分页）的数据对象，如果使用limit的同时，也使用了page这个参数，则paginator对象不会产生

4，get_data 目的为了获得一个文档list的，一定要设置 paginator_name， 这样在后续调用分页数据的时候，就不会产生分页逻辑、数据混乱；

5，fieds: 一般在数据输出条数比较多，并且知道需要用到什么字段确定的情况下使用，可以提高 API 调用的性能，从而提高页面的渲染速度；

6，excludes: 比如excludes=['configs', 'hello']表示，如果获得的文档 list 中，排除 path 为cofnigs与hello的两个文档。其中比较特殊的一个值是_, 如果 exceluds 中有_，则表示排除所有path以_开头的文档(一般都是缓存类型的文件夹)；

7，render: post & image 的 render 属性始终为 True，而 folder 类型，如果其目录(或子目录) 包含 image 或 post，并且其本身不位于名称以_开头的特殊文件夹内，那么其 render 属性也为 True

8，level: 也支持[2,3]这样形式，表示查询所有2级以及3级的目录，不包含更深的路径，也不包含1级子目录；也接受>n 或者<n 类型的参数，比如>1，表示2级目录或以上

9，min_posts_count & min_images_count，于目录而言，如果目录名以_开始，则不会统计，比如_draft、_cache

示例代码

get_data 是Bitcron获取数据的核心API，本身非常灵活，有很多可能性。

包含年份日志数的archive

entries = get_data(type='post',limit=300, sort='desc').group('-date:year')
for year, year_posts in entries
    .year
        span= year
        year_start_date = '%s-1-1'%year
        year_end_date = '%s-1-1'%(year.int+1)
        yearly_count = get_data(type='post', return_count=True, date_start=year_start_date, date_end=year_end_date)
        span.yearly_count= "(%s)"%yearly_count
    ul.posts_in_year: for post in year_posts: li
        span.date= post.date.format("%m/%d")
        a(href=post.url, title=post.title)= post.title
+h.paginator()

1, 先通过get_data，获得300篇日志，按照日期的倒序；
 2，因为获得的是list类型的，所以，可以调用 group函数，产生年份，以及年份对应的子日志list；
 3，在循环中，获得了year之后，再产生一个年份的头尾，头为 year-1-1, 尾为次年的1-1，其实也可以(近似)当年的12-31，为了说明 year.int+1这种用法，示例里使用的是次年为尾；
 4，再次调用get_data, 声明return_count=True，并指定日期头尾，这样就能获得当前年份的日志的总数了；
 5，循环处理单篇日志在list内的构建；
 6，最后，不要忘记调用+h.paginator()处理分页信息。

注意，此Demo仅作为启发式，实际上，指定path参数，可以获得某个文件夹(分类)下的日志数、照片数、文件数，也可以进一步是某个年份、月份 & 某个文件夹下的日志数 .etc， 这个要视实际情况机动处理。

get_paginator

作用: 获得一个 Painator对象。
 参数: <index_or_name=0>，参数类型为整数或者字符串
 如果index_or_name是整数，表示获得当前页面的第几个分页对象(从0开始)；如果是字符串，则是指定名字的分页对象(一般是指d.get_data这个函数中的paginator_name参数)。

get_doc

作用: 获得一个文件的原始数据对象

参数 参数类型 说明
path 字符串(必须) 文件路径
match True(默认)/False `match=True`的情况下，路径是必须完全对应；反之则是**前向匹配**，比如`name`可以匹配`name.md`、`name.txt`、`name.jpg`
url 字符串 or None 如果指定了`url`，则是必定针对`post`类型的文档查询，是匹配 url 的，跟`path`、`match`两个参数将没有关系
type 字符串 or None 如果指定了type，即使最终得到了数据对象，但是数据类型(post、image、csv .etc) 不匹配，也会返回 None
as_context_doc True/False(默认) 如果获得了数据对象，并且这个数据对象会根据需要，自动统计 visits 等数据
root 字符串 or None 指定所在根目录，最终会和 `path` 共同补足最终的文件路径

has

作用: 判断某个文件、文档是否存在。
 参数: <path>

make_tree

作用: 将一个文档列表，根据各自 path (路径信息)，自动归档，如果是 folder 类型的，则会有children这个属性。
 注意: 文档列表里的每个文档数据，path与slash_number是必须的字段!

config_editor

作用: 主要是配置站点设置用到的函数，可以指定一个配置文件的路径，最终可以形成可以直接操作的 HTML 界面。
 参数: <path, keys, formats=None>
 说明: path是具体的配置文件(json 文件)的路径，keys 是具体的配置项。
 代码示例 (网站的一般配置项): 

{%
    set config_keys= ['title', 'sub_title',  'keywords@long_str',  'description@text',
                            'posts_per_page',  'images_per_page',  '-',
                            'post_content_type',  'post_paragraph_indent', 'show_toc@bool',                                                                   'hide_post_prefix@bool', '-',
                            'mathjax@bool', 'flowchart@bool', 'echarts@bool',]
%}
+d.config_editor("configs/site.json", config_keys)

update_json

作用: 可以指定一个json路径文件，然后更新其部分内容。
 参数: <path, **kwargs>
 示例: 

// 以下代码可以更新`hello.json`这个文件(如果不存在，则自动创建)，更新的内容是 title & content 这两个字段。当然，json 的结构本身是松散的，具体更新什么内容，由具体调用的时候，机动处理。
+d.update_json('hello.json', title="new title", content="new content")