前言

前一篇文章
介紹瞭如何通過Cabloy-CMS快速搭建一個博客站點。

這裏簡單介紹Cabloy-CMS靜態站點的渲染機制，更多詳細的內容請參見https://cms.cabloy.org

渲染規則

渲染時機

爲了平衡渲染性能，Cabloy-CMS提供了兩個渲染時機：一次構建、文章單獨渲染

一次構建

在CMS配置頁面，點擊構建按鈕，一次性渲染並輸出站點所有文件

文章單獨渲染

當發佈文章時，立即渲染文章，並渲染與文章相關的頁面。

比如首頁頁面：爲了提升首頁加載性能，首頁可能會包含最近發佈的文章。所以，當文章單獨渲染時，也會再次渲染首頁

SEO相關

SEO文件有三個：robots.txt、sitemapindex.xml、sitemap.xml

SEO文件均在構建時一次性輸出

sitemapindex.xml包含不同語言的sitemap.xml鏈接，一個語言對應一個sitemap.xml文件

當文章單獨渲染時，會修改sitemap.xml的內容

目錄、標籤、搜索

由於使用了站點地圖文件，並且所有文章都已經渲染成靜態文件，所以，目錄、標籤、搜索等場景下的文章清單，沒必要提前渲染，只需在需要時通過ajax調用後端API獲取清單並動態顯示

CMS、主題、插件

模塊a-cms只提供了基本的渲染機制和渲染骨架，具體的頁面佈局、元素、功能，都通過主題和插件的組合實現。這種模式，既可以快速開發部署，也可以充分釋放CMS的可擴展性和靈活性

Cabloy-CMS目前提供了主題模塊cms-themeblog、cms-themeaws和插件模塊cms-pluginbase、cms-pluginarticle、cms-pluginsidebar、cms-pluginmarkdowngithub、cms-plugintrack，實現了全功能的博客站點，後續也會持續推出一系列主題和插件

您可以自由組合主題和插件，甚至實現自己的主題和插件，呈現完全不同的站點效果。

也希望您能分享您的智慧與成果，加入到Cabloy的生態中來

文件結構

Cabloy-CMS採用精細的文件結構，帶來了如下便利：

便於定製CSS、JS
便於定製圖片等各類靜態資源
便於實現多語言
便於調試與發佈

建議先把服務運行起來，並構建一次，就可以清晰的看到Cabloy-CMS的文件結構

根目錄

在開發環境中，爲了便於調試，CMS文件根目錄位於源代碼項目內部。而在生產環境中，源代碼項目可能是隻讀的，所以CMS文件根目錄缺省放置在當前用戶的Home目錄中。

開發環境

根目錄：[ProjectDir]/src/backend/app/public/[InstanceId]/cms

InstanceId: 實例Id，通過多實例可以實現多CMS站點的搭建

運行環境

根目錄：[HomeDir]/cabloy/[ProjectName]/public/[InstanceId]/cms

HomeDir: 默認爲當前用戶的Home目錄，可以通過模塊a-file配置

src/backend/config/config.prod.js

config.modules = {
  'a-file': {
    publicDir: 'CustomDir',
  },
};

一級目錄

名稱	說明
dist	`構建`的輸出目錄
en-us/zh-cn	語言源碼目錄

輸出目錄

名稱	說明	渲染時機	備註
articles	存儲所有渲染的文章頁面	一次構建
assets	資源文件	一次構建
plugins	插件的資源文件	一次構建
static	靜態文件	一次構建	如文件`articles.html`，通過ajax調用後端API獲取文章清單，從而可以集中實現`目錄`、`標籤`、`搜索`等功能
zh-cn	其他語言的文件輸出目錄		支持多語言時，缺省語言在`根目錄`下，其他語言在`子目錄`下
index.html	首頁	兩個渲染時機	爲了提升首頁加載性能，首頁可能會包含最近發佈的文章。所以，當`文章`單獨渲染時，也會再次渲染`首頁`
robots.txt	SEO相關	一次構建	不論是否有多語言，只有一個`robots.txt`在`根目錄`下
sitemap.xml	SEO相關，當前語言的站點地圖文件	一次構建，`文章`單獨渲染時修改內容
sitemapindex.xml	SEO相關，站點地圖文件索引	一次構建	不論是否有多語言，只有一個`sitemapindex.xml`在`根目錄`下

語言源碼目錄

名稱	說明	備註
intermediate	中間文件目錄	在一次`構建`時，將`主題`、`插件`、`自定義源碼`的所有源碼文件和資源統一寫入`intermediate`目錄，然後再執行渲染邏輯
custom	自定義源碼目錄	用戶可以在`custom`目錄添加自定義源碼文件，在一次性`構建`時，會自動覆蓋`intermediate`中相同路徑的文件
custom/dist	特別輸出目錄	在實際生產環境中，會有一些第三方用途的文件，如`Google站點驗證文件`，可以放置在這個目錄，以便一次`構建`時輸出

名稱	說明	渲染時機	備註
assets	資源文件	一次構建
layout	佈局目錄	中間文件	`layout`不是官方強制定義的目錄。主題可根據自己的需要添加，規劃自己的頁面元素
main	主渲染模版目錄	兩個渲染時機
main/article.ejs	文章渲染模版		當需要渲染`文章`時使用此模版文件
main/index	首頁渲染模版目錄		當需要渲染`首頁`時使用此目錄中的模版文件。爲什麼是目錄？在一個複雜的站點中，根據場景需要可以有多個類`首頁`模版文件
plugins	插件目錄	一次構建	在一次`構建`時，把所有`插件`源碼文件和資源寫入`plugins`目錄
static	靜態文件目錄	一次構建	如文件`articles.ejs`，通過ajax調用後端API獲取文章清單，從而可以集中實現`目錄`、`標籤`、`搜索`等功能

爲什麼需要把所有源碼文件（主題、插件、自定義源碼）都寫入intermediate目錄？

寫入一個目錄，便於各文件之間的包含引用

渲染流程

Cabloy-CMS提供了兩個渲染時機：一次構建、文章單獨渲染，下面分別描述兩個時機的渲染流程

合併站點配置

在渲染之前，先合併站點配置信息

一次構建

文章單獨渲染

後端上下文對象

Cabloy-CMS採用ejs模版引擎進行頁面渲染，在渲染之前創建一個上下文對象，歸集相關的數據和方法，以便在模版文件中使用

上下文對象結構

{
  ctx: [Object],
  site: [Object],
  require: [Function],
  url: [Function],
  css: [Function],
  js: [Function],
  env: [Function],
  text: [Function],
  util: {
    time: {
      now: [Function],
      today: [Function],
      formatDateTime: [Function],
      formatDate: [Function],
      formatTime: [Function]
    },
    formatDateTime: [Function]
  },
  article: [Object],
  _path: [String]
}

名稱	類型	說明
ctx	屬性	通過ctx對象可以調用後端API及各種資源
site	屬性	站點配置信息
require	方法	引用模塊
url	方法	構造絕對鏈接
css	方法	聲明css文件，以便最後合併和最小化
js	方法	聲明js文件，以便最後合併和最小化
env	方法	注入環境變量，以便輸出到前端使用
text	方法	文本國際化
util	屬性	工具函數
article	屬性	當前渲染的文章信息
_path	屬性	標示當前模版文件的相對路徑（相對於目錄intermediate）

訪問後端資源

通過ctx對象可以調用後端API及各種資源

比如，爲了渲染菜單，需要獲取目錄樹，可以如下操作

const res = await ctx.performAction({
  method:'post',
  url: '/a/cms/category/tree',
  body: { language:site.language.current,hidden:0 },
});
const tree=res.list;

引用模塊

在.ejs文件中，也可以像在NodeJS中一樣引用模塊

// 引用node_modules中的模塊
const moment=require('moment');
// 引用項目內的文件模塊
const test=require('./test.js');

絕對地址

建議頁面中所有資源的URL鏈接都渲染成絕對地址

// 相對於網站根目錄
<%=url('assets/images/background.png')%>
// 相對於當前文件
<%=url('./fonts/github/700i.woff')%>

合併和最小化CSS、JS

在渲染過程中，先聲明CSS和JS文件，然後在最後進行合併和最小化。在渲染模版中提供佔位符，替換爲生成的實際URL鏈接

聲明CSS、JS

// css
css('../assets/css/markdown/github.css.ejs');
css('../assets/css/article.css');
css('../assets/css/sidebar.css');
// js
js('../assets/js/lib/json2.min.js');
js('../assets/js/lib/bootbox.min.js');
js('../assets/js/util.js.ejs');
js('../assets/js/article.js.ejs');
js('../assets/js/sidebar.js.ejs');

如果引用的CSS、JS文件後綴名爲'.ejs'，也會作爲ejs模版進行渲染

佔位符

// CSS文件鏈接佔位符
<link rel="stylesheet" href="__CSS__">
// JS文件鏈接佔位符
<script src="__JS__"></script>

效果

<link rel="stylesheet" href="https://zhennann.me/assets/css/8d38154d198309325c0759a22213dbd6ff0b7edecd2f4868dc72311335ccbe25.css">
<script src="https://zhennann.me/assets/js/b17e06ccb536dee939d4b1deaa595436363a52769c210d74d6a77f011e0f6461.js"></script>

注入環境參數

爲了便於前端實現靈活且豐富的功能邏輯，需要把一些環境參數注入到前端。後端通過env聲明環境參數，這些參數最後會進行合併注入到前端。

同樣，也需要在前端提供佔位符，替換爲生成的實際環境參數

聲明env

env('index',{
  [_path]:data.index,
});

佔位符

// CSS文件鏈接佔位符
<link rel="stylesheet" href="__CSS__">
// ENV佔位符
__ENV__

效果

<script type="text/javascript">
var env={
  "base": ...,
  "language": ...,
  "format": ...,
  "comment": ...,
  "site": ...,
  "index": {
    "main/index/index": 20
  }
};
</script>

國際化

如果需要讓主題和插件可以應用於不同的語言，需要對其中用到的文本資源進行國際化處理

因爲主題和插件本質上都是EggBorn模塊，所以可以直接使用EggBorn模塊提供的國際化機制

比如，插件cms-pluginbase提供了無限滾動的功能，如果加載失敗需要在頁面中提示Load error, try again，可以如下操作

定義語言資源

cms-pluginbase/backend/src/config/locale/zh-cn.js

module.exports = {
  'Load error, try again': '加載失敗，請重試',
};

引用

cms-pluginbase/backend/cms/plugin/assets/js/util.js.ejs

const $buttonTry = $('<button type="button" class="btn btn-warning btn-xs"><%=text("Load error, try again")%></button>');

路徑標示：_path

一個通用的ejs模版文件可能被多個主ejs模版文件包含引用。通過_path，可以在通用ejs模版文件中知曉當前被哪個主ejs模版文件引用，以便做不同的邏輯處理

前端環境對象

爲了便於前端實現靈活且豐富的功能邏輯，需要把一些環境參數注入到前端。

Cabloy-CMS本身內置了一些前端環境對象，同時，也可以通過後端上下文對象的env方法注入自定義屬性，這些參數最後會進行合併注入到前端

注入env

env('index',{
  [_path]:data.index,
});

佔位符

// CSS文件鏈接佔位符
<link rel="stylesheet" href="__CSS__">
// ENV佔位符
__ENV__

前端環境對象結構

<script type="text/javascript">
var env={
  "base": {
    "title": "my blog",
    "subTitle": "gone with the wind",
    "description": "",
    "keywords": ""
  },
  "language": {
    "items": "en-us,zh-cn",
    "default": "en-us",
    "current": "en-us"
  },
  "format": {
    "date": "YYYY-MM-DD",
    "time": "HH:mm:ss"
  },
  "comment": {
    "order": "asc",
    "recentNum": 5
  },
  "site": {
    "path": "main/article",
    "serverUrl": "https://zhennann.cabloy.org",
    "rawRootUrl": "https://zhennann.me"
  },
  "article": ...,
  "index": {
    "main/index/index": 20
  }
};
</script>

名稱	來源	說明
base	站點配置	站點基本信息
language	站點配置	語言信息
format	站點配置	時間格式化
comment	站點配置	評論參數
site	內置參數	站點參數
site.path		當前頁面路徑標示
site.serverUrl		後端服務URL前綴
site.rawRootUrl		前端站點URL前綴
article	內置參數	如果是文章頁面，會自動注入此屬性
index	自定義參數	由主題`cms-themeblog`注入的參數

製作主題

主題既可以全新制作，也可以繼承自其他主題

在這裏新建一個主題模塊test-cmsthemehello，在首頁渲染一行Hello world

新建主題模塊

主題本質上也是EggBorn模塊

進入項目目錄，執行EggBorn提供的腳手架創建一個新模塊

$ cd /path/to/project
$ egg-born src/module/test-cmsthemehello --type=module

修改package.json

test-cmsthemehello/package.json

{
  "name": "egg-born-module-test-cmsthemehello",
  "version": "1.0.0",
  "title": "cms:theme:hello",
  "eggBornModule": {
    "cms": {
      "name": "hello",
      "theme": true,
      "extend": ""
    },
    ...
  },
  "dependencies": {
    ...
    "egg-born-module-cms-pluginbase": "^1.1.1",
    "egg-born-module-cms-pluginarticle": "^1.0.0",
    "egg-born-module-cms-pluginsidebar": "^1.0.0",
    "egg-born-module-cms-pluginmarkdowngithub": "^1.0.0",
    "egg-born-module-cms-plugintrack": "^1.0.1"
  }
}

name: 必須按照EggBorn模塊的命名規範: egg-born-module-{providerId}-{moduleName}
- providerId: 開發者Id，強烈建議採用Github的Username，從而確保貢獻到社區的模塊不會衝突
cms: CMS配置信息
- name: 主題名稱
- theme: 聲明本模塊是一個主題
- extend: 如果要繼承主題，填入原主題的模塊名如cms-themeblog
dependencies: 如果使用了插件，在這裏填入插件模塊信息。如果繼承了主題，也需要在這裏填入原主題的模塊信息

配置參數

主題可以提供自定義的參數

test-cmsthemehello/backend/src/config/config.js

module.exports = appInfo => {
  const config = {};

  // theme
  config.theme = {
    _message: 'Hello World',
  };

  return config;
};

創建首頁渲染模版

test-cmsthemehello/backend/cms/theme/main/index/index.ejs

<html>
 <head></head>
 <body><%=site._message%></body>
</html>

其他源碼及資源

根據需要添加其他源碼及資源，這裏從略

構建模塊

作爲EggBorn模塊，如果在項目內部使用，不需要構建，可以直接使用。如果分享到社區，供其他用戶安裝使用，必須進行構建

$ cd src/module/test-cmsthemehello   -- 進入模塊目錄
$ npm run build:front             -- 構建前端代碼
$ npm run build:backend           -- 構建後端代碼

發佈模塊

可以將製作好的模塊發佈到社區

$ npm publish

製作插件

在這裏新建一個插件模塊test-cmspluginhello，在頁面加載完成時彈出提示Hello world

新建插件模塊

插件本質上也是EggBorn模塊

進入項目目錄，執行EggBorn提供的腳手架創建一個新模塊

$ cd /path/to/project
$ egg-born src/module/test-cmspluginhello --type=module

修改package.json

test-cmspluginhello/package.json

{
  "name": "egg-born-module-test-cmspluginhello",
  "version": "1.0.0",
  "title": "cms:plugin:hello",
  "eggBornModule": {
    "cms": {
      "name": "hello",
      "plugin": true
    },
  },
  ...
}

name: 必須按照EggBorn模塊的命名規範: egg-born-module-{providerId}-{moduleName}
- providerId: 開發者Id，強烈建議採用Github的Username，從而確保貢獻到社區的模塊不會衝突
cms: CMS配置信息
- name: 主題名稱
- plugin: 聲明本模塊是一個插件

配置參數

插件可以提供自定義的參數

test-cmspluginhello/backend/src/config/config.js

module.exports = appInfo => {
  const config = {};

  // plugin
  config.plugin = {
    _message: 'Hello World',
  };

  return config;
};

創建初始腳本

test-cmspluginhello/backend/cms/plugin/init.js.ejs

$(document).ready(function() {
  // alert
  const message='<%=site.plugins['test-cmspluginhello']._message%>';
  window.alert(message);
});

腳本如何引用

只需在渲染模版中聲明JS文件即可

在這裏，可以在主題test-cmsthemehello的首頁模版中引用

test-cmsthemehello/backend/cms/theme/main/index/index.ejs

<% js('plugins/test-cmspluginhello/init.js.ejs') %>
<html>
 <head></head>
 <body>
  <div><%=site._message%></div>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
  <script src="__JS__"></script>
</body>
</html>

其他源碼及資源

根據需要添加其他源碼及資源，這裏從略

構建模塊

作爲EggBorn模塊，如果在項目內部使用，不需要構建，可以直接使用。如果分享到社區，供其他用戶安裝使用，必須進行構建

$ cd src/module/test-cmspluginhello  -- 進入模塊目錄
$ npm run build:front             -- 構建前端代碼
$ npm run build:backend           -- 構建後端代碼

發佈模塊

可以將製作好的模塊發佈到社區

$ npm publish

終極篇

請允許再次強調，主題和插件本質上還是EggBorn模塊，可以添加前端頁面和後端服務

大象無形，終極武器掌握在您的手中，能呈現出什麼效果，完全取決於您的想象力

歡迎貢獻您的智慧和產品到社區，謝謝！

GitHub貢獻

有任何疑問，歡迎提交 issue！

Cabloy-CMS：動靜結合，解決Hexo痛點問題（進階篇）

前言

渲染規則

渲染時機

一次構建

文章單獨渲染

SEO相關

目錄、標籤、搜索

CMS、主題、插件

文件結構

根目錄

開發環境

運行環境

一級目錄

輸出目錄

語言源碼目錄

渲染流程

合併站點配置

一次構建

文章單獨渲染

後端上下文對象

上下文對象結構

訪問後端資源

引用模塊

絕對地址

合併和最小化CSS、JS

聲明CSS、JS

佔位符

效果

注入環境參數

聲明env

佔位符

效果

國際化

定義語言資源

引用

路徑標示：_path

前端環境對象

注入env

佔位符

前端環境對象結構

製作主題

新建主題模塊

修改package.json

配置參數

創建首頁渲染模版

其他源碼及資源

構建模塊

發佈模塊

製作插件

新建插件模塊

修改package.json

配置參數

創建初始腳本

腳本如何引用

其他源碼及資源

構建模塊

發佈模塊

終極篇

GitHub貢獻