Solo 皮肤开发指南

皮肤开发

框架简介

solo/src/main/webapp 页面结构

|- admin                        // 后台管理
|- common-template              // 通用模版
|  |- kill-browser.ftl          // 对非现代浏览器展现的提示
|  |- label.ftl                 // js 中需要使用到的 Java 变量
|  |- macro-comment_script.ftl  // 评论宏
|  |- macro-common_head.ftl     // html 中的 head 宏
|  |- macro-common_page.ftl     // 皮肤以外的其他页面宏
|  |- macro-user_site.ftl       // 用户自定义的站点宏
|  |- search.ftl                // 搜索页面
|  |- start.ftl                 // 开始使用页面，即登录/注册
|  |- share.ftl                 // 分享，需配合 page.share() 使用
|  |- toc.ftl                   // 文章目录
|  |- top-bar.ftl               // 皮肤顶部导航栏，可选
|- error                        // 错误页面
|- images                       // 通用图片
|- js                           // js 目录
|  |- admin                     // 后台 js 
|  |- lib                       // js 第三方库
|  |- common.js                 // 通用方法
|  |- page.js                   // 文章页面通用方法
|  |- pjax.js                   // 页面跳转无刷新的
| - markdowns                   // 存放导入的 markdowns
| - plugins                     // 插件
| - scss                        // 样式文件
|- skins                        // 参见下面的皮肤结构
|- WEB-INF                      // 页面资源配置
|- CHANGE_LOGS.html             // 版本修改历史
|- manifest.json.tpl            // 移动站点描述模版
|- robots.txt                   // 爬虫设置
|- sw.js                        // service work 文件

solo/src/main/webapp/skins/skin-name 皮肤结构

|- css                       // 样式目录
|  |- fonts                  // 字体文件
|  |- base.scss              // 使用 sass，尽量避免使用行内样式及页内样式
|  |- base.css               // npm run build 后根据 base.scss 生成
|- images                    // 图片目录
|- js                        // JavaScript 目录
|  |- common.js              // 脚本，尽量避免在 ftl 中写脚本
|  |- common.min.js          // npm run build 后根据 common.js 生成
|- 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          // 文章列表，可复用于有文章列表的页面
|- categories.ftl            // 分类页面
|- category-articles.ftl     // 某分类下的文章列表页面
|- common-comment.ftl        // 评论模版
|- dynamic.ftl               // 动态页面
|- footer.ftl                // 页尾
|- header.ftl                // 页头
|- index.ftl                 // 首页页面
|- links.ftl                 // 链接列表页面
|- author-articles.ftl       // 某用户所写的文章列表页面
|- macro-comments.ftl        // 评论列表及回复的宏
|- preview.png               // 皮肤首页截图，大小为 280px * 160px
|- side.ftl                  // 侧边栏
|- skin.properties           // 皮肤信息
|- tag-articles.ftl          // 某标签的文章列表页面
|- tags.ftl                  // 标签列表页面

开发步骤

安装 node 环境，根目录下运行 npm install
在 solo/src/main/webapp/skins 目录下按照皮肤结构创建对应的文件夹及文件。可参照 nijigen 皮肤
根目录下运行 npm run dev ，保持对 CSS、JavaScript 文件的热编译，以便实时生成浏览器可运行的的 CSS 、JavaScript 文件
从 index.ftl 开始入手依次编写页面
编写完成后运行 npm run build 对 CSS、JavaScript 文件进行编译和压缩

Pjax 使用

scss 文件中添加 @import "../../../scss/nprogress";
页面中需要 pjax 的部分请参照以下代码进行修改

<div id="pjax">  
<#if pjax><!---- pjax {#pjax} start ----></#if>
我是需要 pjax 的内容
<#if pjax><!---- pjax {#pjax} end ----></#if>  
</div>
...
<#if pjax><!---- pjax {#pjax} start ----></#if>
我是需要 pjax 的脚本
<#if pjax><!---- pjax {#pjax} end ----></#if>

调用 Util.initPjax
在文章页面、首页、其他页面来回切换进行 pjax 测试，检查功能和脚本是否正常。

vcomment 使用

vcomment 简介：🧵 B3log 分布式社区的评论组件，欢迎加入下一代社区网络。

使用静态皮肤和文章同步，需添加 vcomment 组件。使用时请注意保持元素属性及属性值。

<!-- vcomment 组件 -->
<div id="vcomment" data-name="${article.authorName}" data-postId="${article.oId}"></div>
<!-- solo 原生评论组件 -->
<div id="soloComments" style="display:none">
    <@comments commentList=articleComments article=article></@comments>
</div>

uvstat 使用

uvstat 简介：📈 B3log 分布式社区的浏览、评论计数组件，欢迎加入下一代社区网络。

浏览
使用 span 标签将访问数进行包裹，并加上 data-uvstaturl 属性，其值为该访问数对应的链接地址
```
 <span data-uvstaturl="${servePath}${article.articlePermalink}"> ${article.articleViewCount} </span> 
```
评论
使用 span 标签将评论数进行包裹，并加上 data-uvstatcmt 属性，其值为该评论数对应的文章 id
```
 <span data-uvstatcmt="${article.oId}"> ${article.articleCommentCount} </span> 
```

注意事项

皮肤下的样式文件 css/base.scss 和脚本文件 js/common.js 请保持名称的统一，否则无法进行编译
不可修改 .css 文件或 .min.js 文件，否则运行 npm run dev 或 npm run build 命令时会被覆盖
macro-comments.ftl 中标签 id 不可进行更改
可引入公共的 scss [遵循 BEM 规范] src/main/webapp/scss 、公共的 js src/main/webapp/js 和公共的模版 src/main/webapp/common-template 以保持功能的一致性和减轻开发量
发布到生产环境需在根目录下运行 npm run build 以进行代码合并及压缩

模板变量

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

公共模板变量

⚠️ 某些变量只能在 side.ftl 中使用，其他 ftl 需使用可通过 <#include "side.ftl"> 进行引入

变量	类型	说明
hljsTheme	String	代码高亮主题
usite	Map	用户站点配置信息
footerContent	String	页脚自定义内容
adminUser	JSONObject	管理员
userName	String	当前登录用户名
isIndex	Boolean	判断是否是首页
faviconAPI	String	获取 favicon API 地址
isLoggedIn	Boolean	用户登录判断
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	用户自定义的描述
mostUsedTags	List	引用最多的标签列表
noticeBoard	String	用户自定义的公告栏
oId	String	存档日期对象 Id
pageNavigations	List	自定义页面列表
paginationFirstPageNum	Integer	文章列表分页第一页页码
paginationLastPageNum	Integer	文章列表分页最末页页码
paginationPageNums	List	文章列表分页页号
paginationPageCount	Integer	文章列表页数
skinDirName	String	当前使用的皮肤目录名
statistic	JSONObject	统计信息对象
onlineVisitorCnt	Integer	在线访客统计数
users	List	用户列表
version	String	当前使用的 Solo 版本
year	String	当前年份
loginURL	String	登录 URL
logoutURL	String	登出 URL
staticSite	Boolean	是否为静态站点

archive-articles.ftl

变量	类型	说明
archiveDate	JSONObject	存档日期对象
articles	List	文章列表

archives.ftl

变量	类型	说明
archiveDates	List	存档列表

article.ftl

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

author-articles.ftl

变量	类型	说明
authorName	String	用户名

categories.ftl

变量	类型	说明
categories	List	分类列表

category-articles.ftl

变量	类型	说明
category	JSONObject	分类对象
articles	List	文章列表

links.ftl

变量	类型	说明
links	List	链接列表

tag-articles.ftl

变量	类型	说明
tag	JSONObject	标签对象
articles	List	文章列表

tags.ftl

变量	类型	说明
tags	List	标签列表

预览下载

官方皮肤

Bubble 预览
Casper 预览
Pinghsu 预览
Jane 预览

其余 16 个皮肤

nijigen 预览
Medium 预览
9IPHP 预览
Andrea 预览
Bruce 预览
Community 预览
favourite 预览
Finding 预览
i-nove 预览
metro-hot 预览
NeoEase 预览
next 预览
owmx-3.0 预览
timeline 预览
tree-house 预览
yilia 预览

社区皮肤

在此感谢 B3log 社区 Solo 爱好者的贡献

solo-nexmoe 下载预览
solo-star 下载预览
solo-aragaki 下载预览
amaze 下载预览

全局预览

可直接访问 https://b3log.org/solo ，点击皮肤预览进行查看。

新皮肤推荐

大家可以在 issue #6 下跟帖来推荐皮肤，我们会按点赞数进行参考并融入自己的风格后进行制作。当然，也欢迎大家参考本帖后自行开发。

加入开发

回贴提供皮肤下载及演示地址
官方进行测试及反馈
将皮肤链接加入 https://b3log.org/solo/#themes 官网及本帖中

pengljun • 5 年前 • 2 • 1 赞同

下载地址：https://github.com/pengljun/solo-aragaki.git
预览地址：http://blog.konngo.cn/?skin=solo-aragaki

移植过来的一款非常好看的皮肤....

zjhch123 • 5 年前 • 1

目录结构是不是漏了一个 category.ftl 用于展示所有文章分类？

54 回帖