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                  // 标签列表页面

开发步骤

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

Pjax 使用

2. scss 文件中添加 @import "../../../scss/nprogress";
3. 页面中需要 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>  

4. 调用 Util.initPjax
5. 在文章页面、首页、其他页面来回切换进行 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"> 进行引入

archive-articles.ftl

archives.ftl

article.ftl

author-articles.ftl

categories.ftl

category-articles.ftl

links.ftl

tag-articles.ftl

tags.ftl

预览下载

官方皮肤

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

社区皮肤

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

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

全局预览

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

新皮肤推荐

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

加入开发

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