· 7 years ago · Jun 23, 2018, 10:06 PM
1Templater jQuery-plugin help:
2
3*************************************************
4** Additional JavaScript Functions **************
5*************************************************
6
7(These are all instance functions!)
8
9String functions:
10
11 contains(str) - Tests whether the String contains the substring given.
12 replaceAll(regex, str) - Replaces all occurences of the given RegExp
13 with the string given.
14 startsWith(str) - Determines if the String starts with the substring given.
15 endsWith(str) - Determines if the String ends with the given substring.
16 empty() - Determines if the String has no characters or contains nothing
17 but whitespace.
18
19Array functions:
20
21 last() - Returns the last element in the array.
22 first() - Returns the first element in the array.
23 empty() - Determines if the Array is empty or if it contains any data.
24 end() - Returns the last index in the Array.
25 remove(from, to) - From John Resig (MIT License) - Removes the given element
26 from the array if only one index is passed. Removes all elements between
27 the two indexes if from and to are given.
28
29RegExp functions:
30
31 getAllMatches(str) - Returns an array containing all matches of this RegExp in
32 the given String.
33
34*************************************************
35** General Information **************************
36*************************************************
37
38A Templater template is a JavaScript object with three properties, one of
39which is an optional property:
40
41 Name (REQUIRED): The name of the template, used to access the template.
42 Body (REQUIRED): The body of the template, a template is useless without
43 a body.
44 Defaults (OPTIONAL): A JavaScript map containing default values for any
45 properties that are contained within the template. This is optional
46 and can be specified when applying a template. This map does not
47 need to contain all properties that are specified within the
48 body of the template either, just those with default values.
49
50The jQuery plugin introduces two new functions, one of the jQuery object itself
51called 'template' (easy, right?) the other is used on a jQuery object.
52
53Use the $.template function to add and remove templates from the jQuery templater.
54To add, pass the string 'add' along with the template, to remove, pass the string
55'remove' along with the name of the template, if you wish to get a template you've
56created pass 'get' and if you want to replace one you've already stored you can
57use 'replace'.
58
59 Add:
60
61 $.template('add', {
62 name: 'templateName',
63 body: 'templateBody',
64 defaults: {
65 theseAre: 'optional'
66 }
67 });
68
69 Remove (the above template):
70
71 $.template('remove', 'templateName');
72
73 Grab a template that you have created:
74
75 $.template('get', 'templateName');
76
77 Replace a template with a new one:
78
79 $.template('replace', {
80 name: 'templateName',
81 body: 'newTemplateBody',
82 defaults: {
83 theseAre: 'stillOptional'
84 }
85 });
86
87As well as the function for jQuery objects, this function takes the name of a
88template (or a template object), an array or a single object from which the
89template is to be generated, and finally, and optional defaults object
90if you want to change template defaults just this once, or if no defaults
91were given.
92
93 $('div').first().template('templateName', objects, defaults);
94
95*************************************************
96** General Usage ********************************
97*************************************************
98
99Apply a template:
100
101 Assume an HTML stucture like so:
102 <html>
103 ...
104 <div id="content">
105 Content will go here.
106 </div>
107 ...
108 </html>
109
110 Assume a template definition like so:
111
112 $.template('add', {
113 name: 'postBox',
114 body: '<div id="post">'
115 + '<div id="post-title">${title}</div>'
116 + '<div id="post-content">${content}</div>'
117 + '<button id="view-button" data-postid="${postId}">Like</button>'
118 + '</div>'
119 defaults: {
120 title: 'Untitled'
121 }
122 });
123
124 And assume you recieve and AJAX response in JSON like:
125 {
126 success: true,
127 posts: [
128 { "postId": 1, "title": "A Title", "content": "Some content" },
129 ...
130 ]
131 }
132
133 From within the AJAX success function you can easily toss the array of
134 posts (through a template) into the content div like so:
135 ...
136 success: function(json) {
137 if (json.success)
138 $('#content').template('postBox', json.posts);
139 },
140 ...
141
142 Will generate HTML for each post in json.posts and append them to each
143 the template is called on. HTML output from this example would look like:
144
145 <div id="post">
146 <div id="post-title">A Title</div>
147 <div id="post-content">Some Content</div>
148 <button id="view-button" data-postid="1">View</button>
149 </div>
150 ...
151
152 And you're done!
153
154*************************************************
155** Special Statements ***************************
156*************************************************
157
158To access properties of the current object the array is being built for, you can
159specify the property name in ${} notation like so:
160
161 object = { property: 'value' };
162
163If you wanted the value of 'property' to be displayed in the tempalate you would
164type:
165
166 ${property}
167
168This will be replaced with the value of the property if it exists (if it does not
169exist, the engine will attempt to look for it in the defaults object) If it does
170not exist then it will be replaced by an empty string ("").
171
172If you need to perform calculations, call methods, then used the script notation
173${$} (which is similar to the property notation except for the $ inside the curly
174brackets). When using script notation, the current object can be reference as
175'cur'. If you needed to add 5 to every dollar ammount on an object you could
176simply do:
177
178 ${$cur.amount + 5}
179
180This would be replaced with the result of the expression given.
181
182CONDITIONAL OPERATIONS:
183
184There are two conditional operators that determine if the object is not the last
185in the list, or if it's not the first.
186
187 {{+printvalue}}
188
189will only display 'printvalue' if there objects remaining to be processed (meaning
190the current object is not the last in the list). It's opposite:
191
192 {{-printvalue}}
193
194will only display 'printvalue' if there are no objects remaining in the list
195(meaning the current object is last in the list).
196
197NOTE: object properties cannot be placed inside these two condition operators,
198if that is necessary let me know know and I can change it.
199
200Conditiona branching can be done with {{if}}, {{else}}, and {{/if}}.
201
202Branches may not be nested, and conditions cannot be grouped (if this is
203necessary behaviour, let me know). You can build a standard conditional
204branch easily, like:
205
206 {{if condition}}
207
208 [[{{else conditon}}]
209
210 [{{else}}]]
211
212 {{/if}}
213
214(Ignore the braces ([ ]) they are there to demonstrate optional conditionals)
215
216Be aware that the condition does not have any parenthesis around it (and should
217not contain any). Conditions can be simple (a > b) or complex (a > b and b > c),
218and notice the only difference between an 'else if' structure is {{else condition}}
219and {{else}}.
220
221 TCO = Templater Conditional Operaters
222 TCO Programming Equivalent
223 ------------------------------------
224 is ===
225 isnt !==
226 > >
227 >= >=
228 < <
229 <= <=
230 and &&
231 or ||
232 not !
233 ? (((none)))
234
235 (The '?' operater, which should directly follow the property that it's
236 testing, will test for the existence of that property on the current
237 object. Also, if the condition is just a property name, this calculation
238 will be performed automatically (meaning {{if name?}} and {{if name}}
239 are equivalent statements).)
240
241Any word in the condition, that is not listed as a string literal, will be considered an object
242property of the current object (no need for 'cur.' as with scripts or ${} as
243with inline property insertion). Strings are delineated by '=' (So: 'JavaScript' would be:
244=JavaScript=) If the condition evaluates to true (or defaults to an {{else}}) then the value
245specified there will be treated as a standard inline value (meaning ${property}, ${$script},
246{{+text}}, {{-text}}, or text).
247
248NOTE: Conditionals CANNOT be embedded within each other - if this feature is needed, please
249let me know.
250
251And Example:
252
253 {{if routing is 0}}
254 Nonstop
255 {{else routing is 1}}
256 1 Stop
257 {{else}}
258 ${routing} Stops
259 {{/if}}