多客内容管理系统-模板开发

多客内容管理系统 dkcms 模板标签

1.定义一套新 dkcms 模板

一套独立的模板，必须在 dkcms 根目录下的 template目录下，有一个独立每个子目录。同时，目录中必须包含 tpl.info 文件，文件中包含如下信息：

           name:dk-blog 极简1号 
           author: dkcms
           authorInfo: dkcms 模板小组
           description:参考 https://hyunseob.github.io/ 简洁模板
           snapshot:
           type:enjoy
           tag:个人博客,blog,信息门户       

其中个字段含义如下：

字段名称	含义
name	模板名称，会显示在模板界面上
author	模板作者
authorInfo	模板作者信息
description	模板简介
snapshot	缩略图的url
type	模板引擎的类型，应该为 enjoy 或者thymeleaf。如果留空，则默认值为thymeleaf。
tag	模板标签，逗号分割的字符串

2.模板至少需要由哪些文件组成

模板目录下，至少需要有下列模板文件：

序号	模板文件名	说明	动态访问路径
1	index.html	首页模板	/site
2	category.html	一格栏目的首页的模板	/site/category?categoryId=xxx
3	content.html	内容详情页面的模板	/site/article?articleId=xxxx
4	page.html	单页面的模板	/site/page?pageId=1

在打开某种页面或者生成该类型静态页面的时候，系统会加载改模板，如果模板文件不存在，则加载失败，系统报错。如果站点没有此类页面，则此类模板可以没有。比如，某站点没有用到单页面内容，则不需要page.html。某站点没有内容详情页，content.html 模板不存在也美关系。

所以，常规来看，站点一般至少需要 index.html 和 category.html。当然除了上面四个最常用模板文件，dkcms 还应该包含以下模板文件

序号	模板文件名	说明	动态访问路径
5	list.html	列表页面，如果站点首页或者栏目首页中，使用了分页标签PageNav，则系统再生成该页面的同时，也会生成pageNav 分页标签中所有页面的静态页，使用 list.html 模板。生成的静态文件路径为当前栏目路径下 list-$categoryId-${pageId}.html	/site/list?categoryId=1&page=1
6	tag.html	根据tagid，获取所有属于这个标签的内容，并列表展现，使用这个模板	/site/tag?tagId=1
7	search.html	搜索结果页面使用这个模板，是动态请求	/site/search?kw=xxx
8	album.html	图册栏目的模板。如果栏目类型被设定为 图集，则渲染页面是，会尝试使用album.html	/site/category?id=1
9	album-content.html	同上，图册栏目的内容页模板	/site/article?id=1

3.用户注册、登录、评论相关

序号	文件名	说明	动态访问路径
11	/register	用户注册,模板不能定制	/register
12	/login	登录界面，模板不能定制	/login
13	/search	内容索索界面，使用search.html 模板	/site/search?kw=1
14	/site/userInfo	接口，获取当前用户登录状态，如果已登录，返回用户信息
15	/site/getComment	接口，或者当前内容的评论列表	参数id:内容id ；参数start:开始偏移量
16	/site/saveComment	接口，保存评论内容	参数id：内容id;参数comment:评论内容

4.默认模板和指定模板

默认模板
以上模板文件被称为 默认模板。当一个栏目或者内容，未指定特定模板文件时，dkcms会按照上述规则，使用对应的默认模板。

指定模板
在添加栏目和内容时，选定了某个模板文件名，则加载时使用指定的模板。

5.模板输出基本语法

• 普通变量
  #(对象) // 将输出对象的json序列化
  #(变量名)
  #(对象.属性)

• 判空
  #(isBlack(变量))

• 三目运算符

#(isBlack(变量)?'true':'false')

• 判断

#if()
some thing
#else
other thing
#end

• 循环

#for(item: list)
#(item.a)
#(item.b)
#end

6.模板内置全局变量

所有模板中均可以直接使用以下变量

变量名	类型	说明
#(pageType)	页面类型	string	此变量值就是页面类型枚举值的字面量 ，比如SITE_HOMEPAGE等等，可以在模板中，用来判断当是哪个页面
#(global.setting)	map	所有系统设置kv值	#(globa.setting.siteTitle) 站点标题 #(globa.setting.can_register) 是否可以注册
#(global.category)	list	栏目数	遍历
#(global.cmsName)	string	dkcms标题
#(global.cmsVersion)	string	dkcms 版本号
#(global.singlePage)	list	单页面VO列表	遍历可以得到所有单页面

7.各类型页面自有变量

上边变量均可在所有页面中使用输出。同时，dkcms 就将所有页面归纳为如下几种类型：

页面类型	页面类型	对应模板	已内置变量
SITE_HOMEPAGE	站点首页	index.html	#(category)，#(categoryId)，#(page)
CATEGORY_HOME	栏目首页	category.html	#(category)，#(categoryId)，#(page)
CATEGORY_LIST	栏目列表	list.html(album.html)	#(articleListPageInfo)，#(articleList)
CATEGORY_ARTICLE	内容页面	content.html(album-content.html)	#(category)，#(categoryId)，#(article)，#(articleId)
SINGLE_PAGE	单页面	page.html	#(singlePage),#(singlePageId)，#(page)
SITE_MAP	sitemap文件
ARTICLE_LIST_BY_TAG	tag内容列表	tag.html	#(tagId)，#(tagVo)，#(articleList)
SEARCH_RESULT	搜索	search.html	#(searchKeyword)，#(articleList)

其中，categoryId，contentId，tagId 等均为 int 型
其中，article，类型为 ArticleVo；category，类型为CategoryVo；singlePage，类型为singlePageVo；tagVo 类型为TagVo ；articleList 类型为 List
其中，#(page)为翻页页码。SINGLE_PAGE 页面中，#(page) 为 SinglePageVo

8.页面渲染核心逻辑

页面类型：类 DkCmsRenderPageType

渲染上下文：类 DkCmsRenderContext

Render: 类 DkCmsRender

DKCMS 中，生成静态页面和预览，都是渲染任务，代码流程完全相同。不同的是，输出目标不同。生成静态页面，代码逻辑在 ControllerPageGenerate 中，页面预览代码逻辑再 ControllerSite 中。但两处代码的渲染逻辑完全相同，伪代码如下：

//1.得到 context。以上每种类型的，都在contextFactory 中对一个了一种工厂方法

DkCmsRenderContext context = contextFactory.getCategoryArticleContext(articleId)

//2. 实例化模板引擎

 DkCmsRender render = new DkCmsRender();
 
 // 3 .渲染并输出到一个输出流
 Result result = render.renderToWriter(context,writer)