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

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 = [GRMustacheTemplateRepositorytemplateRepositoryWithDirectory:@"/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最终生成字符串。并且传出。

当然，在解析的过程中还涉及到很多类。在这里就不一一提及了。

六：声明

由于本人水平有限，本博客可能有不准确或者错误的地方，还请大家海涵并指正。