尤娜主題渲染標籤指南-Part I(V1.2.2版本)

​Una | 尤娜

一個基於Spring Boot 2.0構建的Java博客系統​

序言

實現尤娜主題渲染標籤的目的是為了能夠加快主題皮膚的製作，對於不熟悉Java語言或者對Spring Boot不太瞭解的朋友也能快速的定製出自己的博客主題。尤娜主題渲染標籤是在Freemarker框架的基礎上實現的，沿用了Freemarker的基礎標籤，如邏輯判斷（if語句，if...else語句，多重if...else語句，switch語句等），數據迭代（對象數組，分頁），數據格式化（時間格式化）以及數據排序等。尤娜主題渲染標籤分為全局常量，內容標籤，格式化函數，腳本函數和分頁函數五類，在接下來的內容中，將做詳細介紹。下面是Freemarker的基本原理圖，對Freemarker不是太熟悉的朋友可訪問其官網(https://freemarker.apache.org/) 瞭解更多詳細的知識。

FreeMarker

1.擴展

尤娜主題渲染標籤支持二次擴展，只需要讓自定義的解析類繼承AbstractUnaBootDirectiveModel.java類或者AbstractMethodModel.java類即可。尤娜會自動將擴展的解析類配置到Freemarker的上下文中。AbstractUnaBootDirectiveModel.java主要用於定義取值標籤，而AbstractMethodModel.java類主要用於定義插件函數。你可以在com.ramostear.unaboot.freemarker包中找到這兩個類。接下來，將列舉兩個小列子，演示如何擴展尤娜的主題渲染標籤。

NumberFormat.java

<code>@Service
public class NumberFormat extends AbstractMethodModel {
    @Override
    public Object exec(List arguments) throws TemplateModelException {
        int number = getInteger(arguments,0);
        DecimalFormat format = new DecimalFormat("###,###");
        return format.format(number);
    }
}/<code>

首先，需要使用@Service對類進行註解，表面這是一個被Spring容器所管理的Bean，然後繼承AbstractMethodModel類，並重寫exec()方法。這樣就簡單的定製了一個數值格式化的函數。在尤娜系統中，對函數和標籤的名稱做了區分(前綴都為“u_”)，函數採用駝峰命名法且首字母小寫，標籤名稱在駝峰命名法的基礎上使用下滑線進行分割(無大寫)。定義完函數後，便可通過下面的方式使用NumberFormat:

html

<code>

     ${u_numberFormat(1024666996)}
    /<code>

Output

<code>1,024,666,996/<code>

說明：

傳入的1024666996將會以科學計數法的方式進行格式化，最後輸出1,024,666,996

Navigation.java

<code>@Service
public class Navigation extends AbstractUnaBootDirectiveModel {
​
    @Autowired
    private CategoryService categoryService;
​
    @Override
    public void execute(DirectiveHandler handler) throws Exception {
        List<category> data = categoryService.navigation();
        if(CollectionUtils.isEmpty(data)){
            handler.put(MULTI,new ArrayList<category>()).render();
        }else{
            handler.put(MULTI,data).render();
        }
    }
}/<category>/<category>/<code>

最後，以導航欄標籤為例，介紹取值標籤的定義。取值標籤需要繼承AbstractUnaBootDirectiveModel類，然後使用@Service進行註解，然後重寫execute()方法，實現具體的業務邏輯，最後將數據通過handler返回到模板中。尤娜系統默認了兩個數據的名稱：SINGLE和MULTI，值分別是“result”和“results”。現在，我們可以在模板中按照以下的方式使用Navigation標籤：

html

<code>
    
        
            
        #list>
    #if>
@u_navigation>/<code>

此外，我們還可以使用Freemarker的sort_by()對數據進行排序,例如：

<code>
    
        
            
        #list>
    #if>
@u_navigation>/<code>

注意：

sort_by()和reverse可以單獨使用，sort_by()是升序排列，reverse是降序排列；兩者也可以同時使用，上面的例子中，將導航欄目按照id進行降序排列。

2.全局常量

全局常量主要針對尤娜博客的基本配置信息，如站點名稱，域名，Logo,備案號，版權信息等。下表列出了尤娜主題渲染標籤所包含的所有全局常量標籤(una-boot-v1.2.2版本)：

尤娜全局常量列表

提示：

在使用全局常量時，最好做空值處理（!'xxxx'），提供一個默認值，因為尤娜主題渲染標籤是在Freemarker的基礎上實現的，Freemarker就像一個玻璃製品，好用漂亮，但易碎！！！最好是在取值時做好空值處理。

3.格式化函數

在尤娜v1.2.2版本中，共提供了5個格式化函數，它們時字符串長度截取函數u_ellipsis(),數值格式化函數u_numberFormat()，字數統計函數u_wordNumber(),時間格式化函數u_timeAgo()和閱讀時間計算函數u_readTime()。

3.1 u_ellipsis()

在製作主題時，往往會遇到字符串的長度超過div的寬度，需要對字符串進行截取。我們可以通過CSS3或者Freemarker自帶的substring()對字符串進行截取，但兩種方式相對來說都比較麻煩，因此，從尤娜1.2.0版本開始便提供了內置的字符串截取函數u_ellipsis()。該函數接收兩個參數，一個是字符串，一個是截取長度，當字符串長度超過所設置的長度時，會自動對字符串進行截取，並在截取的字符串末尾添加“...”。下面是u_ellipsis()函數使用示例：

Data

<code>String msg = "尤娜是一個開源免費的博客系統，使用Java語言進行開發";/<code>

u_ellipsis()

<code>${u_ellipsis(msg 17)}/<code>

Output

<code>尤娜是一個開源免費的博客系統.../<code>

3.2 u_numberFormat()

通常，我們都會在網頁中對數字進行格式化輸出，如科學計數法(1,100,000)，用K代表千(1K,10K)。在尤娜系統中，提供了以科學計數法對數值進行格式化輸出的函數u_numberFoarmat(),該函數接收一個數值參數，下面是函數使用示例：

Data

<code>Integer total = 1314996;/<code>

u_numberFormat()

<code> ${u_numberFormat(total)}/<code>

Output

<code>1,314,996/<code>

3.3 u_wordNumber()

在尤娜主題中，可以使用u_wordNumber()函數對文章的字數進行統計，在醒目的位置告知讀者當前文章有多少字。下面是我個人博客中的一個截圖：

u_wordNumber()函數

下面是u_wordNumber()使用示例，該函數接收一個字符串參數：

Data

<code>String content = "尤娜是一個基於Spring Boot 2.0 進行構建的Java博客系統"/<code>

u_wordNumber()

<code>本文共計${u_wordNumber(content)}個字/<code>

Output

<code>本文共計21個字/<code>

補充

u_wordNumber()會自動將內容中的空格，標點符號，換行符等剔除再計算字數，英文以空格切分計算。

3.4 u_timeAgo()

u_timeAge()函數用於計算文章發佈時間到當前的時間長度，並以秒，分，小時，天，月和年格式化時間。假設我們有如下的幾個文章發佈時間：

Data

<code>String date1 = "2019-01-01 12:00:00";
String date2 = "2019-12-31 00:59:00";
String data3 = "2020-01-01 00:00:00";/<code>

假設當前時間為2020-01-01 00:00:00,使用u_timeAgo()對上述三個發佈時間進行格式化：

<code>${u_timeAgo(date1)}
${u_timeAgo(date2)}
${u_timeAgo(date3)}/<code>

Output

<code>1年以前
1分鐘以前
剛剛/<code>

補充

除了使用u_timeAgo()函數對時間進行格式化外，你還可以選擇Freemarker自帶的格式化函數對時間進行格式化，例如對2020-04-05 06:11進行格式化：

Data

String date = "2020-04-05 06:11";

html

${date?string("yyyy年MM月dd日")}

Output

2020年04月05日

3.5 u_readTime()

u_readTime()是尤娜1.2.2版本中新增的一個趣味性函數，用於估算正常情況下閱讀文章完文章所需要的時間。u_readTime()函數接收一個字符串變量(文章內容),並以200字/分鐘的閱讀速度計算閱讀時間。下面是我個人網站的一個截圖：

u_readTime()函數

下面是u_readTime()函數的使用示例：

Data

<code>String content = "你假裝這裡有4512個字";/<code>

u_readTime()

<code>預計閱讀需要${u_readTime(content)}分鐘/<code>

Output

<code>預計閱讀需要22分鐘/<code>

4.腳本函數

在尤娜v1.2.2版本中，新增了兩個腳本函數u_gitalkScript()和u_gitalkSource()。u_gitalkScript()函數用於生成Gitalk的JavaScript初始化腳本，u_gitalkSource()函數用於生成Gitalk的樣式文件連接和JS腳本的鏈接地址。

4.1 u_gitalkSource()

u_gitalkSource()函數接收一個String類型參數，該參數的可選值有"css"和"js"（u_gitalkSource()函數會忽略大小寫）。下面是使用示例：

html

<code>
    
        <link>
    
    
        ...
        
    
/<code>

Output

<code>
    
        <link>
    
    
        ...
        
    
/<code>

4.2 u_gitalkScript()

u_gitalkScript()函數接收兩個參數，文章ID和評論區的DOM屬性(可以是div的id或class屬性值)。使用此函數後，會生成一段Gitalk評論插件的初始化腳本(使用該函數的前提是在尤娜系統後臺配置了Gitalk插件的相關信息)。下面是u_gitalkScript()使用示例：

Data

<code>Integer postId = 1101;/<code>

u_gitalkScript()

<code>
    
        <link>
    
    
        

               
            

​/<code>

Output

<code>
    
        <link>
    
    
        

               
            
/<code>

下圖是u_gitalkScript()使用的實際效果圖：

gitalk插件使用效果

本小節介紹了尤娜V1.2.2版本中的主題渲染標籤，包括二次擴展，全局常量，格式化函數和腳本函數，並給出了相應的示例代碼。在第二部分中，將詳細講解尤娜主題渲染標籤中的分頁函數和內容標籤。

尤娜博客系統V1.2.2版本

閱讀更多 ramostear 的文章

關鍵字: 跳槽那些事兒 主題 腳本語言