皮肤开发

框架简介

solo/src/main/webapp/skins/skin-name    
|- css                       // 样式目录
|  |- fonts                  // 字体文件
|  |- selection.json         // 如使用 icomoon.io,请上传原文件
|  |- base.scss              // 使用 sass,npm run dev 可生成 base.css 文件
|  |- base.css               // 样式,尽量避免使用行内样式及页内样式
|  |- base.min.css           // npm run build 后根据 base.css 生成
|- images                    // 图片目录
|- js                        // JavaScript 目录
|  |- common.js              // 脚本,尽量避免在 ftl 中写脚本
|  |- common.min.css         // 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          // 文章列表,可复用于有文章列表的页面
|- 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 目录下按照皮肤框架创建对于的文件夹及文件。
  • 可参照 nijigen 目录中的文件进行创建及相应的修改。
  • 建议从 index.ftl 开始入手。
  • 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 使用

  1. 引入 ${staticServePath}/js/lib/compress/pjax.min.js [已包含 jquery-3.1.0.min.js]
  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

注意事项

  1. macro-comments.ftl 中标签 id 不可进行更改。
  2. 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>.
  3. 使用 Sass 或代码压缩需先在根目录运行 npm install
  4. 使用 Sass 开发,在根目录下运行 npm run dev 即可监听文件变化生成对应的 css 文件;可引入公共的 Sass 文件 [遵循 BEM 规范] src/main/webapp/scss
  5. 压缩 JS、CSS,需在根目录下运行 npm run build

模板变量

  • 如果模板变量的类型是 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 上一篇文章标题

page.ftl

变量 类型 说明
page JSONObject 自定义页面对象
pageComments List 自定义页面评论列表

tag-articles.ftl

变量 类型 说明
tag JSONObject 标签对象

tags.ftl

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

预览下载

官方皮肤

社区皮肤

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

全局预览

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

新皮肤推荐

加入开发

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

感谢    关注    收藏    赞同    反对    举报    分享