H & HTML

h 这个 namespace 主要处理跟 渲染、HTML 相关的操作。html与h两者的 namespace 是一致的，一般建议使用h。

主要函数

load

作用: 载入前端 css、js、scss、coffeescript 资源，自动生成对应的 HTML 代码。
 注意: 相同的资源，相同的页面，最多只能载入一次，重复调用不会重复载入。

a

作用: 产生 A 标签元素(超级链接)，并且根据当前页面的 URL，给予selected等相应的 class name。
 参数: title, url, dom_id=None, must_equal=False, class="selected active current"
 参数说明:

  • title: 链接显示的内容
  • url: 链接的地址
  • dom_id: 一般不需要特别指定，如果指定了，则是对应的 Dom 的 ID
  • must_equal: True/False，如果是 True，则当前URL 必须要完全匹配；反之则只要前向匹配则可。
  • class: 如果当前页面 URL 和参数中的url一致对应，则 A 标签元素增加此 class name

js_view

作用: 可以产生一个链接元素，点击的时候，可以显示图片、在 iFrame 内浏览页面、播放视频。
 参数: title, url, group_id=None, view_type='', height=None, width=None, thumbnail=None
 参数说明:

  • title: 显示的文字内容, 也可以是是图片的地址。
  • url: 链接地址或者图片地址或者视频地址，如果 url 以.mp4结尾，view_type 默认作为video处理
  • group_id: 在 view_type='image'的时候起作用，表示一个组别，可以实现上一张、下一张
  • view_type: image、iframe、 video、qrcode、erweima，如果没有特别指定，默认作为iframe处理
  • thumbnail: 缩略图的 url，如果有指定 thumbnail，但未指定 view_type, 则 view_type 默认作为 image处理
  • height: 高度， 在 video 类型的时候有效
  • width: 宽度，在 video 类型的时候有效

auto_a

作用: 是介于js_view 和 a两个函数之间的，如果对应 href 比较适合 js_view 呈现，就会调用 js_view, 反之则调用a.
 参数: title, href, a_title=None, class_name='', group_id='', target="", dom_id=None

i18n

作用: 国际化的多语言对应
 示例: 

// 获得某个 key 的翻译，如果无法匹配，返回 key 本身
+h.i18n('key')
// 设定一个 key 的翻译，未指定语言，则作为默认值
+h.i18n('key', 'I am Key')
// 设定一个 key 的翻译，并指定了语言
+h.i18n('key', '我是 Key', 'zh_cn')

simple_form

作用: 能比较快地生成一个表单(Form)界面。
 参数: title, keys, data_obj=None, formats=None, info=None, submit_text=None, button_type="submit"
 参数说明:

  • data_obj: 如果有指定，则 data_obj 内的属性会对应到 keys，进行填充
  • info: 如果有指定，会呈现出错误信息的红字
  • button_type: 默认为 submit，点击会触发 POST 请求，也可以设定为button, 这样就不会触发提交，可以自己进一步在前端脚本中处理对应的点击行为。
  • submit_text: 点击按钮的文本内容
  • formats: 对 keys 呈现逻辑的补充，一般不需要设定。
  • keys: 一个list形式，比如[title, content], 这样 Form 就会呈现出两个字段来。content@textarea, 此类的 key 增加了@则表示此字段的表现形式。如果需要设定 placeholder，在反引号包裹内补充即可，比如"content@textarea`hello world`"。

注意: select 是 keys 中一个比较特殊的 key，因为本身不具备 placeholder 的属性，但是需要设定 options，因此这样的语法 keys=["title", "sites@select`site1,site2,site3`"] 可以对应一个 Select 类型的字段(value按次序分别为1,2,3)。

formats的说明

formats 可以具体决定一个字段在 form 中的表现形式，dict 形式，key 意义对应+h.simple_form 中传入的 key 值。根据不同的Dom类型，可设定的属性有不同的对应，一般有以下的值:
 type: select, text, list, password, textarea 其中之一
 placeholder: 一般 input、textarea 的最终 HTML DOM对应的 placeholder 属性
 default: 默认值
 options: 仅仅对 select 类型起作用，或者声明了这个属性的，当前视为 select 类型，为一个列表，列表内的元素也是一个(value, text)形式的列表。

这个属性的相对比较复杂，以下为系统默认提供的一个示例: 

formats = {
    'post_content_type': {
        'type': 'select',
        'options': [
            ('markdown', 'Markdown'),
            ('plain', 'Plain Text with Images'),
        ],
    },
    'post_paragraph_indent': {
        'placeholder': '0'
    },
    'posts_per_page': {
        'default': 3,
    },
    'cache_strategy':{
        'type': 'select',
        'options': [
            ('fast', 'Fast'),
            ('balance', 'Balance'),
            ('no', 'No'),
        ]
    },
}

grid_form

跟 simple_form 比较类似，但是会自动处理排版以及 callback 函数的对应。
 todo: 文档待补充...

json_view

作用: 将一个 data 数据，用 JSON 的格式进行呈现。
 参数: data, title=None, fields_to_remove=None
 参数说明:

  • data: 数据对象
  • title: 页面的标题
  • field_to_remove: 是一个 list 类型的数据，表示 data (如果是一个 dict 类型的话) 中哪些字段在呈现的时候需要被移除。

show

作用: 调用 show (模板)目录下的某个模板文件，一般是在 Markdown 文档中直接调用。
 参数: template_path, **kwargs
 具体用例请参考 此处

debug_template

当网站内的/template/目录下发生变化时，页面进行自动刷新或者 css 样式内容的自动重新渲染。
 一般情况，并不需要调用 +h.debug_template 这个函数，编辑模板的时候，进入网站设置中，将网站的 Debug 模式直接打开，效果也是一样的。

paginator

作用: 将一个Paginator对象转为HTML结构的源码。
 参数: <paginator=None, style="simple", pre_label='&laquo; Prev', next_label='Next &raquo;'>
 注意: 最终结果是字符串，并不是Paginator对象本身，不要尝试调用Paginator对象上的属性、命令，这会引发错误。

 paginator: 如果为None，默认提取当前页面的分页对象
 style: simple/min/auto 中一种，默认为 simple
 pre_label: 上一页的文字描述 (可为空，有默认值)，针对 mini/auto 两种样式有效
 next_label: 下一页的文字描述 (可为空，有默认值)，针对 mini/auto 两种样式有效

simple 样式

额外接受的参数:

  • show_page_of: 表示是否显示 Page 1 of 10 的信息，接受 False/True, 默认为 False

效果如图:

auto样式

表现形式: 会计算头尾两页，如果页码数过多，中间会进行自动的省略。
 额外接受的参数:

  • max_count，默认为10，表示可见的页码总数不超过10，可以设定 3-20 之间的数值；
  • omission_mark, 默认为 ...，表示到最后页面，超过 max_count 后需要进行省略，其表示的字符串

效果如图:

mini

表现形式: 根据当前页码，推算前几个页码，但不特定去计算所有页面的头、尾。
 额外接受的参数:

  • max_count，默认为5，表示可见的页码总数不超过5，可以设定 3-20 之间的数值；

效果如图:

前端类属性&函数

mobile_metas

实际上就是以下 HTML 源代码，以实现移动端的基本兼容 

<meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0" name="viewport"/>
<meta content="yes" name="apple-mobile-web-app-capable"/>
<meta content="black" name="apple-mobile-web-app-status-bar-style"/>
<meta content="telephone=no" name="format-detection"/>
<meta name="renderer" content="webkit">

headers

headers = h.mobile_metas + h.seo()

a_color

获得一个颜色(常作为背景色)

seo

必要的keywords & description的描述，主要是针对 SEO 或者其它内容被抓取时用到到的信息。
 可接受参数keywords, description, 比如 h.seo(seo_keywords, seo_description)。
 如果keywords 未传入，则会按照优先级尝试去匹配 post.metadata.keywords 与 site.configs.keywords ；如果 description 未传入，则也会依次去匹配 post.metadata.description 与 site.configs.description。

注意:
 1，在页面中，仅能调用一次 seo 这个函数，后续调用，会直接返回空字符；
 2，也要注意代码的上下次序，如果 post 这个变量没有调用之前已经调用了 h.seo，那么 post 本身就不会影响到 h.seo 这个函数的结果了；
 3，h.headers 会调用一次 h.seo()，也要注意模板代码本身的次序。

前端类函数

back_to_top

作用: 在页面右下角增加返回到头部的元素
 参数: <label='△'>

ajax

作用: 在某个指定的 Dom 上点击后，发送 Ajax 请求，并做进一步的 callback 处理
 参数: dom_id, url, method='get', data='', callback_func=''
 参数说明:

  • dom_id: 指定的 Dom ID
  • url: Ajax 请求的地址
  • method: get or post
  • data: 需要发送的内容
  • callback_func: 请求成功后，回调的函数名

auto_toc

作用: 传入一个文章的 dict 类型的数据对象，自动生成一个 TOC 的代码片段
 接受参数:

  • post: 日志(文章)的数据对象
  • top: 整数类型，可为空，表示 toc 栏距离顶部的高度(滚动条滚动这个高度之后，将处于固定位置)
  • fixed_top: 整数类型，可为空，表示 toc 栏处于固定位置时的 top 位置

注意:

  1. auto_toc 能实现滚动与当前toc的自动对应，但前提是已经设定好对应的 css 样式，一般页面的结构不要过于复杂
  2. top 这个参数可以不用传入，如果全局有一个 toc_offset_top 为名的 Javascript 的函数 (本身需返回一个整数值)，可以起到动态的作用。

auto_header

作用: 对class=auto_header的元素，如果页面产生滚动的时候，到达一定高度时候自动隐藏与显示。

fast

作用: 应用InstantClick技术，加快页面的预载入速度。
 注意: 这可能会造成网站额外的请求与页面浏览。

auto_sidebar

作用: 可以对一个指定的class=sidebar的元素，进行 sidebar 式的布局。
 参数: side='left', sidebar_name='sidebar', width=300, default_status="hide"