Solo 皮肤开发指南

皮肤开发

框架简介

solo/src/main/webapp/skins/skin-name    
|- css                       // 样式目录
|  |- fonts                  // 字体文件
|  |- selection.json         // 如使用 icomoon.io，请上传原文件
|  |- base.css               // 样式，尽量避免使用行内样式及页内样式
|- images                    // 图片目录
|- js                        // JavaScript 目录
|  |- common.js              // 脚本，尽量避免在 ftl 中写脚本
|- lang                      // 语言配置文件，当 solo/src/main/resources/lang_zh_CN.properties 中无配置时可添加至此
|  |- lang_en_US.properties  // 英文
|  |- lang_zh_CN.properties  // 中文
|- archive-articles.ftl      // 某年某月所写文章的列表页面
|- archives.ftl              // 存档列表页面
|- article.ftl               // 文章页面
|- article-list.ftl          // 文章列表，可复用于有文章列表的页面
|- category-articles.ftl     // 某分类下的文章列表页面
|- common-comment.ftl        // 评论模版
|- dynamic.ftl               // 动态页面
|- footer.ftl                // 页尾
|- header.ftl                // 页头
|- index.ftl                 // 首页页面
|- links.ftl                 // 链接列表页面
|- author-articles.ftl       // 某用户所写的文章列表页面
|- macro-comments.ftl        // 评论列表及回复的宏
|- macro-head.ftl            // head 标签中的宏
|- page.ftl                  // 导航页面
|- preview.png               // 皮肤首页截图，大小为 280px * 160px
|- side.ftl                  // 侧边栏
|- skin.properties           // 皮肤信息
|- tag-articles.ftl          // 某标签的文章列表页面
|- tags.ftl                  // 标签列表页面

开发步骤

在 solo/src/main/webapp/skins 目录下按照皮肤框架创建对于的文件夹及文件。
可参照 91PHP 目录中的文件进行创建及相应的修改。
建议从 index.ftl 开始入手。
JS、CSS 压缩需将皮肤目录拷贝到 solo-skin/skins 下运行 cd toolers && npm install && npm run build。
JS、CSS 引用示例如下：

<link type="text/css" rel="stylesheet" href="/skins/${skinDirName}/css/base${miniPostfix}.css" />
<script src="/skins/${skinDirName}/js/common${miniPostfix}.js"></script>

Pjax 使用

引入 ${staticServePath}/js/lib/compress/pjax.min.js [已包含 jquery-3.1.0.min.js]
引入 ${staticServePath}/js/lib/nprogress/nprogress.css
页面中加入

<div id="pjax">  
<#if pjax><!---- pjax {#pjax} start ----></#if>

<#if pjax><!---- pjax {#pjax} end ----></#if>  
</div>

文章页面需把 id="pjax" 改为 id="pjaxArticle"；{#pjax} 改为 {#pjaxArticle}
4. 调用 Util.initPjax

⚠️️ 具体可参考皮肤 Medium

注意事项

macro-comments.ftl 中标签 id 不可进行更改。
文章内容须加上 class=“article-body”，否则不能进行代码高亮。
footer.ftl 中版权声明格式如下：

Powered by <a href="https://b3log.org">B3log 开源</a> • <a href="https://hacpai.com/tag/solo">Solo</a>  
Theme by <a href="your site">your-name</a>.

模板变量

如果模板变量的类型是 JSONObject，其字段属性参考 org.b3log.solo.model 包下的类
每个页面都包含一些公共模板变量，这些模板变量单独列出（不在 *.ftl 表中给出）
每个页面的模板变量如以 Label 结尾，则为多语言配置文件，参看 lang_zh_CN.properties

公共模板变量

变量	类型	说明
footerContent	String	页脚自定义内容
adminUser	JSONObject	管理员
userName	String	当前登录用户名
isIndex	Bool	判断是否是首页
faviconAPI	String	获取 favicon API 地址
isLoggedIn	Bool	用户登录判断
gravatar	String	当前登录人的 gravatar 地址
runtimeMode	String	运行模式，例如 DEVELOPMENT
runtimeEnv	String	运行环境，例如 GAE
pageType	String	当前页面类型，例如 Index，Article，DateArticles
servePath	String	应用路径，可在 latke.properties 中配置
staticServePath	String	静态资源路径，可在 latke.properties 中配置
staticResourceVersion	String	js, css 版本号，防止缓存
topBarReplacement	String	公用 top-bar.ftl 内容
path	String	Action 路径
archiveDates	List	存档日期列表
articles	List	存档文章列表
blogTitle	String	博客标题
blogHost	String	博客地址
blogSubtitle	String	博客子标题
htmlHead	String	用户自定义的 HTML Head
links	List	链接列表
localeString	String	区域设定字符串
metaKeywords	String	用户自定义的关键字
metaDescription	String	用户自定义的描述
mostCommentArticles	List	评论最多的文章列表
mostUsedTags	List	引用最多的标签列表
mostViewCountArticles	List	访问最多的文章列表
noticeBoard	String	用户自定义的公告栏
oId	String	存档日期对象 Id
pageNavigations	List	自定义页面列表
paginationFirstPageNum	Integer	文章列表分页第一页页码
paginationLastPageNum	Integer	文章列表分页最末页页码
paginationPageNums	List	文章列表分页页号
paginationPageCount	Integer	文章列表页数
recentComments	List	最新评论列表
skinDirName	String	当前使用的皮肤目录名
statistic	JSONObject	统计信息对象
onlineVisitorCnt	Integer	在线访客统计数
users	List	用户列表
version	String	当前使用的 Solo 版本
year	String	当前年份
loginURL	String	登录 URL
logoutURL	String	登出 URL

archive-date-articles.ftl

变量	类型	说明
archiveDate	JSONObject	存档日期对象

article-detial.ftl

变量	类型	说明
article	JSONObject	文章对象
articleComments	List	文章评论列表
externalRelevantArticlesDisplayCount	Integer	站外相关文章显示数
nextArticlePermalink	String	下一篇文章链接
nextArticleTitle	String	下一篇文章标题
previousArticlePermalink	String	上一篇文章链接
previousArticleTitle	String	上一篇文章标题