皮肤开发
框架简介
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、公共的 jssrc/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 | 标签列表 |
预览下载
官方皮肤
其余 16 个皮肤
社区皮肤
在此感谢 B3log 社区 Solo 爱好者的贡献
全局预览
可直接访问 https://b3log.org/solo ，点击皮肤预览进行查看。
新皮肤推荐
大家可以在 issue #6 下跟帖来推荐皮肤，我们会按点赞数进行参考并融入自己的风格后进行制作。当然，也欢迎大家参考本帖后自行开发。
加入开发
- 回贴提供皮肤下载及演示地址
- 官方进行测试及反馈
- 将皮肤链接加入 https://b3log.org/solo/#themes 官网及本帖中