├── documents
    ├── en
    │   ├── theme-dev.md
    │   ├── plugin-dev.md
    │   └── install.md
    └── cn
    │   ├── 手动升级文档.md
    │   ├── 安装指导文档.md
    │   ├── 插件制作文档.md
    │   └── 主题制作文档.md
├── .gitignore
├── .npmignore
├── installers
    ├── install_asp_v1.1.17.zip
    └── install_node_v1.1.17.zip
├── updaters
    ├── asp_1.1.15_to_1.1.17.zip
    ├── asp_1.1.16_to_1.1.17.zip
    ├── node_1.1.15_to_1.1.17.zip
    └── node_1.1.16_to_1.1.17.zip
├── CHANGE.log
├── package.json
├── README.md
└── README_en.md


/documents/en/theme-dev.md:
--------------------------------------------------------------------------------
1 | 待更新


--------------------------------------------------------------------------------
/documents/en/plugin-dev.md:
--------------------------------------------------------------------------------
1 | 待更新


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | .idea
2 | .DS_Store
3 | 


--------------------------------------------------------------------------------
/.npmignore:
--------------------------------------------------------------------------------
1 | .idea
2 | .DS_Store
3 | 


--------------------------------------------------------------------------------
/installers/install_asp_v1.1.17.zip:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Spikef/folk/master/installers/install_asp_v1.1.17.zip


--------------------------------------------------------------------------------
/updaters/asp_1.1.15_to_1.1.17.zip:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Spikef/folk/master/updaters/asp_1.1.15_to_1.1.17.zip


--------------------------------------------------------------------------------
/updaters/asp_1.1.16_to_1.1.17.zip:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Spikef/folk/master/updaters/asp_1.1.16_to_1.1.17.zip


--------------------------------------------------------------------------------
/updaters/node_1.1.15_to_1.1.17.zip:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Spikef/folk/master/updaters/node_1.1.15_to_1.1.17.zip


--------------------------------------------------------------------------------
/updaters/node_1.1.16_to_1.1.17.zip:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Spikef/folk/master/updaters/node_1.1.16_to_1.1.17.zip


--------------------------------------------------------------------------------
/installers/install_node_v1.1.17.zip:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Spikef/folk/master/installers/install_node_v1.1.17.zip


--------------------------------------------------------------------------------
/documents/cn/手动升级文档.md:
--------------------------------------------------------------------------------
 1 | # 手动升级Folk
 2 | 
 3 | ## 更新文件
 4 | 
 5 | 你可以在这里找到：[Folk升级包](https://github.com/envirs/folk/blob/master/updaters)
 6 | 
 7 | 根据自己安装的程序环境和版本，找到对应的升级文件zip压缩包。下载对应的压缩包并解压，将解压之后的文件替换到网站根目录。
 8 | 
 9 | ## 更新数据库
10 | 
11 | 手动升级无法更新数据库，当程序的中间一位版本号发生变化时，意味着需要更新数据库。这时候请使用升级程序进行升级。
12 | 
13 | ## 更新版本号
14 | 
15 | 用文本编辑工具打开`vision/configs.json`文件，将`version`字段的值改为新的版本号，如：`"1.0.16"`。
16 | 
17 | ## 重建缓存
18 | 
19 | 在后台首页点击【重建程序缓存】以完成更新。对于node版本，请重启服务。


--------------------------------------------------------------------------------
/CHANGE.log:
--------------------------------------------------------------------------------
 1 | 更新记录
 2 | 
 3 | v1.1.17
 4 | 默认编辑器增加上传附件功能
 5 | 优化默认编辑器上传图片功能
 6 | 优化默认编辑器文件上传功能，防止重复上传相同文件浪费网站空间
 7 | 修复default主题在没有友情链接数据时页面报错的bug
 8 | 增加上传图片添加水印功能，无需服务器安装图片操作组件
 9 | 增加默认编辑器设置功能
10 | 
11 | v1.1.16
12 | 修复debug模式下会重复显示已安装主题或插件的bug
13 | 打包安装程序时自动生成升级覆盖文件包
14 | 
15 | v1.1.15
16 | 改进了主题和插件的安装和卸载功能，主题和插件在安装之后将使用自定义目录，防止主题和插件文件外泄
17 | 增加主题和插件升级功能, 可以使用新版本主题/插件安装包升级主题和插件
18 | 将主题和插件的资源文件移动到统一的目录，解决了node版本在安装主题或者插件之后需要重启服务的问题
19 | 移除了后台的云平台用户登录功能，后台管理员只允许使用本地用户名和密码登录管理面板
20 | 增加了后台登录和解除锁定之后跳转进入登录前页面的功能
21 | 移除了发布日志成功之后自动跳转到日志页面的功能
22 | 修复了插件自定义参数的bug
23 | 修复了hook模块注册时的bug
24 | 增加主题和插件多语言支持功能
25 | 增加主题和插件文档多语言支持
26 | 增加主题和插件文档图片支持
27 | 修复网站访问权限无效的bug
28 | 修复插件请求处理模块的bug
29 | 修复后台导航语言显示的bug
30 | 更新fo-pack模块，并统一包文件后缀为.flk
31 | 修复主题和插件帮助文档页面显示代码不正常的bug


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "Folk",
 3 |   "description": "Folk is a lightweight, portable, powerful and highly customizable content publishing platform. The goal of folk is to share your minds with the worlds easily.",
 4 |   "version": "1.1.17",
 5 |   "author": "Spikef, evio",
 6 |   "homepage": "http://folk.webkits.cn",
 7 |   "repository": "https://github.com/envirs/folk",
 8 |   "keywords": [
 9 |     "blog",
10 |     "CMS",
11 |     "asp",
12 |     "node"
13 |   ],
14 |   "private": true,
15 |   "main": "index.js",
16 |   "scripts": {
17 |     "start": "node index.js",
18 |     "debug": "node index.js --debug"
19 |   },
20 |   "license": "MIT",
21 |   "dependencies": {
22 |     "body-parser": "^1.15.1",
23 |     "cookie-handle": "^1.0.3",
24 |     "crypts": "^1.0.2",
25 |     "ejs-lite": "^1.0.5",
26 |     "express": "^4.13.4",
27 |     "fnu": "0.0.2",
28 |     "fo-pack": "0.0.3",
29 |     "fs-arm": "0.0.1",
30 |     "node-database": "0.0.11",
31 |     "request": "^2.72.0",
32 |     "semver": "^5.1.0",
33 |     "serve-favicon": "^2.3.0",
34 |     "xss": "^0.2.13"
35 |   }
36 | }
37 | 


--------------------------------------------------------------------------------
/documents/cn/安装指导文档.md:
--------------------------------------------------------------------------------
 1 | # 安装Folk
 2 | 
 3 | ## 对于Node版本
 4 | 
 5 | ### 运行环境
 6 | 
 7 | `Folk(node)`基于[Node.js](https://nodejs.org/)(推荐版本>=4.0.0)开发，低版本的(>=0.10.x)[Node.js](https://nodejs.org/)理论上也是支持的，但是鉴于时间原因目前还未测试。
 8 | 
 9 | 在本地计算机上运行`Folk`非常简单，只需要先安装[Node.js](https://nodejs.org/)即可。
10 | 
11 | `Node.js`支持windows、linux和MacOS，因此`Folk`也可以运行于这些系统之上。
12 | 
13 | ### 关于Node.js
14 | 
15 | [Node.js](https://nodejs.org/)是一个基于Chrome JavaScript运行时建立的一个平台。[Node.js](https://nodejs.org/)是一个事件驱动I/O服务端JavaScript环境，基于Google的V8引擎，V8引擎执行Javascript的速度非常快，性能非常好。
16 | 
17 | 简单的说[Node.js](https://nodejs.org/)就是运行在服务端的JavaScript。以前，JavaScript只存在于浏览器端，而服务端编程则需要通过其它语言，如PHP或ASP来实现。现在，服务端与浏览器端可以使用同一种语言，这无疑大大降低学习成本。
18 | 
19 | ### 开始使用
20 | 
21 | 开始使用`Folk`最好的方式就是使用安装包，你可以在这里找到：[Folk安装包](https://github.com/envirs/folk/blob/master/installers)
22 | 
23 | ## 对于ASP版本
24 | 
25 | ### 运行环境
26 | 
27 | `Folk(asp)`需要运行在Windows Server的IIS之上，并需要以下四种数据库ODBC驱动中的一种：access，mssql，mysql或sqlite。
28 | 
29 | ### 关于ASP
30 | 
31 | Active Server Pages(ASP)，现在我们通常称为Classc ASP，是微软推出的第一代动态网站开发脚本引擎。无疑，ASP是古老而又过时的，但是鉴于国内的特殊环境，我们仍然有大量支持ASP的虚拟主机和很少支持Node.js的运行环境，所以我们仍然保留了兼容ASP的版本。
32 | 
33 | 我们的ASP版本基于[NodeAsp](https://github.com/Spikef/NodeAsp)，这是一个强大的ASP框架，它使得我们的两个版本的程序共用代码，互相兼容。
34 | 
35 | ### 开始使用
36 | 
37 | 开始使用`Folk`最好的方式就是使用安装包，你可以在这里找到：[Folk安装包](https://github.com/envirs/folk/blob/master/installers)


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Folk
 2 | 
 3 | > [Click here to read the English documents.](https://github.com/envirs/folk/blob/master/README_en.md)
 4 | 
 5 | Folk是一个轻量、便携，同时又很强大且可高度定制的内容发布平台。Folk的目标是：让您可以轻松地与世界分享您的点滴。
 6 | 
 7 | Folk使用世界流行的javascript语言开发，因此可以同时运行于node和asp(非.net)。其中，node版本支持sqlite(推荐)和mysql两种数据库，而asp版本则同时支持access、mssql、mysql和sqlite四种数据库。这两个版本的核心代码完全相同，因此对应的主题和插件也可以做到同时兼容。
 8 | 
 9 | Folk的核心程序是轻量的，只提供最基础的文章和用户功能，让您能够非常快速地上手。同时，Folk也支持自定义主题，让您的网站更加个性化。而强大的插件系统，则可以让您在Folk的基础上，扩展出您所能想像的任何功能，甚至将她变成一个cms系统。
10 | 
11 | Folk默认使用markdown语法来撰写日志，但是Folk也支持通过插件来使用可视化的html编辑器，让您自由选择、随心书写！
12 | 
13 | ## 快速安装手册
14 | 
15 | 1. 从install/目录下载对应版本的安装文件；
16 | 2. 将解压后的install文件夹（包括install文件夹本身）上传至网站根目录；
17 | 3. 对于asp版本，访问`http://您的域名/install`，然后根据提示进行安装；
18 | 4. 对于node版本，在命令行执行`node install`，然后根据提示进行安装；
19 | 5. 安装完毕，删除install目录。
20 | 6. 对于asp版本，访问`http://您的域名/control.asp`进入管理后台
21 | 7. 对于node版本，先`node index.js`启动网站服务，然后访问`http://您的域名/control`进入管理后台
22 | 
23 | ## 文档
24 | 
25 | * [详细安装:](https://github.com/envirs/folk/blob/master/documents/cn/%E5%AE%89%E8%A3%85%E6%8C%87%E5%AF%BC%E6%96%87%E6%A1%A3.md)
26 | 
27 | * [手动升级:](https://github.com/envirs/folk/blob/master/documents/cn/%E6%89%8B%E5%8A%A8%E5%8D%87%E7%BA%A7%E6%96%87%E6%A1%A3.md)
28 | 
29 | * [主题开发:](https://github.com/envirs/folk/blob/master/documents/cn/%E4%B8%BB%E9%A2%98%E5%88%B6%E4%BD%9C%E6%96%87%E6%A1%A3.md)
30 | 
31 | * [插件开发:](https://github.com/envirs/folk/blob/master/documents/cn/%E6%8F%92%E4%BB%B6%E5%88%B6%E4%BD%9C%E6%96%87%E6%A1%A3.md)
32 | 
33 | ## 开发计划
34 | 
35 | ### 云平台
36 | 
37 | 云平台是一个将广大博主形成联盟生态圈的线上系统，可以让用户在写作之余，方便地认识更多朋友、向更多志同道合的人展示自己的网站。
38 | 
39 | 同时，您还可以在云平台上分享或者出售您的主题、插件等，也可以在平台上广招英雄，来帮助您实现所需要的功能！
40 | 
41 | ### APP
42 | 
43 | 在今天这个移动互联网时代，随时随地使用手机分享自己此刻的想法或者拍下的照片，当然是必不可少的。所以，我们会在后续推出方便好用的配套APP，让这一切更加美好。
44 | 
45 | ## 关于PJBlog与Folk
46 | 
47 | PJBlog是一个历史悠久(源于2004年)的ASP博客程序，在国内有着广泛的用户基础。在经过十来年的发展之后，显然她已经有些跟不上时代的发展了。于是我们于2014年开始研发全新理念的PJBlog5, 并在两年后推出同时兼容node和asp平台的全新版本，并以Folk作为开发代号。
48 | 
49 | ## 版权与许可
50 | 
51 | PJBlog项目由陈子舜发起，Folk版本由沈赟杰和刘彬共同开发，因此版权归陈子舜、沈赟杰和刘彬共同所有。
52 | 
53 | 任何组织和个人在不移除版权标识及链接的前提下，可以免费使用；但是作为大型商业盈利用途的情况除外。
54 | 
55 | 任何组织和个人使用本程序发布的内容皆属于其自由意志，本程序开发团队不承担任何法律连带责任。


--------------------------------------------------------------------------------
/documents/en/install.md:
--------------------------------------------------------------------------------
 1 | # Install Folk
 2 | 
 3 | ## For the Node version
 4 | 
 5 | ### Environment
 6 | 
 7 | Folk(node) is built on [Node.js](https://nodejs.org/)(recommends version>=4.0.0), lower versions(>=0.10.x) are also supported but not being tested yet.
 8 | 
 9 | Running Folk locally on your computer is straight forward, but requires that you install [Node.js](https://nodejs.org/) first.
10 | 
11 | Node.js can run at both windows, linux and MacOS, so is the same as Folk.
12 | 
13 | ### About Node.js
14 | 
15 | [Node.js](https://nodejs.org/) is a modern platform for building fast, scalable and efficient web applications. Over the past 20 years, the web has evolved from a collection of static pages into a platform capable of supporting complex web applications like Gmail and facebook. JavaScript is the programming language which has enabled this progress.
16 | 
17 | [Node.js](https://nodejs.org/) provides us with the ability to write JavaScript on server. In the past JavaScript has only existed in the browser, and a second programming language, such as PHP or ASP, was required to do server side programming. Having a web application consist of a single programming language is a great benefit, and this also makes Node.js accessible to developers who might have traditionally stayed on the client side.
18 | 
19 | The way that [Node.js](https://nodejs.org/) makes this possible, is by wrapping up the JavaScript engine from Google’s Chrome browser and making it installable anywhere. This means that you can get Folk installed on your computer to try it out very quickly and easily.
20 | 
21 | ### Getting started
22 | 
23 | The best way to start Folk is using the installers. You can find them here: [Get Installers](https://github.com/envirs/folk/blob/master/installers).
24 | 
25 | ## For the ASP version
26 | 
27 | ### Environment
28 | 
29 | Folk(asp) requires Windows Server with IIS, and one of the following database ODBC drivers: access, mssql, mysql or sqlite.
30 | 
31 | ### About ASP
32 | 
33 | Active Server Pages(ASP), later known as Classic ASP or ASP Classic, is Microsoft's first server-side script engine for dynamically generated web pages. 
34 | 
35 | ASP use server-side scripting to generate contents that would be sent to the visitor's web browser. The ASP interpreter reads and executes all script code between <% and %> tags, the result of which is content generation. These scripts are written using `VBScript`, `JScript` and `PerlScript`. The `JScript`, which has the same syntax with `JavaScript`, is our choice.
36 | 
37 | ### Getting started
38 | 
39 | The best way to start Folk is using the installers. You can find them here: [Get Installers](https://github.com/envirs/folk/blob/master/installers).


--------------------------------------------------------------------------------
/README_en.md:
--------------------------------------------------------------------------------
 1 | # Folk
 2 | 
 3 | > [点击此处阅读中文文档.](https://github.com/envirs/folk/blob/master/README.md)
 4 | 
 5 | Folk is a lightweight, portable, powerful and highly customizable content publishing platform. The goal of folk is to share your minds with the worlds easily.
 6 | 
 7 | Folk is developed with javascript, one of the most popular language of the world.  It's divided into two versions of node and classic asp. The node version supports sqlite (recommended) and mysql databases, and the asp version supports four kinds of databases: access, mssql, mysql and sqlite. They share the same core codes so that the extensions can also be share.
 8 | 
 9 | The core of Folk is lightweight, it only supplies the base article and member management. This makes you start everything easily. Meanwhile, you can make your website more personalized by custom themes. And according to the powerful plugin system, you can extend any function based on Folk as you can imagine, even a cms.
10 | 
11 | Markdown is the first choice for writing on Folk. But WYSIWYG editor plugin is also available. It's totally freedom and as you like!
12 | 
13 | ## Quick Install
14 | 
15 | 1. Download the version your want from the install/
16 | 2. Unzip in the location you want to install
17 | 3. For the asp version, just visit `http://yourdomain/install`
18 | 4. For the node version, fire up a terminal and run `node install`
19 | 5. Delete the `install` folder after these steps for safe
20 | 6. For the asp version, just visit `http://yourdomain/control.asp` to get the control panel
21 | 7. For the node version, run `node index.js` on terminal to start the service，then visit `http://yourdomain/control` to get the control panel
22 | 
23 | ## Documents
24 | 
25 | * [Install:](https://github.com/envirs/folk/blob/master/documents/en/install.md)
26 | 
27 | * [Theme Develop:](https://github.com/envirs/folk/blob/master/documents/en/theme-dev.md)
28 | 
29 | * [Plugin Develop:](https://github.com/envirs/folk/blob/master/documents/en/plugin-dev.md)
30 | 
31 | ## Road Map
32 | 
33 | ### Cloud Platform
34 | 
35 | The Cloud-Platform is an online system to combine bloggers, that allows users to make more friends after writing, and show your website to more like-minded people.
36 | 
37 | At the same time, you can also share or sell your themes or plugins in the Cloud-Platform, or get some help to achieve the required functionality!
38 | 
39 | ### Mobile Application
40 | 
41 | Living in the mobile internet era, sharing your minds, words or photos by mobile phone at anytime and anywhere, is certainly essential. Therefore, we will launch an APP at the following time to make it all better.
42 | 
43 | ## About PJBlog
44 | 
45 | PJBlog is an old classic ASP blog program(since 2004) in China which has a broad customer base. After ten years of development, it's clear that she can't keep up with the times. So in 2014 we started to develop a new concept of PJBlog5, and launch a new version that is compatible with both node and asp after two years, using Folk as the development code name.
46 | 
47 | ## Copyright & License
48 | 
49 | The PJBlog project was initiated by PuterJam, and the Folk version was developed by Evio and Spikef, so these three guys share the copyright.
50 | 
51 | Any organization or individual can use it free without removing the copyright notice and links, except for large commercial usage.
52 | 
53 | Any organization or individual use the application to publish content is their free will, the development team does not assume any legally binding commitments.


--------------------------------------------------------------------------------
/documents/cn/插件制作文档.md:
--------------------------------------------------------------------------------
  1 | # Folk插件
  2 | 
  3 | 插件可以扩展Folk已有功能，满足更多自定义需求。
  4 | 
  5 | 习惯上，我们把插件简单地分类如下：
  6 | 
  7 | * 功能插件：仅仅实现某个功能，不体现在界面上（例如发布文章之后自动Ping搜索引擎）
  8 | * 后台插件：只在后台显示的插件（例如一个后台的音乐播放器）
  9 | * 模块插件：在某个页面的某个部分展示内容（例如提供一个侧栏广告模块）
 10 | * 页面插件：一个完整的独立页面（例如提供单页显示站长介绍的内容）
 11 | * 综合插件：综合以上多个功能而形成的插件（例如包含后台审核、侧栏显示、以及申请页面的友情链接功能）
 12 | 
 13 | Folk的插件文件放置于`vision/plugins`目录下。后台包含插件管理模块，自动列出所有的插件，可以对插件进行安装、启用、停用、卸载、删除、自定义参数和查看帮助文档等操作。
 14 | 
 15 | * [开始制作插件](#开始制作插件)
 16 | * [插件基础文件](#插件基础文件)
 17 | * [插件对外接口](#插件对外接口)
 18 | * [插件请求处理](#插件请求处理)
 19 | * [插件前台页面](#插件前台页面)
 20 | * [插件后台页面](#插件后台页面)
 21 | * [插件数据库](#插件数据库)
 22 | * [插件自定义安装和卸载](#插件自定义安装和卸载)
 23 | * [使用hook功能](#使用hook功能)
 24 | * [插件多语言支持](#插件多语言支持)
 25 | 
 26 | ## 开始制作插件
 27 | 
 28 | ### 开启debug模式
 29 | 
 30 | 默认情况下，只有经过官方认证的插件才能安装使用。因此，如果要制作插件，则需要开启`debug`模式。
 31 | 
 32 | 对于`asp`版本，开启的方式为：在后台首页，`设置程序功能` ⇨ `开启debug模式`。
 33 | 
 34 | 对于`node`版本，开启的方式为：使用`node index --debug`或者`npm run-script debug`启动应用。
 35 | 
 36 | > 注意：默认情况下，debug模式是关闭的，因为debug模式会略微影响程序性能，同时debug模式下会显示详细的错误信息，对程序安全性也有影响，因此，记得在制作完成插件之后关闭debug模式。
 37 | 
 38 | ### 新建插件
 39 | 
 40 | 在`vision/plugins`目录下新建一个目录用于保存新建插件的所有文件，目录名称需要和您的插件名称相同。
 41 | 
 42 | 然后，您就可以参照下面的教程往下一步一步地添加插件文件了！
 43 | 
 44 | ## 插件基础文件
 45 | 
 46 | 每套插件在安装之后都会保存在单独的目录中，插件目录名称可以随意，但为了兼容性考虑，所有目录名称和文件名请务必**不要使用中文和特殊字符**。
 47 | 
 48 | 一套插件包含以下基础文件：
 49 | 
 50 | * [插件LOGO图片](#插件LOGO图片)
 51 | * [插件信息文件](#插件信息文件)
 52 | * [插件配置文件](#插件配置文件)
 53 | * [插件帮助文档](#插件帮助文档)
 54 | 
 55 | ### 插件LOGO图片
 56 | 
 57 | `logo.png`用于在网站后台展示，通常建议尺寸为60×60左右。该文件必须包含，否则插件无法安装！
 58 | 
 59 | ### 插件信息文件
 60 | 
 61 | 插件信息保存在`package.json`文件中，`package.json`是一个完全符合JSON规范的json文件。
 62 | 
 63 | `package.json`文件中可能包含一些其它平台需要使用的字段信息，`Folk`只关注其中的以下字段。以下说明的字段中，除明确标明是可以省略的字段外，都是必需包含的。
 64 | 
 65 | #### name
 66 | 
 67 | 在`package.json`中最重要的就是name和version字段。他们都是必须的，如果没有就无法安装。name和version一起组成插件的唯一标志，更新插件的同时需要更新version。
 68 | 
 69 | name作为包名的同时，也是这个插件的名字，也是插件安装之后的目录名。
 70 | 
 71 | > 注意：name通常由小写字母, 数字以及`.-_`等符号组成. 不要使用中文, 大写字母和任何non-url-safe的字符.
 72 | 
 73 | #### version
 74 | 
 75 | 插件的版本号，必需符合[semver](https://docs.npmjs.com/misc/semver)规范。简言之，就是使用三个数字，中间用`.`隔开，例如：`1.0.0`。
 76 | 
 77 | > 注意：如果当插件无法升级时，请增加版本号的第一位，例如：从`1.2.12`变为`2.2.13`。
 78 | 
 79 | #### description
 80 | 
 81 | 插件描述信息，用于描述该插件的一些特性：插件类型，主要功能等。
 82 | 
 83 | #### homepage
 84 | 
 85 | 插件项目主页，可以是某篇日志的地址或者某个GitHub项目的地址，可以省略。
 86 | 
 87 | #### author
 88 | 
 89 | 插件作者信息，具体格式请参考下文的完整示例。
 90 | 
 91 | #### engines
 92 | 
 93 | 指定该插件支持的运行版本：`node`表示支持的Node.js的版本，例如“>=0.10.0”，同时意味着该插件支持node版本的Folk；`nodeasp`表示支持的NodeAsp的版本，例如“>=0.1.0”，同时意味着该插件支持asp版本的Folk；`folk`表示该插件支持的Folk的版本（可以在后台的右下角看到）。关于版本号的约束方式，请参考[semver](https://docs.npmjs.com/misc/semver)相关文档。
 94 | 
 95 | > 注意：当Folk进行了无法兼容之前主题或者插件的升级之后，中间一位的版本号会发生变更！
 96 | 
 97 | #### price
 98 | 
 99 | 插件售价，如果希望在云平台上出售您的插件以获取报酬的话，请填写该字段。该字段值的类型为数字，币种为人民币，单位为元。
100 | 
101 | #### mark
102 | 
103 | 插件标识，由程序自动生成，请勿手动添加或修改。
104 | 
105 | #### control
106 | 
107 | `control`用于声明插件后台管理页面导航，只有插件存在后台管理页面时才需要定义。
108 | 
109 | * `name`: 后台插件导航名称
110 | * `icon`: 后台插件导航图标，基于[fontawesome](http://fontawesome.io/icons/)图标字体。比如：`fa-envelope-o`
111 | * `hide`: 隐藏显示导航名称，但是仍然可以通过url访问
112 | * `pages`: 后台插件管理页面标识。比如我们填写 `list`，那么你插件文件夹下必须存在`views/list.ejs`这个文件。然后，用户就可以在后台的插件导航菜单进入该页面了。
113 | * `assets`: 管理页面需要额外加载的css文件和js文件。
114 | * `subs`: 插件二级管理导航，格式与一级导航相同。二级导航下还支持一级子导航。
115 | 
116 | > 注意: 关于ejs页面文件，请参考主题文档中ejs-lite模板引擎中的相关说明。
117 | 
118 | 插件管理导航示例：
119 | 
120 | ```json
121 | {
122 |     ...,
123 |     "control": {
124 |         "name": "评论留言管理",
125 |         "icon": "fa-envelope",
126 |         "subs": {
127 |             "list": {
128 |                 "name": "评论留言列表",
129 |                 "icon": "fa-envelope",
130 |                 "pages": "list",
131 |                 "assets": {
132 | 					"js": [
133 | 						"plugins/markdown/marked.js",
134 | 						"plugins/pinyin/pinyin.js",
135 | 						"plugins/prism/prism.js",
136 | 						"editor/file.input.js",
137 | 						"editor/selection.js",
138 | 						"editor/undo.js",
139 | 						"editor/editor.js",
140 | 						"editor/image.js"
141 | 					],
142 | 					"css": [
143 | 						"plugins/markdown/markdown.css",
144 | 						"plugins/prism/prism.css",
145 | 						"editor/editor.css"
146 | 					]
147 | 				}
148 |             },
149 |             "config": {
150 |                 "name": "评论通知设置",
151 |                 "icon": "fa-cogs",
152 |                 "pages": "config"
153 |             },
154 |             "test": {
155 |                 "name": "二级子导航",
156 |                 "subs": {
157 |                     "third1": {
158 |                         "name": "三级子导航1",
159 |                         "icon": "fa-qq"
160 |                     },
161 |                     "third2": {
162 |                         "name": "三级子导航2"
163 |                     }
164 |                 }
165 |             }
166 |         }
167 |     }
168 | }
169 | ```
170 | 
171 | #### navigator
172 | 
173 | `navigator`用于声明插件前台页面导航，只有插件存在前台页面时才需要定义。
174 | 
175 | * `name`: 前台插件导航名称
176 | * `icon`: 前台插件导航图标，基于[fontawesome](http://fontawesome.io/icons/)图标字体。比如：`fa-envelope-o`
177 | * `pages`: 前台插件页面标识，即主题中对应页面文件的文件名
178 | * `method`: 进入插件页面时自动执行方法名称，可以省略
179 | 
180 | **完整示例：**
181 | 
182 | ```json
183 | {
184 |     "name": "blog-link",
185 |     "description": "友情链接插件。",
186 |     "version": "1.0.0",
187 |     "homepage": "",
188 |     "price": 0,
189 |     "author": {
190 |         "name": "Spikef",
191 |         "email": "Spikef@foxmail.com",
192 |         "url": "http://www.xybk.net"
193 |     },
194 |     "engines": {
195 |         "folk": ">=1.0.1",
196 |         "node": ">=4.0",
197 |         "nodeasp": ">=0.1.0"
198 |     },
199 |     "control": {
200 |         "name": "友情链接插件",
201 |         "icon": "fa-link",
202 |         "pages": "bloglink"
203 |     },
204 |     "navigator": {
205 |         "name": "友情链接",
206 |         "icon": "fa-link",
207 |         "pages": "bloglink",
208 |         "method": "getPageList"
209 |     }
210 | }
211 | ```
212 | 
213 | **了解更多：**
214 | 
215 | * [关于JSON规范](http://json.cn/json.html)
216 | * [关于package.json](http://www.mujiang.info/translation/npmjs/files/package.json.html)
217 | 
218 | ### 插件配置文件
219 | 
220 | 插件可以提供一些参数选项供用户设置，以使插件可以满足不同用户需求，这些参数保存在`options.json`文件中。
221 | 
222 | `options.json`也是一个标准的JSON文件，每一个参数都是一个JSON对象，包含type、desc、info、value、items、source等，而其键名则作为该参数的名称供插件调用。具体请参考主题文档中的[主题配置文件](https://github.com/envirs/folk/blob/master/documents/cn/%E4%B8%BB%E9%A2%98%E5%88%B6%E4%BD%9C%E6%96%87%E6%A1%A3.md#%E4%B8%BB%E9%A2%98%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6)章节。
223 | 
224 | > 插件安装之后，这些参数的值可以在后台的插件设置中进行修改。
225 | 
226 | ### 插件帮助文档
227 | 
228 | 插件下面可以包含一个文件名为`README.md`的帮助文档，该文档为标准的[markdown](http://sspai.com/25137)文件，不支持表格、公式等扩展语法。
229 | 
230 | 为了便于链接到其它语言的帮助文档和添加图片，帮助文档在markdown语法的基础上支持如下两个特殊用法。
231 | 
232 | #### 链接到指定语言的帮助文档
233 | 
234 | 例如：插件下有名为`README_EN.md`的帮助文档，可以使用如下方式链接过去。
235 | 
236 | `[Click Here To Read The English Document]({filename:README_EN.md})`
237 | 
238 | #### 显示assets目录中的图片
239 | 
240 | 如果需要在帮助文档中显示图片，可以将图片存放在插件的assets目录中。
241 | 
242 | 例如：插件下有名为`assets/images/help.png`的图片，可以使用如下方式显示。
243 | 
244 | `![图片替换文本]({attachment:images/help.png})`
245 | 
246 | ## 插件对外接口
247 | 
248 | 插件对外接口文件`command.js`，是插件核心文件之一，主要提供方法接口。
249 | 
250 | 这是一个符合CommonJS的模块文件，插件作者在该模块内定义一系列方法，供主题或者其它模块调用。
251 | 
252 | 示例代码：
253 | 
254 | ```javascript
255 | /**
256 |  * Usage: 插件数据提供接口, 用于在主题中调用插件数据
257 |  * Author: Spikef < Spikef@Foxmail.com >
258 |  * Copyright: Envirs Team < http://envirs.com >
259 |  */
260 | 
261 | var db = blog.modules.db;
262 | 
263 | /**
264 |  * 获取侧栏友情链接数据, 返回数组或者false(无链接的情况下)
265 |  * @returns {Array|boolean}
266 |  */
267 | exports.getSideList = function(type) {
268 |     db.table(db.prefix + "links");
269 |     var data = false;
270 |     var top = this.options.topCount;
271 |     if (type !== 0 && type !== 1) {
272 |         if (typeof top === 'number' && top > 0) {
273 |             data = db.sel("*", "link_hide=0 and link_index<>0", "link_id desc", top).toJSON();
274 |         } else {
275 |             data = db.sel("*", "link_hide=0 and link_index<>0", "link_id desc").toJSON();
276 |         }
277 |     } else {
278 |         var link_type = type === 0 ? "link_type=0" : "link_type<>0";
279 |         if (typeof top === 'number' && top > 0) {
280 |             data = db.sel("*", "link_hide=0 and link_index<>0 and " + link_type, "link_id desc", top).toJSON();
281 |         } else {
282 |             data = db.sel("*", "link_hide=0 and link_index<>0 and " + link_type, "link_id desc").toJSON();
283 |         }
284 |     }
285 | 
286 |     return data;
287 | };
288 | 
289 | /**
290 |  * 获取页面友情链接数据, 返回数组或者false(无链接的情况下)
291 |  * @returns {Array|false}
292 |  */
293 | exports.getPageList = function() {
294 |     return db.select(db.prefix + "links", "*", "link_hide=0", "link_type desc, link_id desc").toJSON();
295 | };
296 | 
297 | /**
298 |  * 获取未通过的友情链接数目
299 |  * @returns {Number}
300 |  */
301 | exports.getHideList = function() {
302 |     var result = db.select(db.prefix + "links", "count(*) as c", "link_hide<>0").toJSON(0);
303 |     return result ? result.c : 0;
304 | };
305 | ```
306 | 
307 | Folk定义了唯一的全局变量`blog`，在插件模块文件中可以直接使用该对象。
308 | 
309 | * blog.folder: 网站所在二级目录名称
310 | * blog.system: `system`目录的绝对路径
311 | * blog.vision: `vision`目录的绝对路径
312 | * blog.engine: 系统运行引擎，返回`node`或者`asp`
313 | * blog.remote: 返回云平台域名，末尾无`/`
314 | * blog.domain: 返回当前网站域名，末尾无`/`
315 | * blog.server: 返回云平台完整域名，以`/`结束
316 | * blog.client: 返回当前网站完整域名，包含二级目录，以`/`结束
317 | * blog.version: 返回当前程序版本号
318 | * blog.settings: 返回后台网站设置保存的内容
319 | * blog.user: 返回当前用户信息
320 | * blog.theme: 返回当前主题信息
321 | * blog.modules.db: 数据库操作模块(database或node-database)
322 | * blog.modules.fs: 文件操作模块(fs-plus)
323 | * blog.modules.path: 路径操作模块(path)
324 | * blog.modules.url: URL操作模块
325 | * blog.modules.hook: HOOK操作模块
326 | 
327 | 另外，模块有三个对象`this.pid`(插件在数据库中的id)，`this.options`(插件自定义参数)和`this.lan`(插件多语言支持方法)可以在模块内的方法中直接使用。
328 | 
329 | 如果该模块只有一个对外方法，也可以这么写。
330 | 
331 | ```javascript
332 | module.exports = function() {
333 |     // your codes here
334 | }
335 | ```
336 | 
337 | 程序在调用该模块时，不会使用`new`来实例化它，而是会将`this`对象指定为模块本身，因此不要将模块方法绑定到模块对象的`prototype`对象上，而应该使用类似下面的方式。
338 | 
339 | ```javascript
340 | var cmd = module.exports = function() {
341 |     this.init();    // this = cmd
342 | }
343 | 
344 | cmd.init = function() {
345 |     // your codes here
346 | }
347 | ```
348 | 
349 | 该模块内部的方法可以返回任意格式的结果，除了`null`。
350 | 
351 | ## 插件请求处理
352 | 
353 | 插件请求处理文件`service.js`，主要处理前端数据请求。通俗地讲，就是用于处理表单提交数据和返回Ajax请求数据的。
354 | 
355 | 该文件不能直接与前端通信，必须通过中间文件，这些中间文件在Folk中被称之为虚拟机。虚拟机说明如下：
356 | 
357 | * request: 同步虚拟机，当方法直接返回结果数据时使用
358 | * async: 异步虚拟机，当方法需要异步等待，并将结果数据作为参数传入回调函数时使用
359 | 
360 | > 使用何种虚拟机由请求发起方完成，插件作者只需要告知即可。
361 | 
362 | 为了安全考虑，通过虚拟机传入参数时，会自动对html代码和SQL关键字进行转义。如果需要获取转义前的原始内容，请使用`fnu`模块中的`decodePost`方法反向转义。
363 | 
364 | 该模块的写法与[插件对外接口](#插件对外接口)模块的写法完全一致，区别在于该模块内部的方法在执行时会自动传入参数。对于同步方法，将自动传入`req`和`res`两个参数；对于异步方法，将自动传入`req`，`res`和`callback`三个参数。
365 | 
366 | * req: 请求数据，包括HTTP请求头、URL请求参数、POST请求内容、Cookie等。
367 | * res: 输出对象，包括设置HTTP头、输出页面、跳转页面、Cookie等。
368 | * callback: 回调方法，必须传入JSON数据作为参数来调用。
369 | 
370 | 示例代码：
371 | 
372 | ```javascript
373 | exports.jump = function(req, res) {
374 |     if (!blog.settings.appKey || !blog.settings.appToken) {
375 |         return {
376 |             success: false,
377 |             message: '登录失败，请先设置appKey和appToken!'
378 |         }
379 |     }
380 | 
381 |     var from = req.query.from || blog.client;
382 |     var bind = blog.modules.url.setUrl('api', 'async', {name: 'cloud-user', method: 'jump', from: from, bind: blog.user.id});
383 | 
384 |     if (blog.user.status > 0 && !blog.user.openid && req.query.bind != blog.user.id) {
385 |         blog.modules.db.close();
386 |         var html = blog.modules.fs.readFileSync(blog.modules.path.resolve(__dirname, 'page/confirm.html'), 'utf8');
387 |         html = html.replace('{url_from}', from).replace('{url_bind}', bind);
388 |         res.setHeader('Content-Type', 'text/html;charset=utf-8');
389 |         res.end(html);
390 |         return false;
391 |     } else {
392 |         var fnu = require('fnu');
393 |         var sha1 = require('crypts/lib/sha1');
394 |         var code = sha1(blog.configs.secret.substr(0, 20) + fnu.getIP(req));
395 |         var stamp = Math.floor(Date.now() / 10000);
396 |         var state = sha1(blog.configs.secret.substr(0, 20) + code + stamp);
397 |         var option = {httpOnly: true, path: '/' + blog.folder};
398 |         res.cookie('cloud_user_jump_code', code, option);
399 | 
400 |         var options = {
401 |             client_id: blog.settings.appKey,
402 |             client_secret: blog.settings.appToken,
403 |             remote: blog.remote,
404 |             local: blog.modules.url.setUrl('api', 'async', {name: 'cloud-user', method: 'login', from: from})
405 |         };
406 | 
407 |         var sdk = new SDK(ajax, options);
408 |         var url = sdk.authorize(state);
409 | 
410 |         blog.modules.db.close();
411 |         res.redirect(url);
412 |         return false;
413 |     }
414 | };
415 | 
416 | exports.login = function(req, res, callback) {
417 |     if (!req.query.from || !req.query.state || !req.cookies['cloud_user_jump_code']) {
418 |         callback({
419 |             success: false,
420 |             message: '登录失败, 不正确的请求来源或请求已过期!'
421 |         });
422 |         return;
423 |     } else {
424 |         var fnu = require('fnu');
425 |         var sha1 = require('crypts/lib/sha1');
426 |         var code = sha1(blog.configs.secret.substr(0, 20) + fnu.getIP(req));
427 |         var state = req.query.state;
428 |         var stamp = Math.floor(Date.now() / 10000);
429 |         var wrong = true;
430 |         if (code === req.cookies['cloud_user_jump_code']) {
431 |             for (var i=0; i<=12; i++) {
432 |                 if (sha1(blog.configs.secret.substr(0, 20) + code + stamp) === state) {
433 |                     wrong = false;
434 |                     break;
435 |                 }
436 |                 stamp--;
437 |             }
438 |         }
439 |         if (wrong) {
440 |             callback({
441 |                 success: false,
442 |                 message: '登录失败, 不正确的请求来源或请求已过期!'
443 |             });
444 |             return;
445 |         }
446 |     }
447 | 
448 |     var options = {
449 |         client_id: blog.settings.appKey,
450 |         client_secret: blog.settings.appToken,
451 |         remote: blog.remote,
452 |         local: blog.modules.url.setUrl('api', 'async', {name: 'cloud-user', method: 'login'})
453 |     };
454 | 
455 |     var sdk = new SDK(ajax, options);
456 | 
457 |     var data = {}, that = this;
458 |     sdk.token(req.query.code, function(err, tokens){
459 |         if (err) {
460 |             callback(err);
461 |             return;
462 |         }
463 | 
464 |         data.tokens = tokens;
465 |         sdk.openid(tokens.access_token, function(err, openid){
466 |             if (err) {
467 |                 callback(err);
468 |                 return;
469 |             }
470 | 
471 |             data.openid = openid;
472 |             sdk.userinfo(tokens.access_token, openid, function(err, info){
473 |                 if (err) {
474 |                     callback(err);
475 |                     return;
476 |                 }
477 | 
478 |                 data.info = info;
479 | 
480 |                 // 判断邮箱是否已存在
481 |                 var params, exist = [], id;
482 | 
483 |                 params = {
484 |                     fields: "user_id, user_cloud_openid",
485 |                     wheres: "user_mail='" + info.user_mail + "'"
486 |                 };
487 |                 blog.modules.db
488 |                     .select(blog.configs.prefix + "members", params.fields, params.wheres)
489 |                     .forEach(function(object) {
490 |                         exist.push(object)
491 |                     });
492 | 
493 |                 if (exist.length) {
494 |                     for (var i=0, len=exist.length; i<len; i++) {
495 |                         if (exist[i].user_cloud_openid != data.openid) {
496 |                             if (blog.user.status === 0) {
497 |                                 callback({
498 |                                     success: false,
499 |                                     message: '邮箱与其他用户重复，如果该邮箱账户属于您自己，请先用本地用户登录，然后再重新授权。'
500 |                                 });
501 |                             } else {
502 |                                 id = exist[i].user_id;
503 |                             }
504 |                             break;
505 |                         }
506 |                     }
507 |                 } else if (blog.user.status > 0) {
508 |                     id = blog.user.id;
509 |                 }
510 | 
511 |                 // 判断openid是否已存在
512 |                 var User = require(blog.modules.path.resolve(blog.system, 'library/user'));
513 |                 params.wheres = "user_cloud_openid='" + data.openid + "'";
514 |                 exist = User.select(params);
515 |                 if (exist) id = exist.user_id;
516 | 
517 |                 // 获取用户详细地址
518 |                 info.user_province = info.user_province || '';
519 |                 info.user_city = info.user_city || '';
520 |                 info.user_area = info.user_area || '';
521 | 
522 |                 var cities = require('./libs/city_cn.json');
523 |                 var address = [];
524 |                 if (info.user_province && cities[info.user_province]) address.push(cities[info.user_province]);
525 |                 if (info.user_city && cities[info.user_city]) address.push(cities[info.user_city]);
526 |                 if (info.user_area && cities[info.user_area]) address.push(cities[info.user_area]);
527 |                 if (info.user_address) address.push(info.user_address);
528 | 
529 |                 var user = {
530 |                     user_nick: data.info.user_nick,
531 |                     user_avatar: data.info.user_avatar,
532 |                     user_sex: Number(data.info.user_sex) || 0,
533 |                     user_mail: data.info.user_mail,
534 |                     user_website: data.info.user_website,
535 |                     user_mobile: data.info.user_telphone,
536 |                     user_group: that.options.group,
537 |                     user_address: address.join(' '),
538 |                     user_login_date: new Date(),
539 |                     user_login_local: require('fnu').getIP(req),
540 |                     user_cloud_openid: data.openid,
541 |                     user_cloud_expire: new Date(Number(data.tokens.expires_in)),
542 |                     user_cloud_token: data.tokens.access_token,
543 |                     user_cloud_refresh: data.tokens.refresh_token
544 |                 };
545 | 
546 |                 if (data.info.user_birthday) {
547 |                     user.user_birthday = new Date(data.info.user_birthday);
548 |                 }
549 | 
550 |                 if (id) {
551 |                     delete user.user_group;
552 |                     User.update(user, id);
553 |                 } else {
554 |                     id = User.insert(user);
555 |                 }
556 | 
557 |                 var expire = new Date(Number(data.tokens.expires_in));
558 |                 var option = {httpOnly: true, expires: expire, path: '/' + blog.folder};
559 |                 var openid = hash(data.openid);
560 |                 var token = hash(data.tokens.access_token);
561 |                 res.cookie('user_id', id, option);
562 |                 res.cookie('user_openid', openid, option);
563 |                 res.cookie('user_token', token, option);
564 | 
565 |                 // 登录成功
566 |                 blog.modules.db.close();
567 |                 res.redirect(req.query.from);
568 |             });
569 |         })
570 |     });
571 | 
572 |     return false;
573 | };
574 | 
575 | exports.logout = function(req, res) {
576 |     res.clearCookie('user_id', {path: '/' + blog.folder});
577 |     res.clearCookie('user_openid', {path: '/' + blog.folder});
578 |     res.clearCookie('user_token', {path: '/' + blog.folder});
579 | 
580 |     blog.modules.db.close();
581 |     res.redirect(req.query.from);
582 | };
583 | ```
584 | 
585 | 如上代码所示，如果是跳转页面，则需要在跳转之前调用`blog.modules.db.close()`方法关闭数据库连接。对于同步方法，应该返回JSON格式的数据，或者返回false(当需要直接输出HTML页面或者跳转页面时)。对于异步方法，没有返回值，而是直接调用`callback`回调函数。
586 | 
587 | 需要注意的是：
588 | 
589 | * 对于POST请求，使用参数名称(`req.body.name`)来获取请求数据。
590 | * 对于表单提交，使用表单控件名称(`req.body.name`)来获取请求数据。
591 | * 当需要判断用户是否具有权限的时候，可以使用`blog.user.hasLimit(mark)`方法。
592 | 
593 | ## 插件前台页面
594 | 
595 | 插件前台页面是指页面插件需要在前台显示的页面，例如留言本插件，需要提供一个独立的页面来显示留言内容，这个页面就属于插件前台页面。
596 | 
597 | 插件前台页面由主题作者完成，插件作者只需要按照约定在`package.json`中声明`navigator`字段即可。
598 | 
599 | ## 插件后台页面
600 | 
601 | 某些插件可能需要后台管理页面，例如评论审核功能，这些页面保存在该插件下的`views`目录中，文件后缀名为`ejs`。更多关于`ejs-lite`模板渲染引擎请查看[主题制作文档相关章节](https://github.com/envirs/folk/blob/master/documents/cn/%E4%B8%BB%E9%A2%98%E5%88%B6%E4%BD%9C%E6%96%87%E6%A1%A3.md#%E6%A8%A1%E6%9D%BF%E5%BC%95%E6%93%8E)，或者[ejs-lite模板引擎](https://github.com/Spikef/ejs-lite)文档。插件后台管理页面并不是一个完整的独立页面，而是内嵌在系统管理后台页面中的一部分。
602 | 
603 | 后台管理页面需要额外加载的css文件和js文件，存放在该插件的`assets`目录下。
604 | 
605 | 后台管理页面脚本模块保存在该插件的`scripts`目录下，文件名与对应的`.ejs`文件相同，后缀为`.js`。加载插件管理页面之前将自动执行该模块中的`module.exports`方法，并将该方法返回的数据绑定到页面。同样，该模块也有三个对象`this.pid`(插件在数据库中的id)，`this.options`(插件自定义参数)和`this.lan`(插件多语言支持方法)可以在模块内的方法中直接使用。
606 | 
607 | ```javascript
608 | var db = blog.modules.db;
609 | 
610 | module.exports = function() {
611 |     var data = {};
612 |     var list = db.select(db.prefix + "links", "*", "", "link_id desc").toJSON();
613 |     data.list = list || [];
614 | 
615 |     return data;
616 | };
617 | ```
618 | 
619 | 这样，在页面中就可以直接使用`list`数据了。
620 | 
621 | ```html
622 | <%list.forEach(function(item) {%>
623 | <div class="col-md-4 blogLink" data-hide="<%=item.link_hide%>" data-index="<%=item.link_index%>">
624 |     <div class="items">
625 |         <!-- other html codes -->
626 |     </div>
627 | </div>
628 | <%});%>
629 | ```
630 | 
631 | ## 插件数据库
632 | 
633 | 当插件需要使用自定义数据库时，可以在该插件根目录中添加`table.json`文件来定义。为了保证程序的正常运行与升级，插件数据库是独立于系统数据库的，该文件中不允许包含系统已有数据表的定义。当卸载插件时，对应的表格将自动删除。
634 | 
635 | 示例代码：
636 | 
637 | ```json
638 | {
639 |     "links": [
640 |         "link_id identity primary key",
641 |         "link_name nvarchar(255) null",
642 |         "link_desc nvarchar(255) null",
643 |         "link_href nvarchar(255) null",
644 |         "link_icon nvarchar(255) null",
645 |         "link_type bit null default(0)",
646 |         "link_hide bit null default(0)",
647 |         "link_index bit null default(0)"
648 |     ]
649 | }
650 | ```
651 | 
652 | ## 插件自定义安装、升级和卸载
653 | 
654 | 自定义安装模块`install.js`允许用户安装插件过程附带自定义安装内容。
655 | 
656 | 比如我们在安装的时候需要移动插件的文件到系统文件夹下。比如安装插件时需要自动增加插件要使用的用户权限。这些操作都可以在`install.js`中实现，而无需用户再去手动进行这些操作。这样无疑使得插件的安装更加智能，使用更加方便。不过需要注意的是，这个模块是在系统安装插件最后执行。
657 | 
658 | 对应的，自定义升级模块`update.js`在插件升级的最后自动执行，自定义卸载模块`uninstall.js`在插件卸载的最后自动执行。
659 | 
660 | 这个文件同样是一个标准的类模块文件，我们把要执行的操作方法在类的初始化过程中依次调用，这样就能够自动执行这些方法了。
661 | 
662 | 这三个模块将传入`this.pid`用于模块内部方法中获取插件在数据库中的id值。
663 | 
664 | 示例代码：
665 | 
666 | ```javascript
667 | module.exports = function(req, res){
668 |     // your codes here
669 | };
670 | ```
671 | 
672 | ## 使用hook功能
673 | 
674 | ### 挂接系统操作
675 | 
676 | 通常，我们需要使用插件实现一些与系统操作相关的功能。例如：在文章发布成功之后，自动ping到搜索引擎；自动将文章标题转换成拼音作为别名；自动将附件存储到第三方网盘并更新文章中的下载链接；在后台首页自动展示插件中的某些内容。
677 | 
678 | 对于之前PJBlog中的作法，我们是通过修改系统文件实现。这样的直接后果就是程序无法升级，否则需要对照文件重新修改一次。
679 | 
680 | 为了解决这种窘境，PJBlog5(Folk)实现了hook技术。
681 | 
682 | hook，又称“钩子”，实际上是一个处理消息的程序段，通过系统调用，把它挂入系统。每当特定的操作执行时，系统将自动执行插件中与对应hook挂接的方法。
683 | 
684 | 注意：当同一个hook挂接多个插件中的多个方法时，按照插件安装的先后顺序依次执行。
685 | 
686 | 为了实现插件自动挂接hook，我们需要在插件目录中添加`hook.js`模块。插件安装时，系统将自动把`hook.js`中挂接的方法关联起来。插件卸载时，系统将自动取消关联。
687 | 
688 | 插件中具体的实现方法，都写在hook.js中，在hook.js中我们可以挂接多个接口。
689 | 
690 | 以下是一个示例，用于实现显示系统通知。
691 | 
692 | ```javascript
693 | // 显示系统通知
694 | exports['System.Notification'] = function(notice) {
695 |     if (!notice instanceof Array) return;
696 | 
697 |     var command = require('./command');
698 |     var count = command.getHideList();
699 | 
700 |     if (count > 0) {
701 |         var html = [
702 |             '<a href="' + blog.modules.url.setUrl('control', 'index', {p: this.pid}) + '">',
703 |             '    <i class="fa fa-unlink text-aqua"></i> 有 ' + count + ' 条友情链接等待审核',
704 |             '</a>'
705 |         ].join('\n');
706 | 
707 |         notice.push(html);
708 |     }
709 | };
710 | ```
711 | 
712 | ### 在插件中提供hook供其它插件调用
713 | 
714 | 有时候，我们也可以在插件中提供hook供其它插件调用。
715 | 
716 | 例如，提供一个不带数据返回的hook。
717 | 
718 | ```javascript
719 | //注册hook：评论成功
720 | blog.modules.hook.execute('PLUGIN.Comments.Success', data);  // 提供一个名为PLUGIN.Comments.Success的hook，并将data作为参数传入
721 | //结束hook
722 | ```
723 | 
724 | 如果需要将处理结果回传，则需要使用js的回调函数实现。
725 | 
726 | ```javascript
727 | var callback = function(object){
728 |     // do sth with object
729 | }
730 |  
731 | blog.modules.hook.execute('PLUGIN.Comments.Ready', content, callback);
732 | ```
733 | 
734 | ### 系统hook列表
735 | 
736 | + **System.User.Info:** 获取用户信息，参数：req, user(用户信息数据)
737 | 
738 | + **System.User.Links:** 获取用户登录等url地址，参数：req, user(用户信息数据)
739 | 
740 | + **System.Notification:** 在后台右上角显示系统通知，参数：notice(通知数据数组)
741 | 
742 | ## 插件多语言支持
743 | 
744 | 参考主题制作文档的[主题语言文件](https://github.com/envirs/folk/blob/master/documents/cn/%E4%B8%BB%E9%A2%98%E5%88%B6%E4%BD%9C%E6%96%87%E6%A1%A3.md#主题语言文件)章节。


--------------------------------------------------------------------------------
/documents/cn/主题制作文档.md:
--------------------------------------------------------------------------------
   1 | # Folk主题
   2 | 
   3 | 主题是指用户定制的Folk前台界面，通过自定义主题模板，可以将Folk打造成极具个性化的个人网站。
   4 | 
   5 | Folk的主题采用的是修改自[ejs](https://github.com/mde/ejs)的[ejs-lite](https://github.com/Spikef/ejs-lite)模板引擎。`ejs-lite`除了在`ejs`的基础上增加了对[NodeAsp](https://github.com/Spikef/NodeAsp)的兼容以及更多的自定义选项之外，在使用上与`ejs`完全一致。
   6 | 
   7 | Folk的主题文件放置于`vision/themes`目录下。后台包含主题管理模块，自动列出所有的主题，可以对主题进行安装、启用、停用、卸载、删除、自定义参数和查看帮助文档等操作。
   8 | 
   9 | * [开始制作主题](#开始制作主题)
  10 | * [主题基础文件](#主题基础文件)
  11 | * [主题资源文件](#主题资源文件)
  12 | * [主题模板文件](#主题模板文件)
  13 | * [主题语言文件](#主题语言文件)
  14 | * [主题脚本文件](#主题脚本文件)
  15 | 
  16 | ## 开始制作主题
  17 | 
  18 | ### 开启debug模式
  19 | 
  20 | 默认情况下，只有经过官方认证的主题才能安装使用。因此，如果要制作主题，则需要开启`debug`模式。
  21 | 
  22 | 对于`asp`版本，开启的方式为：在后台首页，`设置程序功能` ⇨ `开启debug模式`。
  23 | 
  24 | 对于`node`版本，开启的方式为：使用`node index --debug`或者`npm run-script debug`启动应用。
  25 | 
  26 | > 注意：默认情况下，debug模式是关闭的，因为debug模式会略微影响程序性能，同时debug模式下会显示详细的错误信息，对程序安全性也有影响，因此，记得在制作完成主题之后关闭debug模式。
  27 | 
  28 | ### 新建主题
  29 | 
  30 | 在`vision/themes`目录下新建一个目录用于保存新建主题的所有文件，目录名称需要和您的主题名称相同。
  31 | 
  32 | 然后，您就可以参照下面的教程往下一步一步地添加主题文件了！
  33 | 
  34 | ## 主题基础文件
  35 | 
  36 | 每套主题在安装之后都会保存在单独的目录中，主题目录名称可以随意，但为了兼容性考虑，所有目录名称和文件名请务必**不要使用中文和特殊字符**。
  37 | 
  38 | 一套主题包含以下基础文件：
  39 | 
  40 | * [主题预览图片](#主题预览图片)
  41 | * [主题信息文件](#主题信息文件)
  42 | * [主题配置文件](#主题配置文件)
  43 | * [主题帮助文档](#主题帮助文档)
  44 | 
  45 | ### 主题预览图片
  46 | 
  47 | `preview.png`用于提供主题预览，方便用户后台管理和安装，通常建议尺寸为600×400左右。该文件必须包含，否则主题无法安装！
  48 | 
  49 | `snapshot.png`为主题的完整截图，方便在云平台上更好的展示和出售您的主题，对图片尺寸无要求，但是建议文件大小不超过2M。该文件并不是必需的。
  50 | 
  51 | ### 主题信息文件
  52 | 
  53 | 主题信息保存在`package.json`文件中，`package.json`是一个完全符合JSON规范的json文件。
  54 | 
  55 | `package.json`文件中可能包含一些其它平台需要使用的字段信息，`Folk`只关注其中的以下字段。以下说明的字段中，除明确标明是可以省略的字段外，都是必需包含的。
  56 | 
  57 | #### name
  58 | 
  59 | 在`package.json`中最重要的就是name和version字段。他们都是必须的，如果没有就无法安装。name和version一起组成主题的唯一标志，更新主题的同时需要更新version。
  60 | 
  61 | name作为包名的同时，也是这个主题的名字，也是主题安装之后的目录名。
  62 | 
  63 | > 注意：name通常由小写字母, 数字以及`.-_`等符号组成. 不要使用中文, 大写字母和任何non-url-safe的字符.
  64 | 
  65 | #### version
  66 | 
  67 | 主题的版本号，必需符合[semver](https://docs.npmjs.com/misc/semver)规范。简言之，就是使用三个数字，中间用`.`隔开，例如：`1.0.0`。
  68 | 
  69 | > 注意：如果当主题无法升级时，请增加版本号的第一位，例如：从`1.2.12`变为`2.2.13`。
  70 | 
  71 | #### description
  72 | 
  73 | 主题描述信息，用于描述该主题的一些特性：主色调，风格等。
  74 | 
  75 | #### homepage
  76 | 
  77 | 主题项目主页，可以是某篇日志的地址或者某个GitHub项目的地址，可以省略。
  78 | 
  79 | #### author
  80 | 
  81 | 主题作者信息，具体格式请参考下文的完整示例。
  82 | 
  83 | #### engines
  84 | 
  85 | 指定该主题支持的运行版本：`node`表示支持的Node.js的版本，例如“>=0.10.0”，同时意味着该主题支持node版本的Folk；`nodeasp`表示支持的NodeAsp的版本，例如“>=0.1.0”，同时意味着该主题支持asp版本的Folk；`folk`表示该主题支持的Folk的版本（可以在后台的右下角看到）。关于版本号的约束方式，请参考[semver](https://docs.npmjs.com/misc/semver)相关文档。
  86 | 
  87 | > 注意：当Folk进行了无法兼容之前主题或者插件的升级之后，中间一位的版本号会发生变更！
  88 | 
  89 | #### plugins
  90 | 
  91 | 该主题支持的插件列表，格式与engines一样，键名为插件名称，键值为适配的插件版本。该字段可以省略，但是为了用户更好的使用主题，通常建议填写！
  92 | 
  93 | #### template
  94 | 
  95 | 模板引擎选项参数，支持delimiters和useWith两个设置选项。
  96 | 
  97 | 查看更多关于`ejs-lite`模板引擎[选项说明](https://github.com/Spikef/ejs-lite#options)文档。
  98 | 
  99 | #### price
 100 | 
 101 | 主题售价，如果希望在云平台上出售您的主题以获取报酬的话，请填写该字段。该字段值的类型为数字，币种为人民币，单位为元。
 102 | 
 103 | #### mark
 104 | 
 105 | 主题标识，由程序自动生成，请勿手动添加或修改。
 106 | 
 107 | **完整示例：**
 108 | 
 109 | ```json
 110 | {
 111 |     "name": "default",
 112 |     "description": "默认主题, 基于bootstrap。",
 113 |     "version": "1.0.1",
 114 |     "homepage": "",
 115 |     "price": 0,
 116 |     "author": {
 117 |         "name": "Spikef",
 118 |         "email": "Spikef@foxmail.com",
 119 |         "url": "http://www.xybk.net"
 120 |     },
 121 |     "engines": {
 122 |         "folk": ">=1.0.1",
 123 |         "node": ">=4.0",
 124 |         "nodeasp": ">=0.1.0"
 125 |     },
 126 |     "plugins": {},
 127 |     "template": {}
 128 | }
 129 | ```
 130 | 
 131 | **了解更多：**
 132 | 
 133 | * [关于JSON规范](http://json.cn/json.html)
 134 | * [关于package.json](http://www.mujiang.info/translation/npmjs/files/package.json.html)
 135 | 
 136 | ### 主题配置文件
 137 | 
 138 | 主题可以提供一些参数选项供用户设置，以使主题更加灵活，这些参数保存在`options.json`文件中。
 139 | 
 140 | `options.json`也是一个标准的JSON文件，每一个参数都是一个JSON对象，包含type、desc、info、value、items、source等，而其键名则作为该参数的名称供主题调用。
 141 | 
 142 | > 主题安装之后，这些参数的值可以在后台的主题设置中进行修改。
 143 | 
 144 | #### type
 145 | 
 146 | 修改参数时的form控件类型，其值为字符串，所有支持的类型请查看下面的完整示例。
 147 | 
 148 | #### desc
 149 | 
 150 | 修改参数时的form控件对应的label显示的文本，其值为字符串。
 151 | 
 152 | #### value
 153 | 
 154 | 参数的默认值，可以为字符串、数字或者布尔值，在调用自定义参数时，会自动转换为对应的值的类型。
 155 | 
 156 | #### info
 157 | 
 158 | 修改参数时的form控件下方显示的提示文本，其值为字符串，可以省略。
 159 | 
 160 | #### items
 161 | 
 162 | 当type为select时，items提供下拉菜单选项，其值为数组，数组中的每个元素为json，包含name(用于显示)和value(用户选中的值)。
 163 | 
 164 | #### source
 165 | 
 166 | 当type为dynamic时，source提供下拉菜单选项。dynamic表示该参数的可选值由函数动态生成，source即为该函数的源码, 可用如下方式获取。
 167 | 
 168 | ```javascript
 169 | var a = function() {
 170 |     // your codes here
 171 | };
 172 | var b = a.toString().replace(/\n/g, '\\n');
 173 | console.log(b);
 174 | ```
 175 | 
 176 | 在下面的完整示例中，参数test12会自动列出该主题下`assets/styles`目录中所有的主题样式，供用户选择。
 177 | 
 178 | **完整示例：**
 179 | 
 180 | ```json
 181 | {
 182 |     "test1": {
 183 |         "type": "text",
 184 |         "desc": "用户名",
 185 |         "value": "普通文本"
 186 |     },
 187 |     "test2": {
 188 |         "type": "number",
 189 |         "desc": "数字",
 190 |         "value": 10
 191 |     },
 192 |     "test3": {
 193 |         "type": "password",
 194 |         "desc": "密码",
 195 |         "value": "123456"
 196 |     },
 197 |     "test4": {
 198 |         "type": "date",
 199 |         "desc": "日期",
 200 |         "value": "2016-05-01"
 201 |     },
 202 |     "test5": {
 203 |         "type": "time",
 204 |         "desc": "时间",
 205 |         "value": "21:17"
 206 |     },
 207 |     "test6": {
 208 |         "type": "color",
 209 |         "desc": "颜色",
 210 |         "value": "#FFFFFF",
 211 |         "info": "显示在输入框下方的提示文本"
 212 |     },
 213 |     "test7": {
 214 |         "type": "email",
 215 |         "desc": "邮箱",
 216 |         "value": "mute@boot.cn"
 217 |     },
 218 |     "test8": {
 219 |         "type": "url",
 220 |         "desc": "网址",
 221 |         "value": "http://www.baidu.com"
 222 |     },
 223 |     "test9": {
 224 |         "type": "textarea",
 225 |         "desc": "文本域",
 226 |         "value": "善于观察的医生常常能从人的表情、姿势以及动作诊察出抑郁症。",
 227 |         "info": "显示在输入框下方的提示文本"
 228 |     },
 229 |     "test10": {
 230 |         "type": "select",
 231 |         "desc": "布尔选择列表",
 232 |         "value": false,
 233 |         "info": "显示在输入框下方的提示文本",
 234 |         "items": [
 235 |             {"name": "否", "value": false},
 236 |             {"name": "是", "value": true}
 237 |         ]
 238 |     },
 239 |     "test11": {
 240 |         "type": "select",
 241 |         "desc": "数字选择列表",
 242 |         "value": 2,
 243 |         "items": [
 244 |             {"name": "0", "value": 0},
 245 |             {"name": "1", "value": 1},
 246 |             {"name": "2", "value": 2}
 247 |         ]
 248 |     },
 249 |     "test12": {
 250 |         "type": "dynamic",
 251 |         "desc": "函数生成选择列表",
 252 |         "value": 2,
 253 |         "source": "function () {\n    var fs = blog.modules.fs;\n    var path = blog.modules.path;\n\n    var styles = [];\n    var folder = path.resolve(blog.vision, 'themes', blog.theme.folder, 'assets/styles');\n    if (fs.existsSync(folder)) {\n        fs.readdirSync(folder).forEach(function(item) {\n            if (fs.statSync(path.resolve(folder, item)).isDirectory()) {\n                styles.push({\n                    name: item,\n                    value: item\n                });\n            }\n        });\n    }\n\n    return styles;\n}"
 254 |     }
 255 | }
 256 | ```
 257 | 
 258 | ### 主题帮助文档
 259 | 
 260 | 主题下面可以包含一个文件名为`README.md`的帮助文档，该文档为标准的[markdown](http://sspai.com/25137)文件，不支持表格、公式等扩展语法。
 261 | 
 262 | 为了便于链接到其它语言的帮助文档和添加图片，帮助文档在markdown语法的基础上支持如下两个特殊用法。
 263 | 
 264 | #### 链接到指定语言的帮助文档
 265 | 
 266 | 例如：主题下有名为`README_EN.md`的帮助文档，可以使用如下方式链接过去。
 267 | 
 268 | `[Click Here To Read The English Document]({filename:README_EN.md})`
 269 | 
 270 | #### 显示assets目录中的图片
 271 | 
 272 | 如果需要在帮助文档中显示图片，可以将图片存放在主题的assets目录中。
 273 | 
 274 | 例如：主题下有名为`assets/images/help.png`的图片，可以使用如下方式显示。
 275 | 
 276 | `![图片替换文本]({attachment:images/help.png})`
 277 | 
 278 | ## 主题资源文件
 279 | 
 280 | 主题资源文件即css样式表、js脚本、图片、自定义字体等文件，这些文件必需保存在主题目录下的`assets`目录中，该主题才能正常使用。
 281 | 
 282 | 系统自带的资源文件位于`system/assets`目录中，有些常用的文件，如：jquery、bootstrap、font-awesome都已经自带了，推荐直接使用。
 283 | 
 284 | ## 主题模板文件
 285 | 
 286 | 主题模板文件主要包含页面HTML代码，一些简单的逻辑处理，以及绑定、显示数据。这些文件位于主题目录下的`views`目录中，以`.ejs`作为文件后缀名。
 287 | 
 288 | * [模板引擎](#模板引擎)
 289 | * [数据源](#数据源)
 290 | * [辅助方法类](#辅助方法类)
 291 | * [模板文件](#模板引擎)
 292 | 
 293 | ### 模板引擎
 294 | 
 295 | Folk的主题模板使用了[ejs-lite](https://github.com/Spikef/ejs-lite)模板引擎，完整文档请访问项目主页阅读，这里只作简单介绍。
 296 | 
 297 | #### 定义变量和执行代码
 298 | 
 299 | 可以在HTML中混入后端JavaScript代码，用`<%`和`%>`标签包围即可。例如，定义变量：
 300 | 
 301 | ```javascript
 302 | <%
 303 | var a = "hello world";
 304 | var b = ["h", "e", "l", "l", "o", "w", "o", "r", "l", "d"];
 305 | var c = function(index) {
 306 |     if ( typeof(index) === "number" ) {
 307 |         return b[index] || "undefined";
 308 |     } else {
 309 |         return "error";
 310 |     }
 311 | }
 312 | %>
 313 | ```
 314 | 
 315 | #### 输出变量和函数的返回值
 316 | 
 317 | 使用`<%=`或`<%-`标签开始，表示输出值。当使用`<%-`输出时，输出内容中的HTML将被转义，即`<`和`>`将输出为`&lt;`和`&gt;`。
 318 | 
 319 | > 注意：这一点与ejs模板引擎正好相反，不过我们可以通过自定义标签来实现与ejs模板引擎一致的效果。
 320 | 
 321 | ```html
 322 | <p>输出字符串、数字、布尔值等：<%=a%></p>
 323 | <p>输出数组或JSON等：<%=JSON.stringify(b)%></p>
 324 | <p>执行并输出函数的返回值：<%=c(1)%></p>
 325 | ```
 326 | 
 327 | 渲染之后，将输出以下内容：
 328 | 
 329 | ```html
 330 | <p>输出字符串、数字、布尔值等：hello world</p>
 331 | <p>输出数组或JSON等：["h", "e", "l", "l", "o", "w", "o", "r", "l", "d"]</p>
 332 | <p>执行并输出函数的返回值：e</p>
 333 | ```
 334 | 
 335 | #### if条件判断
 336 | 
 337 | 分为特定模板标签和原始JavaScript代码两种方式：
 338 | 
 339 | ```html
 340 | <%var n = 200;%>
 341 | <%?n && n>300%><p>大于300</p>
 342 | <%??n<100%><p>小于100</p>
 343 | <%??%><p>介于100和300之间</p>
 344 | <%?%>
 345 | ```
 346 | 
 347 | 等同于以下代码：
 348 | 
 349 | ```html
 350 | <%var n = 200;%>
 351 | <%if (n && n>300) {%><p>大于300</p>
 352 | <%} else if (n<100) {%><p>小于100</p>
 353 | <%} else {%><p>介于100和300之间</p>
 354 | <%}%>
 355 | ```
 356 | 
 357 | #### switch条件选择
 358 | 
 359 | 分为特定模板标签和原始JavaScript代码两种方式：
 360 | 
 361 | ```html
 362 | <%var m = 200;%>
 363 | <%:m%>
 364 | <%::100%><p>等于100</p>
 365 | <%::200, "200"%><p>等于200</p>
 366 | <%::%><p>不等于100也不等于200</p>
 367 | <%:%>
 368 | ```
 369 | 
 370 | 等同于以下代码：
 371 | 
 372 | ```html
 373 | <%var m = 200;%>
 374 | <%switch (m) {%>
 375 |   <%case 100:%>
 376 |     <p>等于100</p>
 377 |     <%break;%>
 378 |   <%case 200:%>
 379 |   <%case "200":%>
 380 |     <p>等于200</p>
 381 |     <%break;%>
 382 |   <%default:%>
 383 |     <p>不等于100也不等于200</p>
 384 |     <%break;%>
 385 | <%}%>
 386 | ```
 387 | 
 388 | #### 循环数组
 389 | 
 390 | 分为特定模板标签和原始JavaScript代码两种方式：
 391 | 
 392 | ```html
 393 | <%var list = [1, 2, 3];%>
 394 | <%~list <div class="header">header</div>
 395 |     <ul>%>
 396 |     <li id="out_<%=$index+1%>"><%=$value%></li>
 397 | <%~</ul>%>
 398 | ```
 399 | 
 400 | 等同于以下代码：
 401 | 
 402 | ```html
 403 | <%var list = [1, 2, 3];%>
 404 | <%if (list.length > 0) {%>
 405 | <div class="header">header</div>
 406 | <ul>
 407 |     <%list.forEach(function($value, $index){%>
 408 |     <li id="out_<%=$index+1%>"><%=$value%></li>
 409 |     <%})%>
 410 | </ul>
 411 | <%}%>
 412 | ```
 413 | 
 414 | 渲染之后，将输出以下内容：
 415 | 
 416 | ```html
 417 | <div class="header">header</div>
 418 | <ul>
 419 |     <li id="out_1">1</li>
 420 |     <li id="out_2">2</li>
 421 |     <li id="out_3">3</li>
 422 | </ul>
 423 | ```
 424 | 
 425 | #### 循环json
 426 | 
 427 | 分为特定模板标签和原始JavaScript代码两种方式：
 428 | 
 429 | ```html
 430 | <%
 431 | var list = {
 432 |               a: 100,
 433 |               b: 200,
 434 |               c: 300
 435 |            };
 436 | %>
 437 | <%~~list <ul>%>
 438 |     <li id="<%=$key%>"><%=$value%></li>
 439 | <%~%>
 440 | ```
 441 | 
 442 | 等同于以下代码：
 443 | 
 444 | ```html
 445 | <%
 446 | var html = [];
 447 | var list = {
 448 |               a: 100,
 449 |               b: 200,
 450 |               c: 300
 451 |            };
 452 | for (var $key in list) {
 453 |     if (!list.hasOwnProperty($key)) continue;
 454 |     var $value = list[$key];
 455 |     html.push('<li id="' + $key + '">' + $value + '</li>');
 456 | }
 457 | html = html.join('\n');
 458 | if (html.length > 0) html = '<ul>\n' + html + '\n</ul>';
 459 | %>
 460 | <%=html%>
 461 | 
 462 | ```
 463 | 
 464 | 渲染之后，将输出以下内容：
 465 | 
 466 | ```html
 467 | <ul>
 468 |     <li id="a">100</li>
 469 |     <li id="b">200</li>
 470 |     <li id="c">300</li>
 471 | </ul>
 472 | ```
 473 | 
 474 | #### 包含子模板
 475 | 
 476 | 可以将一些公用代码作为子模板包含进来，避免重复编写模板代码，便于修改和维护；同时，子模板也可以继续包含子模板。如果子模板位于当前模板的上层目录中时，可以使用`../`作为相对路径。
 477 | 
 478 | 有两种方式可以包含子模板。
 479 | 
 480 | 第一种：
 481 | 
 482 | ```html
 483 | <%=include('user/show', {user: user})%>
 484 | ```
 485 | 
 486 | 第二种：
 487 | 
 488 | <%include user/show%>
 489 | 
 490 | 这两种方式的区别在于：第一种方式可以使用一个变量作为模板路径，同时可以单独指定子模板的数据源。
 491 | 
 492 | #### 自定义标签
 493 | 
 494 | 如果不喜欢用`<%`和`%>`，没关系，您可以在`package.json`的`template`字段中定义您喜欢的标签，如`{{`和`}}`。
 495 | 
 496 | 自定义标签示例：
 497 | 
 498 | ```json
 499 | {
 500 |     ...
 501 |     "template": {
 502 |         "delimiters": {
 503 |             "begin": "{{",
 504 |             "close": "}}"
 505 |         }
 506 |     }
 507 | }
 508 | ```
 509 | 
 510 | 这样，上面的示例代码就变成了：
 511 | 
 512 | ```html
 513 | <p>输出字符串、数字、布尔值等：{{=a}}</p>
 514 | <p>输出数组或JSON等：{{=JSON.stringify(b)}}</p>
 515 | <p>执行并输出函数的返回值：{{=c(1)}}</p>
 516 | ```
 517 | 
 518 | #### 关闭with模式
 519 | 
 520 | 默认情况下，with模式是开启的，这将为绑定主题数据源提供方便。关闭with模式理论上可以略微提高模板引擎的渲染速度。因此是否开启with模式，完全取决于您自己。开启的方式为，在`package.json`的`template`字段中设置`useWith`的值为`false`。
 521 | 
 522 | ```json
 523 | {
 524 |     ...
 525 |     "template": {
 526 |         "useWith": false
 527 |     }
 528 | }
 529 | ```
 530 | 
 531 | 例如绑定网站标题数据，默认情况下是这样子的：`<%=blog.title%>`。开启with模式后，则需要统一在前面加上`folk.`，变成`<%=folk.blog.title%>`。
 532 | 
 533 | ### 数据源
 534 | 
 535 | 数据源用于向模板页面提供数据，没有绑定数据源的模板页面是没有意义的。
 536 | 
 537 | #### 通用模板数据源
 538 | 
 539 | 通用模板数据源是所有前台页面共用的数据源。
 540 | 
 541 | **系统数据源对象：blog**
 542 | 
 543 | * blog.timer(): 返回页面运行当前消耗的时间(毫秒)
 544 | * blog.engine: 系统运行引擎，返回`node`或者`asp`
 545 | * blog.remote: 返回云平台域名，末尾无`/`
 546 | * blog.domain: 返回当前网站域名，末尾无`/`
 547 | * blog.server: 返回云平台完整域名，以`/`结束
 548 | * blog.client: 返回当前网站完整域名，包含二级目录，以`/`结束
 549 | * blog.version: 返回当前程序版本号
 550 | * blog.name: 后台设置的网站名称
 551 | * blog.title: 后台设置的网站标题
 552 | * blog.copyright: 后台设置的网站版本信息
 553 | * blog.keywords: 后台设置的SEO关键字
 554 | * blog.description: 后台设置的SEO描述
 555 | * blog.status: 后台设置的网站运行状态
 556 | 
 557 | **URL地址查询参数数据源对象: query**
 558 | 
 559 | 这个与当前的URL地址有关，例如当前URL地址为：`http://yourdomain/article?id=1page=20`，则可以使用`query.page`获取查询参数`20`。
 560 | 
 561 | **当前用户数据源对象: user**
 562 | 
 563 | * user.id: 当前用户的id
 564 | * user.nick: 当前用户的昵称
 565 | * user.mail: 当前用户的邮箱
 566 | * user.group: 当前用户的分组id
 567 | * user.limits: 当前用户的权限
 568 | * user.status: 当前用户的状态(0 - 未登陆，1 - 普通会员，2 - 管理员(已锁定)，3 - 管理员)
 569 | * user.forbid: 当前用户是否被禁止访问
 570 | * user.avatar: 当前用户的头像
 571 | * user.hasLimit(limit_mark): 判断当前用户是否具有某项权限，返回true/false
 572 | * user.control: 当前用户为管理员时，返回管理后台的地址
 573 | * user.register: 当前用户未登录时，返回云平台注册地址
 574 | * user.login: 当前用户未登录时，返回云平台登录地址
 575 | 
 576 | **当前主题数据源对象: theme**
 577 | 
 578 | * theme.id: 返回主题在数据库中的id值
 579 | * theme.name: 返回主题名称
 580 | * theme.mail: 返回主题作者邮箱
 581 | * theme.site: 返回主题作者网站
 582 | * theme.author: 返回主题作者名称
 583 | * theme.folder: 返回主题所在文件夹
 584 | * theme.version: 返回主题的版本号
 585 | * theme.assets: 返回主题目录下`assets`目录的完整URL路径，以`/`结束
 586 | * theme.options: 返回`options.json`文件中的主题自定义参数的值
 587 | 
 588 | 例如：在`options.json`中定义了名为`test`的自定义参数，则可以使用`theme.options.test`获取它的值。
 589 | 
 590 | **导航数据源对象navs**
 591 | 
 592 | 所有的导航都保存在名为navs的JavaScript数组中。每一条导航数据都是一个json对象。
 593 | 
 594 | * nav_id: 导航id
 595 | * nav_name: 导航名称
 596 | * nav_type: 导航类型
 597 | * nav_link: 导航地址
 598 | * nav_order: 导航排序
 599 | * nav_href: 导航链接
 600 | 
 601 | 以下是一个生成导航菜单的示例：
 602 | 
 603 | ```html
 604 | <nav class="main-navigation">
 605 |     <div class="container">
 606 |         <div class="row">
 607 |             <div class="col-sm-12">
 608 |                 <div class="navbar-header">
 609 |                         <span class="nav-toggle-button collapsed" data-toggle="collapse" data-target="#main-menu">
 610 |                         <span class="sr-only">Toggle navigation</span>
 611 |                         <i class="fa fa-bars"></i>
 612 |                         </span>
 613 |                 </div>
 614 |                 <div class="collapse navbar-collapse" id="main-menu">
 615 |                     <ul class="menu">
 616 |                         <%~navs%>
 617 |                         <li role="presentation"><a href="<%=nav_href%>"><%=nav_name%></a></li>
 618 |                         <%~%>
 619 |                     </ul>
 620 |                 </div>
 621 |             </div>
 622 |         </div>
 623 |     </div>
 624 | </nav>
 625 | ```
 626 | 
 627 | **分类数据源对象cates**
 628 | 
 629 | 所有的分类都保存在名为cates的JavaScript数组中。每一条分类数据都是一个json对象。
 630 | 
 631 | * cate_id: 分类id
 632 | * cate_name: 分类名称
 633 | * cate_desc: 分类描述
 634 | * cate_count: 该分类下的文章数
 635 | * cate_order: 分类排序
 636 | * cate_href: 分类链接
 637 | 
 638 | 以下是一个生成分类菜单的示例：
 639 | 
 640 | ```html
 641 | <div class="widget">
 642 |     <h4 class="title">文章分类</h4>
 643 |     <div class="content common text-link">
 644 |         <%cates.forEach(function(cate){%>
 645 |         <p>
 646 |             <i class="fa fa-folder-open-o"></i>
 647 |             <a href="<%=cate.cate_href%>"><%=cate.cate_name%></a>
 648 |             <span class="text-success">(<%=cate.cate_count%>)</span>
 649 |         </p>
 650 |         <%});%>
 651 |     </div>
 652 | </div>
 653 | ```
 654 | 
 655 | #### 页面级模板数据源
 656 | 
 657 | 页面级模板数据源只针对指定的页面才有用，具体请看下面的[模板文件](#模板文件)章节。
 658 | 
 659 | ### 辅助方法类
 660 | 
 661 | 辅助方法类对象`helper`提供了一些常用方法或者模块对象，方便制作主题时直接调用。
 662 | 
 663 | * [helper.setUrl](#helpersetUrl)
 664 | * [helper.fnu](#helperfnu)
 665 | * [helper.hook](#helperhook)
 666 | * [helper.plugin](#helperplugin)
 667 | * [helper.hasPlugin](#helperhasplugin):
 668 | 
 669 | #### helper.setUrl
 670 | 
 671 | 为了同时兼容node和asp，Folk采用了统一的URL管理模块。因此，当需要获取某个URL地址时，可以使用这个方法。
 672 | 
 673 | setUrl方法一共有三个参数：
 674 | 
 675 | **entrance**
 676 | 
 677 | 入口，分为stage（前台页面，可以省略），control（后台管理页面），api（接收请求，统一返回json数据）。
 678 | 
 679 | **approach**
 680 | 
 681 | 处理模块，具体可以查看`system/routers.json`中的配置。
 682 | 
 683 | **params**
 684 | 
 685 | 其它URL请求参数，为json对象，可以省略。
 686 | 
 687 | 例如：获取某个插件的ajax请求地址（假设插件id为1，name为blog-link，具体的方法为post-link），可以这样返回。
 688 | 
 689 | ```javascript
 690 | var url = helper.setUrl('api', 'request', {pid: 1, method: 'post-link'});
 691 | ```
 692 | 
 693 | 或者在不知道id的情况下，也可以直接使用插件的name。
 694 | 
 695 | ```javascript
 696 | var url = helper.setUrl('api', 'request', {name: 'blog-link', method: 'post-link'});
 697 | ```
 698 | 
 699 | URL模块是前、后端兼容的，如果希望在前端js中使用该方法，请参考以下步骤。
 700 | 
 701 | 1.在页面中引入URL模块文件，并定义前端全局变量blog（需要用到blog.engine和blog.client两个值）。
 702 | 
 703 | ```html
 704 | <script src="<%=blog.client%>system/library/url.js"></script>
 705 | <script language="javascript" type="text/javascript">
 706 |     (function(blog) {
 707 |         window.blog = blog;
 708 |     }(<%=JSON.stringify(blog)%>));
 709 | </script>
 710 | ```
 711 | 
 712 | 2.通过以下方式来调用此方法。 
 713 | 
 714 | ```
 715 | var url = modules.url.setUrl('api', 'request', {name: 'blog-link', method: 'post-link'});
 716 | ```
 717 | 
 718 | #### helper.fnu
 719 | 
 720 | fnu模块提供了一些辅助函数方法，这里只介绍几个常用的。
 721 | 
 722 | **fnu.extend(source, target)**
 723 | 
 724 | 将target对象(json)的元素拷贝至source对象(json)，并返回新的source对象。
 725 | 
 726 | **fnu.deepClone(source, target)**
 727 | 
 728 | 与extend类似，区别在于当元素也为json时，会继续进行深拷贝，这样可以防止修改source对象时污染到target对象。
 729 | 
 730 | **fnu.getType(object)**
 731 | 
 732 | 获取object对象的数据类型，可能的返回值：undefined, null, string, number, array, boolean, date, error, function, math, object, regexp。
 733 | 
 734 | **fnu.isType(object, type)**
 735 | 
 736 | 相当于`fnu.getType(object) === type`。
 737 | 
 738 | **fnu.cutStr(s, n, c, r)**
 739 | 
 740 | 截取字符串。
 741 | 
 742 | * s: 字符串
 743 | * n: 截取字数
 744 | * c: 是否使用中文编排
 745 | * r: 省略的符号
 746 | 
 747 | **fnu.dateFormat(date, format)**
 748 | 
 749 | 格式化日期时间。
 750 | 
 751 | `dateFormat(new Date('2016-3-27 8:5:34'), 'yy-mm-dd hh:nn') => 2016-03-27 08:05:34`
 752 | 
 753 | * date: 时间、时间戳或可以转换为时间格式的字符串
 754 | * format: 格式化字符串，y(年)、m(月)、d(日)、h(时)、n(分)、s(秒)，如果使用两位字母(yy)则表示输出完整位数
 755 | 
 756 | **fnu.numberFormat(number, format)**
 757 | 
 758 | 格式化数字。例如`numberFormat(-23123211312, ',2')`表示整数位用`,`分隔，并保留两位小数。
 759 | 
 760 | #### helper.hook
 761 | 
 762 | 参考插件制作文档的[使用hook功能](https://github.com/envirs/folk/blob/master/documents/cn/%E6%8F%92%E4%BB%B6%E5%88%B6%E4%BD%9C%E6%96%87%E6%A1%A3.md#使用hook功能)章节。
 763 | 
 764 | #### helper.plugin
 765 | 
 766 | 该方法用于辅助主题调用插件方法，传入两个参数。如果用户未安装此插件，将返回null。
 767 | 
 768 | * name: 插件名称
 769 | * options: 其它参数，为json对象，可以省略，具体需要参考插件文档
 770 | 
 771 | **options.method:** 待调用方法名称
 772 | **options.args:** 数组，待调用方法需要传入的参数
 773 | 
 774 | 以获取友情链接侧栏为例：
 775 | 
 776 | ```html
 777 | <%var friendLinks = helper.plugin('blog-link', {method: 'getSideList', args: [10]});%>
 778 | <%if (friendLinks) {%>
 779 | <div class="widget">
 780 |     <h4 class="title">友情链接</h4>
 781 |     <div class="content common text-link">
 782 |         <%friendLinks.forEach(function(item){%>
 783 |         <p><i class="fa fa-globe"></i> <a href="<%=item.link_href%>" target="_blank"><%=item.link_name%></a></p>
 784 |         <%});%>
 785 |     </div>
 786 | </div>
 787 | <%}%>
 788 | ```
 789 | 
 790 | #### helper.hasPlugin
 791 | 
 792 | 该方法传入插件name作为参数，返回用户是否安装此插件。
 793 | 
 794 | ### 模板文件
 795 | 
 796 | #### home.ejs
 797 | 
 798 | 网站主页模板文件，如果该文件不存在，则访问网站时直接显示文章列表页。
 799 | 
 800 | 该页面不存在额外的页面级数据源。
 801 | 
 802 | #### list.ejs
 803 | 
 804 | 文章列表页模板，分类列表和标签列表共用。
 805 | 
 806 | 下面我们来看一下文章列表页特有的数据源对象。
 807 | 
 808 | **列表请求数据源对象search**
 809 | 
 810 | * search.type: 请求类型，返回`分类`或者`标签`
 811 | * search.name: 请求值，返回分类或标签名称
 812 | 
 813 | ```html
 814 | <%if (search.name) {%>
 815 | <div class="cover tag-cover">
 816 |     <h3 class="tag-name">
 817 |         <%=search.type%>：<%=search.name%>
 818 |     </h3>
 819 | </div>
 820 | <%}%>
 821 | ```
 822 | 
 823 | **文章列表数据源对象articles**
 824 | 
 825 | * articles.total: 返回文章总数
 826 | * articles.list: 返回文章列表数组，元素为文章信息的json对象
 827 | * articles.page: 返回包含分页信息的json对象
 828 | 
 829 | 文章信息包含以下字段：
 830 | 
 831 | * article.art_id: 返回文章id
 832 | * article.art_title: 返回文章标题
 833 | * article.art_cover: 返回文章封面图片
 834 | * article.art_summary: 返回文章摘要
 835 | * article.art_alias: 返回文章别名
 836 | * article.art_type: 返回文章类型
 837 | * article.art_post_time: 返回文章发表时间，Date类型
 838 | * article.art_last_time: 返回文章最后修改时间，Date类型
 839 | * article.art_comment_count: 返回文章评论数
 840 | * article.art_visit_count: 返回文章阅读数
 841 | * article.art_like_count: 返回文章点赞数
 842 | * article.art_cate: 返回文章分类信息
 843 | * article.art_cate.cate_name: 返回文章分类名称
 844 | * article.art_cate.cate_href: 返回文章分类链接
 845 | * article.art_cate.cate_count: 返回文章分类下的文章数目
 846 | * article.author: 返回文章作者信息
 847 | * article.author.user_nick: 返回文章作者昵称
 848 | * article.author.user_avatar: 返回文章作者头像
 849 | * article.author.user_mail: 返回文章作者邮箱
 850 | * article.art_tags: 返回文章标签列表，数组类型
 851 | * article.art_tags[i].tag_id: 返回标签id
 852 | * article.art_tags[i].tag_name: 返回标签名称
 853 | * article.art_tags[i].tag_href: 返回标签链接地址
 854 | * article.art_tags[i].art_count: 返回标签下的文章数目
 855 | 
 856 | 下面是一个循环显示文章列表的示例：
 857 | 
 858 | ```html
 859 | <%articles.list.forEach(function(item){%>
 860 | <article class="post">
 861 |     <div class="post-head">
 862 |         <h1 class="post-title"><a href="<%=item.art_href%>"><%=item.art_title%></a></h1>
 863 |         <div class="post-meta">
 864 |             <span class="author">作者：<%=item.art_author.user_nick%></span> <i class="fa fa-calendar-o"></i>
 865 |             <time class="post-date"><%=helper.fnu.dateFormat(new Date(item.art_post_time), 'yy年m月d日')%></time>
 866 |         </div>
 867 |     </div>
 868 |     <div class="post-content">
 869 |         <p><%=item.art_summary%></p>
 870 |     </div>
 871 |     <div class="post-permalink">
 872 |         <a href="<%=item.art_href%>" class="btn btn-default">阅读全文</a>
 873 |     </div>
 874 | 
 875 |     <footer class="post-footer clearfix">
 876 |         <div class="pull-left tag-list">
 877 |             <%~item.art_tags <i class="fa fa-tags"></i>%>
 878 |             <a href="<%=tag_href%>"><%=tag_name%></a>
 879 |             <%~%>
 880 |         </div>
 881 |         <div class="pull-right tag-list">
 882 |             <i class="fa fa-folder-open"></i>
 883 |             <a href="<%=item.art_cate.cate_href%>"><%=item.art_cate.cate_name%></a>
 884 |         </div>
 885 |     </footer>
 886 | </article>
 887 | <%});%>
 888 | ```
 889 | **文章列表分页数据源对象page**
 890 | 
 891 | * page.from: 返回起始页码
 892 | * page.to: 返回结束页码
 893 | * page.first: 返回第一页的页码
 894 | * page.last: 返回最后一页的页码
 895 | * page.prev: 返回前一页的页码
 896 | * page.next: 返回后一页的页码
 897 | * page.range: 返回一次显示的页码条数
 898 | * page.index: 返回当前页码
 899 | * page.array: 返回所有显示的页码数组
 900 | * page.link: 返回指定页码的链接（待定）
 901 | 
 902 | #### article.ejs
 903 | 
 904 | 文章页面模板。
 905 | 
 906 | 下面我们来看一下文章页面特有的数据源对象。
 907 | 
 908 | **文章信息数据源对象article**
 909 | 
 910 | * article.art_id: 返回文章id
 911 | * article.art_title: 返回文章标题
 912 | * article.art_cover: 返回文章封面图片
 913 | * article.art_summary: 返回文章摘要
 914 | * article.art_content: 返回文章内容
 915 | * article.art_alias: 返回文章别名
 916 | * article.art_type: 返回文章类型
 917 | * article.art_post_time: 返回文章发表时间，Date类型
 918 | * article.art_last_time: 返回文章最后修改时间，Date类型
 919 | * article.art_comment_count: 返回文章评论数
 920 | * article.art_visit_count: 返回文章阅读数
 921 | * article.art_like_count: 返回文章点赞数
 922 | * article.art_href: 返回文章的固定链接地址
 923 | * article.art_cate: 返回文章分类信息
 924 | * article.art_cate.cate_name: 返回文章分类名称
 925 | * article.art_cate.cate_href: 返回文章分类链接
 926 | * article.art_cate.cate_count: 返回文章分类下的文章数目
 927 | * article.author: 返回文章作者信息
 928 | * article.author.user_nick: 返回文章作者昵称
 929 | * article.author.user_avatar: 返回文章作者头像
 930 | * article.author.user_mail: 返回文章作者邮箱
 931 | * article.art_tags: 返回文章标签列表，数组类型
 932 | * article.art_tags[i].tag_id: 返回标签id
 933 | * article.art_tags[i].tag_name: 返回标签名称
 934 | * article.art_tags[i].tag_href: 返回标签链接地址
 935 | * article.art_tags[i].art_count: 返回标签下的文章数目
 936 | * article.art_prev: 返回上一篇文章相关信息
 937 | * article.art_prev.art_id: 返回上一篇文章的id
 938 | * article.art_prev.art_title: 返回上一篇文章的标题
 939 | * article.art_prev.art_cover: 返回上一篇文章的封面图片
 940 | * article.art_prev.art_href: 返回上一篇文章的链接地址
 941 | * article.art_next: 返回下一篇文章相关信息
 942 | * article.art_next.art_id: 返回下一篇文章的id
 943 | * article.art_next.art_title: 返回下一篇文章的标题
 944 | * article.art_next.art_cover: 返回下一篇文章的封面图片
 945 | * article.art_next.art_href: 返回下一篇文章的链接地址
 946 | * article.art_relative: 返回相关文章信息数组，需要在后台设置相关文章数
 947 | * article.art_relative[i].art_id: 返回相关文章的id
 948 | * article.art_relative[i].art_title: 返回相关文章的标题
 949 | * article.art_relative[i].art_cover: 返回相关文章的封面图片
 950 | * article.art_relative[i].art_href: 返回相关文章的链接地址
 951 | 
 952 | #### 插件页面模板文件
 953 | 
 954 | 插件页面模板文件不是一个特定的文件，其文件名由插件规定，具体参考[插件制作文档相关章节](https://github.com/envirs/folk/blob/master/documents/cn/%E6%8F%92%E4%BB%B6%E5%88%B6%E4%BD%9C%E6%96%87%E6%A1%A3.md#navigator)。
 955 | 
 956 | **插件数据源对象plugin**
 957 | 
 958 | * plugin.id: 返回插件id
 959 | * plugin.name: 返回插件名称
 960 | * plugin.author: 返回插件作者名称
 961 | * plugin.mail: 返回插件作者邮箱
 962 | * plugin.site: 返回插件作者网址
 963 | * plugin.forbid: 返回插件是否被停止使用
 964 | * plugin.version: 返回插件版本号
 965 | * plugin.data: 返回插件提供的数据源（见下面的plugins）
 966 | 
 967 | **插件方法模块plugins**
 968 | 
 969 | 当插件作者没有声明默认的数据源提供方法时，将无法使用plugin.data来获取插件提供的数据源，只能根据插件作者约定，通过plugins调用插件作者声明的方法名称来获取数据源对象。
 970 | 
 971 | #### 404.ejs
 972 | 
 973 | 404状态页面模板，例如访问了不存在的文章或者分页页面时，将显示该页面内容。
 974 | 
 975 | #### 500.ejs
 976 | 
 977 | 500错误页面模板，当访问页面出现错误时，将显示该页面内容。
 978 | 
 979 | 对于404和500页面，都包含一个名为`error`的错误数据源对象。
 980 | 
 981 | * error.status: 状态值，404或者500
 982 | * error.message: 返回错误描述
 983 | 
 984 | ### 内置模板文件
 985 | 
 986 | 该功能尚未完善...
 987 | 
 988 | ## 主题语言文件
 989 | 
 990 | 主题支持多语言(简体中文, English...)，只需要在该主题目录下添加`language`目录，然后添加对应的语言包即可，注意文件名统一小写。
 991 | 
 992 | 语言包中只有一个数组，保存了该主题所要用到的所有语言资源。
 993 | 
 994 | * zh-cn.json: 简体中文
 995 | * en-us.json: 英文
 996 | 
 997 | ### ejs模板文件和后端js脚本文件
 998 | 
 999 | 对于ejs模板文件和后端js脚本文件，只需使用`this.lan(index)`即可返回`index`对应索引的数组元素。
1000 | 
1001 | `this.lan`方法也可以传入多个参数，示例如下：
1002 | 
1003 | zh-cn.json
1004 | 
1005 | ```json
1006 | [
1007 |     "欢迎，{0}"
1008 | ]
1009 | ```
1010 | 
1011 | helper.js
1012 | 
1013 | ```javascript
1014 | exports.html = function() {
1015 |     console.log(this.lan(0, 'admin'));
1016 |     // prints: 欢迎，admin
1017 | }
1018 | ```
1019 | 
1020 | home.ejs
1021 | 
1022 | ```html
1023 | <!-- dispaly: <div>欢迎，admin</div> -->
1024 | <div><%=this.lan(0, 'admin')%></div>
1025 | ```
1026 | 
1027 | ### package.json文件和options.json文件
1028 | 
1029 | 对于json文件，因为不具备可执行性，因此需要在`language`目录下添加一个`map.json`文件，来指定字段在语言包数组中对应的索引。
1030 | 
1031 | 示例代码：
1032 | 
1033 | ```json
1034 | {
1035 |     "package": {
1036 |         "description": 30
1037 |     },
1038 |     "options": {
1039 |         "sideArtCount": {
1040 |             "desc": 29
1041 |         }
1042 |     }
1043 | }
1044 | ```
1045 | 
1046 | ## 主题脚本文件
1047 | 
1048 | 在主题目录下的`scripts`目录中，可以存放一些供主题调用的后端模块文件。它们虽然也以`.js`作为后缀名，但是是标准的node模块文件，只供后端调用。
1049 | 
1050 | > 注意：该章节内容仅为一些具有Node.js基础的主题作者而准备，在刚开始学习制作主题时建议跳过本章节。
1051 | 
1052 | 主题脚本文件的目的在于，当系统提供的数据源不够用时，我们可以通过自定义主题脚本文件来扩充数据源。
1053 | 
1054 | 例如，我们可以在`scripts`目录中加入一个名为`helper.js`的文件，写入一些供主题调用的辅助方法，代码如下：
1055 | 
1056 | ```javascript
1057 | /**
1058 |  * Usage: 自定义主题辅助方法模块.
1059 |  * Notice: 本文件仅作为演示用途, 强烈建议不要在您的主题中直接使用此文件中的代码!
1060 |  * Author: Spikef < Spikef@Foxmail.com >
1061 |  * Copyright: Envirs Team < http://envirs.com >
1062 |  */
1063 | 
1064 | var fnu = require('fnu');
1065 | 
1066 | // 获取所有文章标签
1067 | exports.getTags = function() {
1068 |     var tags = require('../../../caches/tags.json');
1069 |     var list = [];
1070 | 
1071 |     for (var i in tags.data) {
1072 |         list.push(tags.data[i]);
1073 |     }
1074 | 
1075 |     return list;
1076 | };
1077 | 
1078 | // 获取随机日志
1079 | exports.getRndArticle = function() {
1080 |     var list = [];
1081 |     var sql = blog.modules.db.resolveSQL("select top 10 art_id, art_title from " + blog.configs.prefix + "articles where art_cate>0 and art_type>2 order by rand(art_id)");
1082 |     blog.modules.db
1083 |         .runsql(sql)
1084 |         .forEach(function(article) {
1085 |             article.art_title = fnu.cutStr(article.art_title, 35, true);
1086 |             article.art_href = blog.modules.url.setUrl('article', {id: article.art_id});
1087 |             list.push(article);
1088 |         });
1089 | 
1090 |     return list;
1091 | };
1092 | 
1093 | // 获取热门日志
1094 | exports.getHotArticle = function() {
1095 |     var list = [];
1096 |     var sql = blog.modules.db.resolveSQL("select top 10 art_id, art_title, art_visit_count from " + blog.configs.prefix + "articles where art_cate>0 and art_type>2 order by art_visit_count desc, art_id desc");
1097 |     blog.modules.db
1098 |         .runsql(sql)
1099 |         .forEach(function(article) {
1100 |             article.art_title = fnu.cutStr(article.art_title, 28, true);
1101 |             article.art_title = article.art_title + ' (' + article.art_visit_count + ')';
1102 |             article.art_href = blog.modules.url.setUrl('article', {id: article.art_id});
1103 |             list.push(article);
1104 |         });
1105 | 
1106 |     return list;
1107 | };
1108 | 
1109 | // 获取最新日志
1110 | exports.getNewArticle = function() {
1111 |     var list = [];
1112 |     var sql = blog.modules.db.resolveSQL("select top 10 art_id, art_title from " + blog.configs.prefix + "articles where art_cate>0 and art_type>2 order by art_id desc");
1113 |     blog.modules.db
1114 |         .runsql(sql)
1115 |         .forEach(function(article) {
1116 |             article.art_title = fnu.cutStr(article.art_title, 35, true);
1117 |             article.art_href = blog.modules.url.setUrl('article', {id: article.art_id});
1118 |             list.push(article);
1119 |         });
1120 | 
1121 |     return list;
1122 | };
1123 | 
1124 | // 给H1-H6添加标头
1125 | exports.makeArtMenu = function(content) {
1126 |     var PinYin = require(blog.modules.path.resolve(blog.system, 'assets/plugins/pinyin/pinyin.js'));
1127 |     var menu = [], headIds = [], idIndex = {};
1128 |     content = content.replace(/(<h[1-3])(>([^<]+)<\/h[1-3]>)/g, function($0, $1, $2, $3) {
1129 |         var id = PinYin($3, '-');
1130 |         id = id
1131 |             .replace(/\([^)]*\)/g, '')
1132 |             .replace(/[A-Z](?=[a-z])/g, '-$&')
1133 |             .replace(/[^\w]+/g, '-')
1134 |             .replace(/(^\-|\-$)/gm, '')
1135 |             .toLowerCase();
1136 | 
1137 |         // 防止ID重复
1138 |         if ( headIds.indexOf(id) > -1 ) {
1139 |             var tid = id;
1140 |             do {
1141 |                 idIndex[tid] = idIndex[tid] ? idIndex[tid] + 1 : 1;
1142 |                 id = tid + '-' + idIndex[tid];
1143 |             } while ( headIds.indexOf(id) > -1 );
1144 |         }
1145 |         headIds.push(id);
1146 | 
1147 |         if ( $1.indexOf('3') === -1 ) {
1148 |             menu.push({
1149 |                 id: id,
1150 |                 text: $3,
1151 |                 subs: [],
1152 |                 level: 2
1153 |             })
1154 |         } else {
1155 |             var last = menu[menu.length - 1];
1156 |             if (last) {
1157 |                 last.subs.push({
1158 |                     id: id,
1159 |                     text: $3,
1160 |                     level: 3
1161 |                 });
1162 |             }
1163 |         }
1164 | 
1165 |         return $1 + ' id="' + id + '"' + $2;
1166 |     });
1167 | 
1168 |     var menuHtml = '', subsHtml = '';
1169 |     menu.forEach(function(m) {
1170 |         menuHtml += '\t<li><a href="#' + m.id + '">' + m.text + '</a>{subs}\t</li>\n';
1171 |         subsHtml = '';
1172 |         m.subs.forEach(function(sm) {
1173 |             subsHtml += '\t\t\t<li><a href="#' + sm.id + '">' + sm.text + '</a></li>\n';
1174 |         });
1175 |         if ( subsHtml.length > 0 ) subsHtml = '\n\t\t<ul class="nav nav-h3">\n' + subsHtml + '\t\t</ul>\n';
1176 |         menuHtml = menuHtml.replace(/\{subs}/, subsHtml);
1177 |     });
1178 |     if ( menuHtml.length > 0 ) menuHtml = '<ul class="nav nav-h2">\n' + menuHtml + '</ul>';
1179 | 
1180 |     return {
1181 |         content: content,
1182 |         sidebar: menuHtml.replace(/\t/g, '    ')
1183 |     };
1184 | };
1185 | ```
1186 | 
1187 | 然后，我们就可以在主题中通过以下代码获取热门日志数据。
1188 | 
1189 | ```javascript
1190 | var hotList = helper.getHotArticle();   // 获取最新日志
1191 | ```
1192 | 
1193 | Folk定义了唯一的全局变量`blog`，在主题脚本文件中可以直接使用该对象。
1194 | 
1195 | * blog.folder: 网站所在二级目录名称
1196 | * blog.system: `system`目录的绝对路径
1197 | * blog.vision: `vision`目录的绝对路径
1198 | * blog.engine: 系统运行引擎，返回`node`或者`asp`
1199 | * blog.remote: 返回云平台域名，末尾无`/`
1200 | * blog.domain: 返回当前网站域名，末尾无`/`
1201 | * blog.server: 返回云平台完整域名，以`/`结束
1202 | * blog.client: 返回当前网站完整域名，包含二级目录，以`/`结束
1203 | * blog.version: 返回当前程序版本号
1204 | * blog.settings: 返回后台网站设置保存的内容
1205 | * blog.user: 返回当前用户信息
1206 | * blog.theme: 返回当前主题信息
1207 | * blog.modules.db: 数据库操作模块(database或node-database)
1208 | * blog.modules.fs: 文件操作模块(fs-plus)
1209 | * blog.modules.path: 路径操作模块(path)
1210 | * blog.modules.url: URL操作模块
1211 | * blog.modules.hook: HOOK操作模块
1212 | 
1213 | 相关模块的说明文档可以通过访问`http://yourdomain/control?docs&type=module&name=modulename`来查看。
1214 | 
1215 | ## Q&A
1216 | 
1217 | Q: 是否可以在模板文件中使用require来获取模块？
1218 | 
1219 | A: 可以。
1220 | 
1221 | Q: 如何使用内置的统计文章访问次数功能？
1222 | 
1223 | A: 以下是一个示例代码，建议在post成功之后在本地加入标记，减少请求次数。
1224 | 
1225 | ```javascript
1226 | var search = window.location.search;
1227 | var result = search.match(/id=(\d+)/);
1228 | var art_id = result ? result[1] : 0;
1229 | $.post(
1230 |     modules.url.setUrl('api', 'count', {m: 'visit'}),
1231 |     {id: art_id}
1232 | );
1233 | ```
1234 | 
1235 | Q: 如何使用内置的统计文章点赞次数功能？
1236 | 
1237 | A: 以下是一个示例代码，建议在post成功之后在本地加入标记，减少请求次数。
1238 | 
1239 | ```javascript
1240 | var search = window.location.search;
1241 | var result = search.match(/id=(\d+)/);
1242 | var art_id = result ? result[1] : 0;
1243 | $.post(
1244 |     modules.url.setUrl('api', 'count', {m: 'like'}),
1245 |     {id: art_id}
1246 | );
1247 | ```


--------------------------------------------------------------------------------