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最终生成字符串。并且传出。
当然,在解析的过程中还涉及到很多类。在这里就不一一提及了。
六:声明
由于本人水平有限,本博客可能有不准确或者错误的地方,还请大家海涵并指正