皮肤开发
框架简介
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 官网及本帖中