GRMustache的使用（HTML模板渲染工具）For iOS

GRMustache是一個相似templateEngine的html渲染工具，能夠更加有效的幫助你們完成數據生成HTML的過程。
直達地址：https://github.com/groue/GRMustache
不管是GRMustache，仍是templateEngine。他們都幫助你們避免了使用
 -[NSString stringByReplacingOccurrencesOfString:withString:]:
方法時，繁瑣且頻繁低效的字符串操做。能夠更加優雅高效的生成HTML文件。

本篇博客源地址：http://386502324.blog.163.com/blog/static/113469377201555103951794/
因爲博客後期可能還會修改，轉載的內容可能不全或有錯誤，請瀏覽博客源地址。

一：導入方法
該類庫支持cocospod導入管理。省去了繁瑣的靜態庫導入以及後期的更新維護。

二：使用方法
在這裏就直接拷貝官方的使用示例了。

// 輸出 "Hello Arthur!"
NSString *rendering = [GRMustacheTemplate renderObject:@{ @"name": @"Arthur" } fromString:@"Hello {{name}}!" error:NULL];
// 從bundle文件中讀取輸出字符串
NSString *rendering = [GRMustacheTemplate renderObject:user fromResource:@"Profile" bundle:nil error:NULL];
重用templates，避免一個一樣的templates被屢次解析
GRMustacheTemplate *template = [GRMustacheTemplate templateFromResource:@"Profile" bundle:nil error:nil];
rendering = [template renderObject:arthur error:NULL];
rendering = [template renderObject:barbara error:NULL];
rendering = ...

三：注意點

二是官方提供的小示例，在此還想說的是
直達連接：http://mustache.github.io/mustache.5.html
一些特殊狀況的定義。
文檔已經說的很是清楚，再次就再也不贅述。
簡單描述下，有些特殊的狀況：好比使用{{{ }}}
有時候接口返回的數據中含有<p></p>等標籤，若是使用{{ }}完成替換，可能會致使這些特殊的字符被轉義，也就是致使格式丟失。
這篇文檔就是用來處理這些特殊狀況的。
若是須要，還請自行閱讀該文檔。

四：類的實現

瞭解下幾個主要的類。從而明白這個類庫的原理。

1：GRMustache
使用該類庫須要手動引入頭文件的類。
The GRMustache class provides with global-level information and configuration of the GRMustache library.
GRMustache類提供了通用的信息和庫的配置。（也就是方便你們引入其餘類）。

2：GRMustacheTemplate（模板）
GRMustacheTemplate是該類庫使用的最基本的類。咱們在使用類庫時，都須要該類的實例或者他的類方法。就想操做系統的窗口，讓咱們更簡單的使用這個類，提供了該類最基本的功能接口。
初始化方法比較簡單，這裏就再也不贅述。
本博客的第二塊內容【使用方法】中，有該類的最基礎方法

3：GRMustacheConfiguration構造配置器（解析規則）
配置器的做用是設置tagStartDelimiter（左標籤）和_tagEndDelimiter（右標籤），GRMustacheContentType，以及GRMustacheContext，以便讓解析器使用。

1：經過查看API文檔，咱們能夠得知，配置器有三種級別

①：Globally  全局的惟一配置器
 [GRMustacheConfiguration defaultConfiguration]

②：For all templates of a template repository 針對一個模板庫的配置器
GRMustacheTemplateRepository *repo = [GRMustacheTemplateRepository templateRepositoryWithDirectory:@"/path/to/templates"];

// Have all templates in /path/to/templates render HTML
repo.configuration.contentType = GRMustacheContentTypeHTML;

// Load the HTML template `profile.mustache`:
GRMustacheTemplate *template = [repo templateNamed:@"profile" error:NULL];

③：For a single template.做者沒有給實例。。暫時先空着。。

 

 2：三個屬性（property）

①： baseContext  
Mustache的渲染是根據從上下文的堆棧中獲取到的值進行的。上下文的堆棧使用base context完成初始化，經過你提供給template的objects擴展生成Mustache sections，並按照他的位置進行渲染。

默認的configuration包含默認的basecontext。已經預先配置在了GRMustache的標準庫中。
標準庫已經預約義了一些值，例如localize（本地化）和uppercase（大寫）
例如, 下面的 template:
{{# localize }}Hello {{ uppercase(name) }}!{{/ localize }}
會被渲染爲:
Bonjour ARTHUR !（法語：您好，亞瑟）hello被轉義爲做者國家的文字，也就是法語。

Provided with a name and a localization for "Hello %@!" string in the Localizable.strings file of the main bundle.
你能夠擴展 the base context:
// 全部的模板:
[[GRMustache defaultConfiguration] extendBaseContextWithObject:myCustomLibrary]

// 某個template repository下的模板:
GRMustacheTemplateRepository *repo = [GRMustacheTemplateRepository templateRepositoryWith...];
[repo.configuration extendBaseContextWithObject:myCustomLibrary]
你也能夠重設, 從而再也不使用標準庫中的上下文

[GRMustache defaultConfiguration].baseContext = [GRMustacheContext context];
repo.configuration.baseContext = [GRMustacheContext context];
你也能夠關注 priority keys（優先鍵值）。他們將始終被渲染成一樣的值（不能被改變或覆蓋）
// 保證{{my_important_value}}的渲染結果始終一致，而且不能被其餘自定義數據（庫）覆蓋:
id library = @{ @"my_important_value": ... };
[repo.configuration extendBaseContextWithProtectedObject:library];
See the GRMustacheContext Class Reference for a full documentation of the GRMustacheContext class.（連接可點）
base context也能夠在template的層級上被定義（譯者注：相對上面都是經過構造器實例定義而言）
GRMustacheTemplate *template = [GRMustacheTemplate templateFrom...];
[template extendBaseContextWith...];    // base context 的擴展
template.baseContext = ...;             // base context 的替換

②：contentType（內容類型）
默認的配置器使用了GRMustacheContentTypeHTML的內容類型，意味着全部的模板都會默認被渲染成HTML，輸入值會被轉碼。
GRMustache也支持文本模板，渲染文本不會被轉碼（轉義）。
This subject is fully covered in the HTML vs. Text Templates Guide.
③：tagStartDelimiter and tagEndDelimiter（左標籤和右標籤）
你能夠經過如下兩種方法層級進行標籤的替換。
// 全部模板使用 <% 和 %> 做爲替換標籤:
[GRMustacheConfiguration defaultConfiguration].tagStartDelimiter = @"<%";
[GRMustacheConfiguration defaultConfiguration].tagEndDelimiter = @"%>";

// 只是某個template repository使用自定義的起始標籤:
GRMustacheTemplateRepository *repo = [GRMustacheTemplateRepository templateRepositoryWith...];
repo.configuration.tagStartDelimiter = @"[[";
repo.configuration.tagEndDelimiter = @"]]";
另外，標籤也能夠在單個模板級別上進行設置"Set Delimiters Tag" 好比 {{=<% %>=}}:標籤會變爲<% name %>

4：GRMustacheTemplateRepository（模板庫）
一個GRMustacheTemplateRepository實例含有一系列的模板和修飾符，能夠經過嵌入符相互嵌入，如{{>name}}。
這個類能夠幫助你處理那些mustacheTemplate沒法直接實現的其餘高級方法的狀況：

①：當[GRMustacheTemplate templateFrom...] 不符合你的須要( Templates Guide).
例如, 你的模板沒有存儲在文件中, 或者他沒有被編碼成UTF8的格式.
②：當你的模板被儲存在多層級的路徑下，可是你先想要直接使用它的直接經過修飾符partials.
{{> header }} loads a header partial template stored next to its enclosing template, but {{> /partials/header }}, with a leading slash, loads a template located at the absolute path /partials/header from the root of the template repository.
③：當你想要一組模板配置特定的 configuration。例如你想讓其中一些模板渲染成文本，而讓另外一些模板渲染成HTML

5：GRMustacheTemplateParser（解析器）

GRMustacheTemplateParser接收一個Mustache template的字符串，並生成tokens。解析器的代理compiler類會去接收這些生成的tokens，生成語法結構樹並去生成一個templateAST。
（順便吐槽一句，這個類庫的做者是法國人，把法國人的英語再翻譯成漢語真是好痛苦。。）

接下來看一下他的初始化方法：- (instancetype)initWithConfiguration:(GRMustacheConfiguration *)configuration;
解析器是根據一個GRMustacheConfiguration的實例生成的。也就是說，設置好GRMustacheConfiguration（也就是解析的規則），解析器將按照此配置進行解析。

6：GRMustacheCompiler（編譯器）
GRMustacheCompiler 做爲代理接收GRMustacheTemplateParser 生成的GRMustacheTokens,生成一個遵循 GRMustacheTemplateASTNode protoco 的syntax tree類templateAST .

7：GRMustacheTemplateAST（語法樹）
The GRMustacheTemplateAST represents the abstract syntax tree of a template.
GRMustacheTemplateAST呈現出模板的抽象語法樹。

8：GRMustacheCompiler（編譯器）
engine利用templateAST和context最終生成字符串。而且傳出。

五：綜述該類庫的工做原理：

①：GRMustacheTemplateRepository建立template實例。
②：template實例建立templateParser（解析模板生成token傳出）以及compiler（接收token並生成語法樹）。
parser和compiler生成templateAST。
③：template實例經過GRMustacheTemplateRepository 的basecontext以及用戶傳入的object生成context。④：template實例建立renderingEngine實例engine。engine利用templateAST和context最終生成字符串。而且傳出。固然，在解析的過程當中還涉及到不少類。在這裏就不一一說起了。六：聲明因爲本人水平有限，本博客可能有不許確或者錯誤的地方，還請你們海涵並指正