Site

Site 对象,在直接调用site的时候,指向当前站点,另外也是account.sites获得列表的单个数据类型。

属性

基本属性

key 说明
id 站点 ID
title 网站标题
page_title 如果有设定网站根目录,则是目录名;反之则是网站的标题
account_id 站点对应的账户 ID
utc_offset 相对0时区的偏移,(-12.0~+12.0)
now 网站的当前时间,类型是 Date数据对象
configs 网站设置 (Dashboard) 中填入的各项配置,数据类型: `dict`
index_doc 根目录下以`index`为名的 Post 数据对象,如不存在,返回`None`
token 网站的API Token,凭此可拥有对网站的完全读、写权限
cronjobs 网站当前的 cronjob 列表, 数据类型为 `list`, 每个cronjob的数据对象类型为 Cronjob

域名相关属性

key 说明
domain 网站(单)域名, 这个域名总是处于可访问的状态,如果本身未验证,会在末尾自动增加 `.park.bitcron.com` 以保证可访问性
site_domain 相当于网站创建时输入的域名,属于不可变属性
domains 当前网站申明的域名 (包括未验证的), 数据类型为 list
root_domains 数据类型为 `list`,表示根域名,这个域名存在的话,其他账户就不能占用它了
valid_domains 数据类型为 `list`, 表示已验证的域名
invalid_domains 数据类型为 `list`, 表示未验证(待验证)的域名

图片、头像相关属性

key 说明
avatar 网站(作者)头像,实际上返回`/avatar.png`这个URL,但图片会进行尺寸的压缩(160*160),头像本身可在`网站设置(dashboard)`中进行设定。
site_avatar 网站头像,实际上返回`/site_avatar.png`这个URL,但图片会进行尺寸的压缩(240*240),头像本身可在`网站设置(dashboard)`中进行设定。
visitor_avatar 评论列表中,访客头像(非Bitcron用户邮箱能对应的头像),实际上返回`/visitor.png`这个URL,但图片会进行尺寸的压缩(80*80),头像本身可在`网站设置(dashboard)`中进行设定。
admin_avatar 评论列表中,网站作者头像,实际上返回`/visitor.png`这个URL,但图片会进行尺寸的压缩(80*80),头像本身可在`网站设置(dashboard)`中进行设定。
background_image 实际返回 `/bg.jpg` 这样的路径,可在`网站设置(dashboard)`中进行设定。 这个属性的调用与否,主要看不同模板的不同表现。

HTML 构建的属性

socials: 网站设置中配置了 Social ID,比如 twitter、微博等信息的,形成的 HTML 片段。
just_socials:site.socials 不同, 默认不会载入对应的图标字体文件。
nav: 网站导航的HTML片段,相当于 site.get_nav(auto_frontend=True)。
just_nav:site.nav不一同的是,默认不会载入导航的css样式,需要自行再定义。
footer: 网站设置中配置了底部栏的 HTML 片段。

site.tags

1,site.tags是按照标签对应的文章数,倒序输出,形如:

[('tag 1',3), ('tag 2', 1)]

2,site.tags模板代码示例:

for tag_name, tag_count in site.tags
    span= tag_name
    span= tag_count

3, site.tags统计的是所有staus=public的日志,同时,如果单个tag内含:字符的,则不算入内。

site.configs

site.configs 里的各项,实际上是不固定的,由模板设计者、使用者自行可以调配的;本文档仅对一些常规、默认的属性项进行说明。
有些属性实际上的值是None(不存在),因为尚未被用户配置过的原因。

key 说明
title 网站标题,同时也会设定到 site.title 中
sub_title 二级标题
keywords 一般无实质意义,主要针对 SEO;前提是在模板中被调用
description 同`keywords`
utc_offset 时区,等同 site.utc_offset
posts_per_page 每页文章数,针对输出文章列表的一些函数调用起作用
images_per_page 每页图片数,针对输出图片列表的一些函数调用起作用
post_content_type `plain` or `markdown`, 默认是`markdown`格式;如果是`plain`,则调用`post.content`这个属性的时候,会忽略 Markdown 语法(插图除外)。
post_paragraph_indent `整数`类型,单位`em`,表示文章的首行缩进。
hide_post_prefix `True/False`,文章的 URL 一般是`/post/xxxxx`,如果设定值为`True`,则对应的 URL 是`/xxxxx`
mathjax & flowchart & echarts 默认皆`False`,如果设定为`True`,则会载入对应的前端 JS 脚本,以渲染 Mathjax、Flowchat、Echarts 对应的片段。
theme 网站应用的主题名,类似`Wiki/Fit`,默认值一般为`Blog/Default`
cache_strategy 站点缓存策略
force_ssl 如果为`True`,则 `http://`形式访问的,强制跳转到对应的`https://`上
hide_comments 如果为 `True`,隐藏系统默认的评论系统。
nav_configs 用户设定的导航项,数据类型`list`,一般也在`导航(Navigation)`中可以通过拖拽的方式可视化的创建
footer 用户设定的页尾 HTML 代码片段
inject_template 用户设定的模板片段,可以被模板引擎渲染,而`footer`是纯 HTML 片段。

注意: 轻易不要调整 utc_offset 这个属性,它产生变化的时候,会影响网站全局时间的呈现;但已经产生、未修改的(时间)数据源则不会变化。一定程度上,这会产生认知上的偏差。

函数

refresh

作用: 更新当前site对象的数据
注意,一般不会使用到这个函数,除非需要对site内的configs进行配置,需要刷新最新的配置,才会调用。

delete

作用: 删除网站,需要输入账户密码进行确认
注意: 需要网站所有者出于登录时才能生效

update_token

作用: 更新当前网站的API Token,并返回最新的Token
注意: 只有在当前账户出于登录的前提下,该函数才会有用。

choose

创建一个站点选择的HTML片段,如果当前页面有when_site_chose这个javascript回调函数,则在使用者选择站点后调用这个函数,并传递一个site_id作为参数。

disable_nav

禁用导航栏,也就是调用 site.nav 不会获得任何内容。

get_nav

作用: 生成站点导航

参数 说明
meta_doc post 数据对象 (默认为当前文章),如果其 metadata 有设定 `nav` 这个 list 类型的属性,则以其为导航源
items 类似 [(name1, url1), (name2, url2)] 结构,表示指定的导航源
auto_frontend 默认为 True,表示自动载入一个导航相关的前端资源以呈现其样式
toogle_menu 默认为 False,若为 True,则表示当页面处于移动端设备宽度的时候,导航栏会自动收缩并可点击展开
as_items 默认为 False,表示生成的结果为 HTML;如果为 True,则返回一个 list,其中每个元素为 dict 类型,拥有 name & url 两个基本属性,用于自定义再构建导航的 HTML 代码片段

注意: 如果是用户自定义的导航,其优先级是最高的;如果都没有设定的话,则会自动推算,并且会将所有 status=page 的文章,作为导航中的一项。

Dashboard

configs 的设定

要实现 site.configs 上的各个属性,可以通过在网站目录下的configs文件夹内的 json 文件实现。
configs文件夹内对应的 json 文件内应该是简单的 key-value 结构,最后在同步到 Bitcron 的时候,会自动将对应的 key-value 更新到 site.configs 这个变量中。

Dashboard 的模板

一般来说,我们可以通过Bitcron 默认提供的Dashboard对网站进行设定。而你也可以实现自己的 Dashboard,因为本质上就是更新一个configs/xxxx.json的配置文件,从而扩展更多的自定义属性以实现各种可能。

以下为系统默认提供的Dashboard的页面源码:

html
    +account.need_admin()
    head
        +h.load('/fb_static/lib/pure.css')
        title= site.title or '?'
        +h.mobile_metas
        +h.load('/fb_static/service/dashboard/dash.css')
    body
        {%
            set dash_parts = [
                {
                    'title': 'Site',
                    'url': '',
                    'icon_css': 'fa fa-home',
                    'path': 'configs/site.json',
                    'fields': ['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',]
                },
                {
                    'title': 'Render',
                    'url': 'render',
                    'icon_css': 'fa fa-newspaper-o',
                    'path': 'configs/render.json',
                    'fields': ['theme', 'debug_template@bool', '-', 'cache_strategy', 'force_ssl@bool', 'hide_comments@bool', 'inject_template@text#200'],
                },
                {
                    'title': 'Social ID',
                    'url': 'social',
                    'icon_css': 'fa fa-user',
                    'path': 'configs/social.json',
                    'fields': ['twitter', 'instagram', 'dribbble', 'github', 'quora', 'flickr','weibo', 'facebook', 'vimeo', 'telegram', 'youtube', 'zhihu'],
                },
                {
                    'title': 'Advanced',
                    'url': 'advanced',
                    'icon_css': 'fa fa-wrench',
                    'path': 'configs/advanced.json',
                    'fields': ['admin_name', 'visitor_password`this is a plaintext password`', '-' , 'utc_offset', 'license_function', 'mail_sender`address from Mail Center`', '-', \
                        'domains@list#200`domains to bind, one domain per line`', 'subdomain@list#200`render a post under a subdomain`'],
                },

                {
                    'title': 'Payment',
                    'url': 'payment',
                    'icon_css': 'fa fa-money',
                    'path': 'configs/payment.json',
                    'fields': ['paypal_account','paypal_merchant_id', '-' ,\
                        'alipay_app_id', 'alipay_private_key@text#200`type <auto> to create one private key automaticlly`', 'alipay_public_key@text#100'],
                },
            ]
        %}

        url_path = request.path.split('/')[-1]
        current_part = dash_parts.filter('url', url_path, return_one=True) or dash_parts[0]
        
        .main.pure-g-r
            .menu.pure-u: .pure-menu.pure-menu-open
                a.pure-menu-heading.homepage(target='_blank', href='/') Home
                ul: for part in dash_parts: li
                    admin_url = "/service/admin/%s"%part.url
                    if request.args.site_id
                        admin_url = admin_url + '?site_id=' + request.args.site_id
                    a(href=admin_url, class="selected" if part.path==current_part.path else "")
                        i(class=part.icon_css)
                        span= _(part.title)
            .container
                .header
                    a#logout(href='/logout')
                        i.fa.fa-power-off
                        span= _('Logout')
                +d.config_editor(current_part.path, current_part.fields)
        +h.load('font')