@@ -26,7 +26,144 @@ Or install it yourself as:
2626
2727## Usage
2828
29- TODO: Write usage instructions here
29+ ### Quick Start
30+
31+ ``` ruby
32+ handlebars = Handlebars ::Engine .new
33+ template = handlebars.compile(" {{firstname}} {{lastname}}"
34+ template.call({ firstname: " Yehuda" lastname: " Katz"
35+ # => "Yehuda Katz"
36+ ```
37+
38+ ### Custom Helpers
39+
40+ Handlebars helpers can be accessed from any context in a template. You can
41+ register a helper with the ` register_helper ` method:
42+
43+ ``` ruby
44+ handlebars = Handlebars ::Engine .new
45+ handlebars.register_helper(:loud ) do |ctx , arg , opts |
46+ arg.upcase
47+ end
48+ template = handlebars.compile(" {{firstname}} {{loud lastname}}"
49+ template.call({ firstname: " Yehuda" lastname: " Katz"
50+ # => "Yehuda KATZ"
51+ ```
52+
53+ #### Helper Arguments
54+
55+ Helpers receive the current context as the first argument of the block.
56+
57+ ``` ruby
58+ handlebars = Handlebars ::Engine .new
59+ handlebars.register_helper(:full_name ) do |ctx , opts |
60+ " #{ ctx[" firstname" } #{ ctx[" lastname" } "
61+ end
62+ template = handlebars.compile(" {{full_name}}"
63+ template.call({ firstname: " Yehuda" lastname: " Katz"
64+ # => "Yehuda Katz"
65+ ```
66+
67+ Any arguments to the helper are included as individual positional arguments.
68+
69+ ``` ruby
70+ handlebars = Handlebars ::Engine .new
71+ handlebars.register_helper(:join ) do |ctx , * args , opts |
72+ args.join(" "
73+ end
74+ template = handlebars.compile(" {{join firstname lastname}}"
75+ template.call({ firstname: " Yehuda" lastname: " Katz"
76+ # => "Yehuda Katz"
77+ ```
78+
79+ The last argument is a hash of options.
80+
81+ See https://handlebarsjs.com/guide/#custom-helpers .
82+
83+ ### Block Helpers
84+
85+ See https://handlebarsjs.com/guide/#block-helpers .
86+
87+ ### Partials
88+
89+ Handlebars partials allow for code reuse by creating shared templates.
90+
91+ You can register a partial using the ` register_partial ` method:
92+
93+ ``` ruby
94+ handlebars = Handlebars ::Engine .new
95+ handlebars.register_partial(:person , " {{person.name}} is {{person.age}}."
96+ template = handlebars.compile(" {{> person person=.}}"
97+ template.call({ name: " Yehuda Katz" age: 20 })
98+ # => "Yehuda Katz is 20."
99+ ```
100+
101+ See https://handlebarsjs.com/guide/#partials .
102+ See https://handlebarsjs.com/guide/partials.html .
103+
104+ ### Hooks
105+
106+ #### Helper Missing
107+
108+ This hook is called for a mustache or a block-statement when
109+ * a simple mustache-expression is not a registered helper, * and*
110+ * it is not a property of the current evaluation context.
111+
112+ You can add custom handling for those situations by registering a helper with
113+ the ` register_helper_missing ` method:
114+
115+ ``` ruby
116+ handlebars = Handlebars ::Engine .new
117+ handlebars.register_helper_missing do |ctx , * args , opts |
118+ " Missing: #{ opts[" name" } (#{ args.join(" , " } )"
119+ end
120+
121+ template = handlebars.compile(" {{foo 2 true}}"
122+ template.call
123+ # => "Missing: foo(2, true)"
124+
125+ template = handlebars.compile(" {{#foo true}}{{/foo}}"
126+ template.call
127+ # => "Missing: foo(true)"
128+ ```
129+
130+ See https://handlebarsjs.com/guide/hooks.html#helpermissing .
131+
132+ ##### Blocks
133+
134+ This hook is called for a block-statement when
135+ * a block-expression calls a helper that is not registered, * and*
136+ * the name is a property of the current evaluation context.
137+
138+ You can add custom handling for those situations by registering a helper with
139+ the ` register_helper_missing ` method (with a ` :block ` argument):
140+
141+ ``` ruby
142+ handlebars = Handlebars ::Engine .new
143+ handlebars.register_helper_missing(:block ) do |ctx , * args , opts |
144+ " Missing: #{ opts[" name" } (#{ args.join(" , " } )"
145+ end
146+
147+ template = handlebars.compile(" {{#person}}{{name}}{{/person}}"
148+ template.call({ person: { name: " Yehuda Katz"
149+ # => "Missing: person"
150+ ```
151+
152+ See https://handlebarsjs.com/guide/hooks.html#blockhelpermissing .
153+
154+ #### Partial Missing
155+
156+ This hook is called for a partial that is not registered.
157+
158+ ``` ruby
159+ handlebars = Handlebars ::Engine .new
160+ handlebars.register_partial_missing do |name |
161+ " partial: #{ name } "
162+ end
163+ ```
164+
165+ Note: This is not a part of the offical Handlebars API. It is provided for
166+ convenience.
30167
31168## Changelog
32169
0 commit comments