Skip to content
This repository
Browse code

Add reference for template documentation

  • Loading branch information...
commit 678232f533d8f9016ce106b78183db7fdec57b4d 1 parent 57ad36e
Will Rossiter authored August 30, 2012

Showing 1 changed file with 156 additions and 56 deletions. Show diff stats Hide diff stats

  1. 212  docs/en/reference/templates.md
212  docs/en/reference/templates.md
Source Rendered
@@ -124,82 +124,99 @@ See [CSS](/topics/css) and [Javascript](/topics/javascript) topics for individua
124 124
 
125 125
 ## Conditional Logic
126 126
 
127  
-You can conditionally include markup in the output. That is, test for something that is true or false, and based on that test, control what gets output.
  127
+You can conditionally include markup in the output. That is, test for something 
  128
+that is true or false, and based on that test, control what gets output.
128 129
 
129 130
 The simplest if block is to check for the presence of a value.
130 131
 
131 132
 	:::ss
132  
-  <% if $CurrentMember %>
133  
-      <p>You are logged in as $CurrentMember.FirstName $CurrentMember.Surname.</p>
134  
-  <% end_if %>
  133
+	<% if $CurrentMember %>
  134
+		<p>You are logged in as $CurrentMember.FirstName $CurrentMember.Surname.</p>
  135
+	<% end_if %>
135 136
 
136  
-The following compares a page property called `MyDinner` with the value in quotes, `kipper`, which is a **literal**. If true, the text inside the if-block is output.
  137
+The following compares a page property called `MyDinner` with the value in 
  138
+quotes, `kipper`, which is a **literal**. If true, the text inside the if-block 
  139
+is output.
137 140
 
138 141
 	:::ss
139  
-  <% if $MyDinner="kipper" %>
140  
-      Yummy, kipper for tea.
141  
-  <% end_if %>
  142
+	<% if $MyDinner="kipper" %>
  143
+		Yummy, kipper for tea.
  144
+	<% end_if %>
142 145
 
143  
-Note that inside a tag like this, variables should have a '$' prefix, and literals should have quotes.  SilverStripe 2.4 didn't include the quotes or $ prefix, and while this still works, we recommend the new syntax as it is less ambiguous.
  146
+Note that inside a tag like this, variables should have a '$' prefix, and 
  147
+literals should have quotes.  SilverStripe 2.4 didn't include the quotes or $ 
  148
+prefix, and while this still works, we recommend the new syntax as it is less 
  149
+ambiguous.
144 150
 
145  
-This example shows the use of the `else` option. The markup after `else` is output if the tested condition is *not* true.
  151
+This example shows the use of the `else` option. The markup after `else` is 
  152
+output if the tested condition is *not* true.
146 153
 
147 154
 	:::ss
148  
-  <% if $MyDinner="kipper" %>
149  
-      Yummy, kipper for tea
150  
-  <% else %>
151  
-      I wish I could have kipper :-(
152  
-  <% end_if %>
  155
+	<% if $MyDinner="kipper" %>
  156
+		Yummy, kipper for tea
  157
+	<% else %>
  158
+		I wish I could have kipper :-(
  159
+	<% end_if %>
153 160
 
154  
-This example shows the user of `else\_if`. There can be any number of `else\_if` clauses. The conditions are tested from first to last, until one of them is true, and the markup for that condition is used. If none of the conditions are true, the markup in the `else` clause is used, if that clause is present.
  161
+This example shows the user of `else_if`. There can be any number of `else_if` 
  162
+clauses. The conditions are tested from first to last, until one of them is true, 
  163
+and the markup for that condition is used. If none of the conditions are true, 
  164
+the markup in the `else` clause is used, if that clause is present.
155 165
 
156 166
 	:::ss
157  
-  <% if $MyDinner="quiche" %>
158  
-      Real men don't eat quiche
159  
-  <% else_if $MyDinner=$YourDinner %>
160  
-      We both have good taste
161  
-  <% else %>
162  
-      Can I have some of your chips?
163  
-  <% end_if %>
  167
+	<% if $MyDinner="quiche" %>
  168
+		Real men don't eat quiche
  169
+	<% else_if $MyDinner=$YourDinner %>
  170
+		We both have good taste
  171
+	<% else %>
  172
+		Can I have some of your chips?
  173
+	<% end_if %>
164 174
 
165 175
 This example shows the use of `not` to negate the test.
166 176
 
167 177
 	:::ss
168  
-  <% if not $DinnerInOven %>
169  
-      I'm going out for dinner tonight.
170  
-  <% end_if %>
  178
+	<% if not $DinnerInOven %>
  179
+		I'm going out for dinner tonight.
  180
+	<% end_if %>
171 181
 
172  
-You can combine two or more conditions with `||` ("or"). The markup is used if *either* of the conditions is true.
  182
+You can combine two or more conditions with `||` ("or"). The markup is used if 
  183
+*either* of the conditions is true.
173 184
 
174 185
 	:::ss
175  
-  <% if $MyDinner=="kipper" || $MyDinner=="salmon" %>
176  
-      yummy, fish for tea
177  
-  <% end_if %>
  186
+	<% if $MyDinner=="kipper" || $MyDinner=="salmon" %>
  187
+		yummy, fish for tea
  188
+	<% end_if %>
178 189
 
179  
-You can combine two or more conditions with `&&` ("and"). The markup is used if *both* of the conditions are true.
  190
+You can combine two or more conditions with `&&` ("and"). The markup is used if 
  191
+*both* of the conditions are true.
180 192
 
181 193
 	:::ss
182  
-  <% if $MyDinner=="quiche" && $YourDinner=="kipper" %>
183  
-      Lets swap dinners
184  
-  <% end_if %>
  194
+	<% if $MyDinner=="quiche" && $YourDinner=="kipper" %>
  195
+		Lets swap dinners
  196
+	<% end_if %>
185 197
 
186 198
 ## Looping Over Lists
187 199
 
188  
-The `<% loop %>...<% end_loop %>` tag is used to **iterate** or loop over a collection of items. For example:
  200
+The `<% loop %>...<% end_loop %>` tag is used to **iterate** or loop over a 
  201
+collection of items. For example:
189 202
 
190 203
 	:::ss
191 204
 	<ul>
192  
-	<% loop $Children %>
193  
-	  <li>$Title</li>
194  
-	<% end_loop %>
  205
+		<% loop $Children %>
  206
+			<li>$Title</li>
  207
+		<% end_loop %>
195 208
 	</ul>
196 209
 
197  
-This loops over the children of a page, and generates an unordered list showing the `Title` property from each one. Note that `$Title` *inside* the loop refers to the `Title` property on each object that is looped over, not the current page. To refer to the current page's `Title` property inside the loop, you can do `$Up.Title`. More about `Up` later.
  210
+This loops over the children of a page, and generates an unordered list showing 
  211
+the `Title` property from each one. Note that `$Title` *inside* the loop refers 
  212
+to the `Title` property on each object that is looped over, not the current page. 
  213
+To refer to the current page's `Title` property inside the loop, you can do 
  214
+`$Up.Title`. More about `Up` later.
198 215
 
199 216
 ### Position Indicators
200 217
 
201  
-Inside the loop scope, there are many variables at your disposal to determine the current position
202  
-in the list and iteration:
  218
+Inside the loop scope, there are many variables at your disposal to determine the 
  219
+current position in the list and iteration:
203 220
 
204 221
  * `$Even`, `$Odd`: Returns boolean, handy for zebra striping
205 222
  * `$EvenOdd`: Returns a string, either 'even' or 'odd'. Useful for CSS classes.
@@ -216,7 +233,9 @@ $Modulus and $MultipleOf can help to build column layouts.
216 233
 	$Modulus(value, offset) // returns an int
217 234
 	$MultipleOf(factor, offset) // returns a boolean.
218 235
 
219  
-The following example demonstrates how you can use $Modulus(4) to generate custom column names based on your loop statement. Note that this works for any control statement (not just children)
  236
+The following example demonstrates how you can use $Modulus(4) to generate 
  237
+custom column names based on your loop statement. Note that this works for any 
  238
+control statement (not just children).
220 239
 
221 240
 	:::ss
222 241
 	<% loop Children %>
@@ -225,9 +244,11 @@ The following example demonstrates how you can use $Modulus(4) to generate custo
225 244
 	</div>
226 245
 	<% end_loop %>
227 246
 
228  
-Will return you column-3, column-2, column-1, column-0, column-3 etc. You can use these as styling hooks to float, position as you need.
  247
+Will return you column-3, column-2, column-1, column-0, column-3 etc. You can 
  248
+use these as styling hooks to float, position as you need.
229 249
 
230  
-You can also use $MultipleOf(value, offset) to help build columned layouts. In this case we want to add a <br> after every 3th item
  250
+You can also use $MultipleOf(value, offset) to help build columned layouts. In 
  251
+this case we want to add a <br> after every 3th item.
231 252
 
232 253
 	:::ss
233 254
 	<% loop Children %>
@@ -238,31 +259,110 @@ You can also use $MultipleOf(value, offset) to help build columned layouts. In t
238 259
 
239 260
 ## Scope
240 261
 
241  
-In the `<% loop %>` section, we saw an example of two **scopes**. Outside the `<% loop %>...<% end_loop %>`, we were in the scope of the page. But inside the loop, we were in the scope of an item in the list. The scope determines where the value comes from when you refer to a variable. Typically the outer scope of a page type's layout template is the page that is currently being rendered. The outer scope of an included template is the scope that it was included into.
  262
+In the `<% loop %>` section, we saw an example of two **scopes**. Outside the 
  263
+`<% loop %>...<% end_loop %>`, we were in the scope of the page. But inside the 
  264
+loop, we were in the scope of an item in the list. The scope determines where 
  265
+the value comes from when you refer to a variable. Typically the outer scope of 
  266
+a page type's layout template is the page that is currently being rendered. 
  267
+The outer scope of an included template is the scope that it was included into.
  268
+
  269
+### Up
  270
+
  271
+When we are in a scope, we sometimes want to refer to the scope outside the 
  272
+<% loop %> or <% with %>. We can do that easily by using `$Up`. `$Up` takes 
  273
+the scope back to the previous level. Take the following example:
  274
+
  275
+	:::ss
  276
+	$Title
  277
+	--
  278
+	<% loop Children %>
  279
+		$Title
  280
+		$Up.Title
  281
+		--
  282
+		<% loop Children %>
  283
+			$Title
  284
+			$Up.Title
  285
+		<% end_loop %>
  286
+	<% end_loop %>
  287
+
  288
+With a page structure (Blog -> Blog entry -> Child blog entry) the 
  289
+above will produce:
242 290
 
243  
-When we are in a scope, we sometimes want to refer to the scope outside the <% loop %> or <% with %>. We can do that easily by using `$Up`.
  291
+	:::sss
  292
+	Blog
  293
+	--
  294
+	Blog entry
  295
+	Blog
  296
+	--
  297
+	Child blog entry
  298
+	Blog entry
  299
+
  300
+
  301
+### Top
  302
+
  303
+While `$Up` provides us a way to go up 1 scope, `$Top` is a shortcut to jump to 
  304
+the top most scope of the page. Using the previous example but expanded to 
  305
+include `$Top`:
  306
+
  307
+	:::ss
  308
+	$Title
  309
+	--
  310
+	<% loop Children %>
  311
+		$Title
  312
+		$Up.Title
  313
+		$Top.Title
  314
+		--
  315
+		<% loop Children %>
  316
+			$Title
  317
+			$Up.Title
  318
+			$Top.Title
  319
+		<% end_loop %>
  320
+	<% end_loop %>
  321
+
  322
+Will produce
  323
+
  324
+	:::ss
  325
+	Blog
  326
+	--
  327
+	Blog entry
  328
+	Blog
  329
+	Blog
  330
+	--
  331
+	Child blog entry
  332
+	Blog entry	
  333
+	Blog
244 334
 
245 335
 ### With
246 336
 
247  
-The `<% with %>...<% end_with %>` tag lets you introduce a new scope. Consider the following example:
  337
+The `<% with %>...<% end_with %>` tag lets you introduce a new scope. Consider 
  338
+the following example:
  339
+
  340
+	:::ss
  341
+	<% with $CurrentMember %>
  342
+		Hello $FirstName, welcome back. Your current balance is $Balance.
  343
+	<% end_with %>
248 344
 
249  
-    <% with $CurrentMember %>
250  
-        Hello $FirstName, welcome back. Your current balance is $Balance.
251  
-    <% end_with %>
252 345
 
253  
-Outside the `<% with %>...<% end_with %>`, we are in the page scope. Inside it, we are in the scope of `$CurrentMember`. We can refer directly to properties and methods of that member. So $FirstName is equivalent to $CurrentMember.FirstName. This keeps the markup clean, and if the scope is a complicated expression we don't have to repeat it on each reference of a property.
  346
+Outside the `<% with %>...<% end_with %>`, we are in the page scope. Inside it, 
  347
+we are in the scope of `$CurrentMember`. We can refer directly to properties and 
  348
+methods of that member. So $FirstName is equivalent to $CurrentMember.FirstName. 
  349
+This keeps the markup clean, and if the scope is a complicated expression we don't 
  350
+have to repeat it on each reference of a property.
254 351
 
255  
-`<% with %>` also lets us use a collection as a scope, so we can access properties of the collection itself, instead of iterating over it. For example:
  352
+`<% with %>` also lets us use a collection as a scope, so we can access 
  353
+properties of the collection itself, instead of iterating over it. For example:
256 354
 
257  
-    $Children.Length
  355
+	:::ss
  356
+	$Children.Length
258 357
 
259 358
 returns the number of items in the $Children collection.
260 359
 
261 360
 ## Pagination
262 361
 
263  
-Lists can be paginated, and looped over page-by-page.
264  
-For this to work, the list needs to be wrapped in a `[api:PaginatedList]`.
265  
-The process is explained in detail on the ["pagination" howto](/howto/pagination).
  362
+Lists can be paginated, and looped over to generate pagination. For this to 
  363
+work,  the list needs to be wrapped in a `[api:PaginatedList]`. The process is 
  364
+explained in detail on the ["pagination" howto](/howto/pagination).
  365
+
266 366
 The list is split up in multiple "pages", each . Note that "page" is this context
267 367
 does not necessarily refer to a `Page` class (although it often happens to be one).
268 368
 

0 notes on commit 678232f

Please sign in to comment.
Something went wrong with that request. Please try again.