Skip to content
This repository
Browse code

MINOR: Documentation, tutorial (part3, and tidy-up part 1&2 )

Fixed up Forms documentation, and replaced some images in first 2
tutorials
  • Loading branch information...
commit 2d80ea5939ecf9783dc3e19e12926393fb09ef63 1 parent 766b03f
Naomi Guyer authored July 02, 2012 chillu committed August 07, 2012
23  docs/en/tutorials/2-extending-a-basic-site.md
Source Rendered
@@ -135,9 +135,9 @@ To add our new fields to the CMS we have to override the *getCMSFields()* method
135 135
 		public function getCMSFields() {
136 136
 			$fields = parent::getCMSFields();
137 137
 			
138  
-			$datefield = new DateField('Date');
139  
-			$datefield->setConfig('showcalendar', true);
140  
-			$fields->addFieldToTab('Root.Main', $datefield, 'Content');
  138
+			$dateField = new DateField('Date');
  139
+			$dateField->setConfig('showcalendar', true);
  140
+			$fields->addFieldToTab('Root.Main', $dateField, 'Content');
141 141
 			$fields->addFieldToTab('Root.Main', new TextField('Author'), 'Content');
142 142
 			
143 143
 			return $fields;
@@ -202,18 +202,17 @@ the date field will have the date format defined by your locale.
202 202
 		$fields = parent::getCMSFields();
203 203
 		
204 204
 		$fields->addFieldToTab('Root.Main', $dateField = new DateField('Date','Article Date (for example: 20/12/2010)'), 'Content');
205  
-		$dateField->setConfig('showcalendar', true);
206  
-		$dateField->setConfig('dateformat', 'dd/MM/YYYY');
207  
-		
208  
-		$fields->addFieldToTab('Root.Main', new TextField('Author','Author Name'), 'Content');
209  
-		
  205
+        $dateField->setConfig('showcalendar', true);
  206
+        $fields->addFieldToTab('Root.Main', $dateField, 'Content');
  207
+        $fields->addFieldToTab('Root.Main', new TextField('Author'), 'Content');
  208
+
210 209
 		return $fields;
211 210
 	}
212 211
 
213 212
 Let's walk through these changes.
214 213
 
215 214
 	:::php
216  
-	$fields->addFieldToTab('Root.Content', $dateField = new DateField('Date','Article Date (for example: 20/12/2010)'), 'Content');
  215
+	$fields->addFieldToTab('Root.Main', $dateField = new DateField('Date','Article Date (for example: 20/12/2010)'), 'Content');
217 216
 
218 217
 *$dateField* is declared only to in order to change the configuration of the DateField.
219 218
 
@@ -228,7 +227,7 @@ By enabling *showCalendar* you show a calendar overlay when clicking on the fiel
228 227
 *dateFormat* allows you to specify how you wish the date to be entered and displayed in the CMS field.  See the `[api:DateField]` documentation for more configuration options.
229 228
 
230 229
 	:::php
231  
-	$fields->addFieldToTab('Root.Content', new TextField('Author','Author Name'), 'Content');
  230
+	$fields->addFieldToTab('Root.Main', new TextField('Author','Author Name'), 'Content');
232 231
 
233 232
 By default the field name *'Date'* or *'Author'* is shown as the title, however this might not be that helpful so to change the title, add the new title as the second argument.
234 233
 
@@ -309,7 +308,7 @@ We can make our templates more modular and easier to maintain by separating comm
309 308
 
310 309
 We'll separate the display of linked articles as we want to reuse this code later on.
311 310
 
312  
-Cut the code in *ArticleHolder.ss** and replace it with an include statement:
  311
+Cut the code between "loop Children" in *ArticleHolder.ss** and replace it with an include statement:
313 312
 
314 313
 **themes/simple/templates/Layout/ArticleHolder.ss**
315 314
 
@@ -371,7 +370,7 @@ This function simply runs a database query that gets the latest news articles fr
371 370
 
372 371
 	:::ss
373 372
 	...
374  
-	<div class="content">$Content</div>
  373
+		<div class="content">$Content</div>
375 374
 	</article>
376 375
 	<% loop LatestNews %>
377 376
 		<% include ArticleTeaser %>
184  docs/en/tutorials/3-forms.md
Source Rendered
@@ -2,30 +2,22 @@
2 2
 
3 3
 ## Overview
4 4
 
5  
-This tutorial is intended to be a continuation of the first two tutorials, and will build on the site produced in those
6  
-two tutorials.
  5
+This tutorial is intended to be a continuation of the first two tutorials ([first tutorial](1-building-a-basic-site), [second tutorial](2-extending-a-basic-site)). In this tutorial we will build on the site we developed in the earlier tutorials and explore forms in SilverStripe. We will look at custom coded forms: forms which need to be written in PHP.
7 6
 
8  
-This tutorial explores forms in SilverStripe. It will look at coded forms. Forms which need to be written in PHP.
9  
-
10  
-Another method which allows you to construct forms via the CMS is by using the [userforms module](http://silverstripe.org/user-forms-module). 
11  
-A UserDefinedForm is much quicker to implement, but lacks the flexibility of a coded form. 
  7
+Instead of using a custom coded form, we could use the [userforms module](http://silverstripe.org/user-forms-module). This module allows users to construct forms via the CMS. A UserDefinedForm is much quicker to implement, but lacks the flexibility of a coded form. 
12 8
 
13 9
 ## What are we working towards?
14 10
 
15  
-We will create a poll on the home page that asks the user their favourite web browser, and displays a bar graph of the
16  
-results.
  11
+We will create a poll on the home page that asks the user their favourite web browser, and displays a bar graph of the results.
17 12
 
18  
-![tutorial:pollresults-small.png](_images/pollresults-small.jpg)
  13
+![tutorial:tutorial3_pollresults.png](_images/tutorial3_pollresults.jpg)
19 14
 
20 15
 
21 16
 ## Creating the form
22 17
 
23  
-We will be creating a form for a poll on the home page.
24  
-
25  
-The poll will ask the user's name and favourite web browser, and then collate the results into a bar graph. We create
26  
-the form in a method on *HomePage_Controller*.
  18
+The poll we will be creating on our homepage will ask the user for their name and favourite web browser. It will then collate the results into a bar graph. We create the form in a method on *HomePage_Controller*.
27 19
 
28  
-*mysite/code/HomePage.php*
  20
+**mysite/code/HomePage.php**
29 21
 
30 22
 	:::php
31 23
 	class HomePage_Controller extends Page_Controller {
@@ -78,7 +70,7 @@ Let's step through this code.
78 70
 
79 71
 First we create our form fields.
80 72
 
81  
-We do this by creating a `[api:FieldList]` and passing our fields as arguments. The first field is a new
  73
+We do this by creating a `[api:FieldList]` and passing our fields as arguments. The first field is a  
82 74
 `[api:TextField]` with the name 'Name'.
83 75
 
84 76
 There is a second argument when creating a field which specifies the text on the label of the field. If no second
@@ -115,9 +107,9 @@ FieldLists containing the fields and form actions respectively.
115 107
 
116 108
 After creating the form function, we need to add the form to our home page template.
117 109
 
118  
-Add the following code to the home page template, just before the Content `<div>`:
  110
+Add the following code to the top of your home page template, just before the first Content `<div>`:
119 111
 
120  
-*themes/tutorial/templates/Layout/HomePage.ss*
  112
+**themes/tutorial/templates/Layout/HomePage.ss**
121 113
 
122 114
 	:::ss
123 115
 	...
@@ -125,12 +117,31 @@ Add the following code to the home page template, just before the Content `<div>
125 117
 		<h2>Browser Poll</h2>
126 118
 		$BrowserPollForm
127 119
 	</div>
128  
-	<div id="Content">
  120
+	<div class="Content">
129 121
 	...
130 122
 
  123
+your HomePage.ss file should now look like this:
  124
+	:::ss
  125
+	<div id="BrowserPoll">
  126
+		<h2>Browser Poll</h2>
  127
+		 $BrowserPollForm
  128
+	</div>
  129
+
  130
+	<div class="content-container typography">	
  131
+		<article>
  132
+			<div id="Banner">
  133
+	  			<img src="http://www.silverstripe.org/themes/silverstripe/images/sslogo.png" alt="Homepage image" />
  134
+			</div>
  135
+			
  136
+			<div class="content">$Content</div>
  137
+		</article>
  138
+		$Form
  139
+		$PageComments
  140
+	</div>	
  141
+
131 142
 Add the following code to the form style sheet:
132 143
 
133  
-*themes/tutorial/css/form.css*
  144
+**themes/tutorial/css/form.css**
134 145
 
135 146
 	:::css
136 147
 	/* BROWSER POLL */
@@ -142,21 +153,27 @@ Add the following code to the form style sheet:
142 153
 		form FieldList {
143 154
 			border:0;
144 155
 		}
145  
-		#BrowserPoll .message {
146  
-			display: block;
147  
-			color:red;
148  
-			background:#ddd;
149  
-			border:1px solid #ccc;
150  
-			padding:5px;
151  
-			margin:5px;
152  
-		}
  156
+   		#BrowserPoll .message {
  157
+            float:left;
  158
+            display: block;
  159
+            color:red;
  160
+            background:#efefef;
  161
+            border:1px solid #ccc;
  162
+            padding:5px;
  163
+            margin:5px;
  164
+        }
153 165
 		#BrowserPoll h2 {
154 166
 			font-size: 1.5em;
  167
+			line-height:2em;
155 168
 			color: #0083C8;
156 169
 		}
157 170
 		#BrowserPoll .field {
158 171
 			padding:3px 0;
159 172
 		}
  173
+		#BrowserPoll input.text {
  174
+			padding: 0;
  175
+			font-size:1em;
  176
+		}
160 177
 		#BrowserPoll .Actions {
161 178
 			padding:5px 0;
162 179
 		}
@@ -165,25 +182,20 @@ Add the following code to the form style sheet:
165 182
 		}
166 183
 
167 184
 
168  
-This CSS code will ensure that the form is formatted and positioned correctly. All going according to plan, if you visit
169  
-[http://localhost/home?flush=1](http://localhost/home?flush=1) it should look something like below.
  185
+This CSS code will ensure that the form is formatted and positioned correctly. All going according to plan, if you visit [http://localhost/your_site_name/home?flush=all](http://localhost/your_site_name/home?flush=all) it should look something like this:
170 186
 
171  
-![](_images/pollform.jpg)
  187
+![](_images/tutorial3_pollform.jpg)
172 188
 
173 189
 
174 190
 ## Processing the form
175 191
 
176  
-Great! We now have a browser poll form, but it doesn't actually do anything. In order to make the form work, we have to
177  
-implement the 'doBrowserPoll' method that we told it about.
  192
+Great! We now have a browser poll form, but it doesn't actually do anything. In order to make the form work, we have to implement the 'doBrowserPoll' method that we told it about.
178 193
 
179  
-First, we need some way of saving the poll submissions to the database, so we can retrieve the results later. We can do
180  
-this by creating a new object that extends from `[api:DataObject]`.
  194
+First, we need some way of saving the poll submissions to the database, so we can retrieve the results later. We can do this by creating a new object that extends from `[api:DataObject]`.
181 195
 
182  
-If you recall, in tutorial two we said that all objects that inherit from DataObject and that add fields are stored in
183  
-the database. Also recall that all pages extend DataObject indirectly through `[api:SiteTree]`. Here instead of
184  
-extending SiteTree (or `[api:Page]`) to create a page type, we extend DataObject directly.
  196
+If you recall, in the [second tutorial](2-extending-a-basic-site) we said that all objects that inherit from DataObject and have their own fields are stored in tables the database. Also recall that all pages extend DataObject indirectly through `[api:SiteTree]`. Here instead of extending SiteTree (or `[api:Page]`) to create a page type, we will extend DataObject directly:
185 197
 
186  
-*mysite/code/BrowserPollSubmission.php*
  198
+**mysite/code/BrowserPollSubmission.php**
187 199
 
188 200
 	:::php
189 201
 	<?php	
@@ -195,10 +207,9 @@ extending SiteTree (or `[api:Page]`) to create a page type, we extend DataObject
195 207
 	}
196 208
 
197 209
 
198  
-If we then rebuild the database ([http://localhost/dev/build?flush=1](http://localhost/dev/build?flush=1)), we will see
199  
-that the *BrowserPollSubmission* table is created. Now we just need to define 'doBrowserPoll' on *HomePage_Controller*.
  210
+If we then rebuild the database ([http://localhost/your_site_name/dev/build?flush=all](http://localhost/your_site_name/dev/build?flush=all)), we will see that the *BrowserPollSubmission* table is created. Now we just need to define 'doBrowserPoll' on *HomePage_Controller*:
200 211
 
201  
-*mysite/code/HomePage.php*
  212
+**mysite/code/HomePage.php**
202 213
 
203 214
 	:::php	
204 215
 	class HomePage_Controller extends Page_Controller {
@@ -212,28 +223,21 @@ that the *BrowserPollSubmission* table is created. Now we just need to define 'd
212 223
 	}
213 224
 
214 225
 
215  
-A function that processes a form submission takes two arguments - the first is the data in the form, the second is the
216  
-`[api:Form]` object.
  226
+A function that processes a form submission takes two arguments - the first is the data in the form, the second is the `[api:Form]` object.
217 227
 
218  
-In our function we create a new *BrowserPollSubmission* object. Since the name of our form fields and the name of the
219  
-database fields are the same we can save the form directly into the data object.
220  
-
221  
-We call the 'write' method to write our data to the database, and 'redirectBack()' will redirect the user back
222  
-to the home page.
  228
+In our function we create a new *BrowserPollSubmission* object. Since the name of our form fields, and the name of the database fields, are the same we can save the form directly into the data object.
223 229
 
  230
+We call the 'write' method to write our data to the database, and '$this->redirectBack()' will redirect the user back to the home page.
224 231
 
225 232
 ## Form validation
226 233
 
227  
-SilverStripe forms all have automatic validation on fields where it is logical. For example, all email fields check that
228  
-they contain a valid email address. You can write your own validation by subclassing the *Validator* class.
  234
+SilverStripe forms all have automatic validation on fields where it is logical. For example, all email fields check that they contain a valid email address. You can write your own validation by subclassing the *Validator* class.
229 235
 
230  
-SilverStripe provides the *RequiredFields* validator, which ensures that the fields specified are filled in before the
231  
-form is submitted. To use it we create a new *RequiredFields* object with the name of the fields we wish to be required
232  
-as the arguments, then pass this as a fifth argument to the Form constructor.
  236
+SilverStripe provides the *RequiredFields* validator, which ensures that the fields specified are filled in before the form is submitted. To use it we create a new *RequiredFields* object with the name of the fields we wish to be required as the arguments, then pass this as a fifth argument to the Form constructor.
233 237
 
234 238
 Change the end of the 'BrowserPollForm' function so it looks like this:
235 239
 
236  
-** mysite/code/HomePage.php **
  240
+**mysite/code/HomePage.php**
237 241
 
238 242
 	:::php
239 243
 	public function BrowserPollForm() {
@@ -243,24 +247,20 @@ Change the end of the 'BrowserPollForm' function so it looks like this:
243 247
 	}
244 248
 
245 249
 
246  
-If we then open the homepage and attempt to submit the form without filling in the required fields an error will be
247  
-shown.
248  
-
249  
-![](_images/validation.jpg)
  250
+If we then open the homepage and attempt to submit the form without filling in the required fields errors should appear.
250 251
 
  252
+![](_images/tutorial3_validation.jpg)
251 253
 
252 254
 
253 255
 ## Showing the poll results
254 256
 
255 257
 Now that we have a working form, we need some way of showing the results.
256 258
 
257  
-The first thing to do is make it so a user can only vote once per session. If the user hasn't voted, show the form,
258  
-otherwise show the results.
  259
+The first thing to do is make it so a user can only vote once per session. If the user hasn't voted, show the form, otherwise show the results.
259 260
 
260  
-We can do this using a session variable. The `[api:Session]` class handles all session variables in SilverStripe.
261  
-First modify the 'doBrowserPoll' to set the session variable 'BrowserPollVoted' when a user votes.
  261
+We can do this using a session variable. The `[api:Session]` class handles all session variables in SilverStripe. First modify the 'doBrowserPoll' to set the session variable 'BrowserPollVoted' when a user votes.
262 262
 
263  
-*mysite/code/HomePage.php*
  263
+**mysite/code/HomePage.php**
264 264
 
265 265
 	:::php
266 266
 	// ...
@@ -288,23 +288,18 @@ it is.
288 288
 	}	
289 289
 
290 290
 
291  
-If you visit the home page now you will see you can only vote once per session; 
292  
-after that the form won't be shown. 
293  
-You can start a new session by closing and reopening your browser.
  291
+If you visit the home page now you will see you can only vote once per session; after that the form won't be shown. You can start a new session by closing and reopening your browser (or if you're using Firefox and have installed the [Web Developer](http://chrispederick.com/work/web-developer/) extension, you can use its Clear Session Cookies command).
  292
+
  293
+Although the form is not shown, you'll still see the 'Browser Poll' heading. We'll leave this for now: after we've built the bar graph of the results, we'll modify the template to show the graph instead of the form if the user has already voted.
294 294
 
295  
-Now that we're collecting data, it would be nice to show the results
296  
-on the website as well. We could simply output every vote, but that's boring.
297  
-Let's group the results by browser, through the SilverStripe data model.
  295
+Now that we're collecting data, it would be nice to show the results on the website as well. We could simply output every vote, but that's boring. Let's group the results by browser, through the SilverStripe data model.
298 296
 
299  
-In the [second tutorial](/tutorials/2-extending-a-basic-site), 
300  
-we got a collection of news articles for the home page by 
301  
-using the 'ArticleHolder::get()' function, which returns a `[api:DataList]`.
302  
-We can get all submissions in the same fashion, through `BrowserPollSubmission::get()`.
303  
-This list will be the starting point for our result aggregation.
  297
+
  298
+In the [second tutorial](/tutorials/2-extending-a-basic-site), we got a collection of news articles for the home page by using the 'ArticleHolder::get()' function, which returns a `[api:DataList]`. We can get all submissions in the same fashion, through `BrowserPollSubmission::get()`. This list will be the starting point for our result aggregation.
304 299
 
305 300
 Create the function 'BrowserPollResults' on the *HomePage_Controller* class.
306 301
 
307  
-** mysite/code/HomePage.php **
  302
+**mysite/code/HomePage.php**
308 303
 
309 304
 	:::php
310 305
 	public function BrowserPollResults() {
@@ -327,17 +322,11 @@ This code introduces a few new concepts, so let's step through it.
327 322
 	:::php
328 323
 	$submissions = new GroupedList(BrowserPollSubmission::get());
329 324
 
330  
-
331  
-First we get all of the `BrowserPollSubmission` records from the database. 
332  
-This returns the submissions as a `[api:DataList]`.
333  
-Then we wrap it inside a `[api:GroupedList]`, which adds the ability
334  
-to group those records. The resulting object will behave just like
335  
-the original `DataList`, though (with the addition of a `groupBy()` method).
  325
+First we get all of the `BrowserPollSubmission` records from the database. This returns the submissions as a `[api:DataList]`.Then we wrap it inside a `[api:GroupedList]`, which adds the ability to group those records. The resulting object will behave just like the original `DataList`, though (with the addition of a `groupBy()` method). 
336 326
 
337 327
 	:::php
338 328
 	$total = $submissions->Count();
339 329
 
340  
-
341 330
 We get the total number of submissions, which is needed to calculate the percentages.
342 331
 
343 332
 	:::php
@@ -351,17 +340,14 @@ We get the total number of submissions, which is needed to calculate the percent
351 340
 	}
352 341
 
353 342
 
354  
-Now we create an empty `[api:ArrayList]` to hold the data we'll pass to the template.
355  
-Its similar to `[api:DataList]`, but can hold arbitrary objects rather than just `DataObject` instances.
356  
-Then iterate over the 'Browser' submissions field. 
357  
-The `groupBy()` method splits our list by the 'Browser' field passed to it,
358  
-creating new lists with submissions just for a specific browser.
359  
-Each of those lists is keyed by the browser name.
360  
-The aggregated result is then contained in an `[api:ArrayData]` object,
361  
-which behaves much like a standard PHP array, but allows us to use it in SilverStripe templates.
  343
+Now we create an empty `[api:ArrayList]` to hold the data we'll pass to the template. Its similar to `[api:DataList]`, but can hold arbitrary objects rather than just DataObject` instances. Then we iterate over the 'Browser' submissions field. 
  344
+
  345
+The `groupBy()` method splits our list by the 'Browser' field passed to it, creating new lists with submissions just for a specific browser. Each of those lists is keyed by the browser name. The aggregated result is then contained in an `[api:ArrayData]` object, which behaves much like a standard PHP array, but allows us to use it in SilverStripe templates.
  346
+
362 347
 
363  
-The final step is to create the template to display our data. Change the 'BrowserPoll' div in
364  
-*themes/tutorial/templates/Layout/HomePage.ss* to the below.
  348
+The final step is to create the template to display our data. Change the 'BrowserPoll' div to the below.
  349
+
  350
+**themes/tutorial/templates/Layout/HomePage.ss** 
365 351
 
366 352
 	:::ss
367 353
 	<div id="BrowserPoll">
@@ -384,20 +370,12 @@ The final step is to create the template to display our data. Change the 'Browse
384 370
 Here we first check if the *BrowserPollForm* is returned, and if it is display it. Otherwise the user has already voted,
385 371
 and the poll results need to be displayed.
386 372
 
387  
-We use the normal tactic of putting the data into an unordered list and using CSS to style it, except here we use inline
388  
-styles to display a bar that is sized proportionate to the number of votes the browser has received. You should now have
389  
-a complete poll.
390  
-
391  
-![](_images/pollresults.jpg)
  373
+We use the normal tactic of putting the data into an unordered list and using CSS to style it, except here we use inline styles to display a bar that is sized proportionate to the number of votes the browser has received. You should now have a complete poll.
392 374
 
393  
-<div class="hint" markdown="1">
394  
-While the ORM is
395  
-</div>
  375
+![](_images/tutorial3_pollresults.jpg)
396 376
 
397 377
 ## Summary
398 378
 
399  
-In this tutorial we have explored forms, and seen the different approaches to creating and using forms. Whether you
400  
-decide to use the [userforms module](http://silverstripe.org/user-forms-module) or create a form in PHP depends on the situation and flexibility
401  
-required.
  379
+In this tutorial we have explored custom php forms, and displayed result sets through Grouped Lists. We have briefly covered the different approaches to creating and using forms. Whether you decide to use the [userforms module](http://silverstripe.org/user-forms-module) or create a form in PHP depends on the situation and flexibility required.
402 380
 
403 381
 [Next Tutorial >>](4-site-search)
8  docs/en/tutorials/4-site-search.md
Source Rendered
@@ -2,15 +2,11 @@
2 2
 
3 3
 ## Overview
4 4
 
5  
-This is a short tutorial demonstrating how to add search functionality to a SilverStripe site. It is recommended that
6  
-you have completed the earlier tutorials, especially the tutorial on forms, before attempting this tutorial. While this
7  
-tutorial will add search functionality to the site built in the previous tutorials, it should be straight forward to
8  
-follow this tutorial on any site of your own. 
  5
+This is a short tutorial demonstrating how to add search functionality to a SilverStripe site. It is recommended that you have completed the earlier tutorials, especially the tutorial on forms, before attempting this tutorial. While this tutorial will add search functionality to the site built in the previous tutorials, it should be straight  forward to follow this tutorial on any site of your own. 
9 6
 
10 7
 ## What are we working towards?
11 8
 
12  
-We are going to add a search box on the top of the page. When a user types something in the box, they are taken to a
13  
-results page.
  9
+We are going to add a search box on the top of the page. When a user types something in the box, they are taken to a results page.
14 10
 
15 11
 ![](_images/tutorial4_search.png)
16 12
 
BIN  docs/en/tutorials/_images/searchform-small.jpg
BIN  docs/en/tutorials/_images/tutorial1_editpage-numbered.jpg
BIN  docs/en/tutorials/_images/tutorial2_homepage-news.jpg
BIN  docs/en/tutorials/_images/tutorial3_pollform.jpg
BIN  docs/en/tutorials/_images/tutorial3_pollresults.jpg
BIN  docs/en/tutorials/_images/tutorial3_validation.jpg
BIN  docs/en/tutorials/_images/validation.jpg
BIN  docs/en/tutorials/_images/welcome.png

0 notes on commit 2d80ea5

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