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

Fixed up Forms documentation, and replaced some images in first 2
tutorials

docs/en/tutorials/2-extending-a-basic-site.md

@@ -135,9 +135,9 @@ To add our new fields to the CMS we have to override the *getCMSFields()* method
 		public function getCMSFields() {
 			$fields = parent::getCMSFields();
 			
-			$datefield = new DateField('Date');
-			$datefield->setConfig('showcalendar', true);
-			$fields->addFieldToTab('Root.Main', $datefield, 'Content');
+			$dateField = new DateField('Date');
+			$dateField->setConfig('showcalendar', true);
+			$fields->addFieldToTab('Root.Main', $dateField, 'Content');
 			$fields->addFieldToTab('Root.Main', new TextField('Author'), 'Content');
 			
 			return $fields;
@@ -202,18 +202,17 @@ the date field will have the date format defined by your locale.
 		$fields = parent::getCMSFields();
 		
 		$fields->addFieldToTab('Root.Main', $dateField = new DateField('Date','Article Date (for example: 20/12/2010)'), 'Content');
-		$dateField->setConfig('showcalendar', true);
-		$dateField->setConfig('dateformat', 'dd/MM/YYYY');
-		
-		$fields->addFieldToTab('Root.Main', new TextField('Author','Author Name'), 'Content');
-		
+        $dateField->setConfig('showcalendar', true);
+        $fields->addFieldToTab('Root.Main', $dateField, 'Content');
+        $fields->addFieldToTab('Root.Main', new TextField('Author'), 'Content');
+
 		return $fields;
 	}
 
 Let's walk through these changes.
 
 	:::php
-	$fields->addFieldToTab('Root.Content', $dateField = new DateField('Date','Article Date (for example: 20/12/2010)'), 'Content');
+	$fields->addFieldToTab('Root.Main', $dateField = new DateField('Date','Article Date (for example: 20/12/2010)'), 'Content');
 
 *$dateField* is declared only to in order to change the configuration of the DateField.
 
@@ -228,7 +227,7 @@ By enabling *showCalendar* you show a calendar overlay when clicking on the fiel
 *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.
 
 	:::php
-	$fields->addFieldToTab('Root.Content', new TextField('Author','Author Name'), 'Content');
+	$fields->addFieldToTab('Root.Main', new TextField('Author','Author Name'), 'Content');
 
 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.
 
@@ -309,7 +308,7 @@ We can make our templates more modular and easier to maintain by separating comm
 
 We'll separate the display of linked articles as we want to reuse this code later on.
 
-Cut the code in *ArticleHolder.ss** and replace it with an include statement:
+Cut the code between "loop Children" in *ArticleHolder.ss** and replace it with an include statement:
 
 **themes/simple/templates/Layout/ArticleHolder.ss**
 
@@ -371,7 +370,7 @@ This function simply runs a database query that gets the latest news articles fr
 
 	:::ss
 	...
-	<div class="content">$Content</div>
+		<div class="content">$Content</div>
 	</article>
 	<% loop LatestNews %>
 		<% include ArticleTeaser %>

docs/en/tutorials/3-forms.md

@@ -2,30 +2,22 @@
 
 ## Overview
 
-This tutorial is intended to be a continuation of the first two tutorials, and will build on the site produced in those
-two tutorials.
+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.
 
-This tutorial explores forms in SilverStripe. It will look at coded forms. Forms which need to be written in PHP.
-
-Another method which allows you to construct forms via the CMS is by using the [userforms module](http://silverstripe.org/user-forms-module). 
-A UserDefinedForm is much quicker to implement, but lacks the flexibility of a coded form. 
+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. 
 
 ## What are we working towards?
 
-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.
+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.
 
-![tutorial:pollresults-small.png](_images/pollresults-small.jpg)
+![tutorial:tutorial3_pollresults.png](_images/tutorial3_pollresults.jpg)
 
 
 ## Creating the form
 
-We will be creating a form for a poll on the home page.
+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*.
 
-The poll will ask the user's name and favourite web browser, and then collate the results into a bar graph. We create
-the form in a method on *HomePage_Controller*.
-
-*mysite/code/HomePage.php*
+**mysite/code/HomePage.php**
 
 	:::php
 	class HomePage_Controller extends Page_Controller {
@@ -78,7 +70,7 @@ Let's step through this code.
 
 First we create our form fields.
 
-We do this by creating a `[api:FieldList]` and passing our fields as arguments. The first field is a new
+We do this by creating a `[api:FieldList]` and passing our fields as arguments. The first field is a  
 `[api:TextField]` with the name 'Name'.
 
 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.
 
 After creating the form function, we need to add the form to our home page template.
 
-Add the following code to the home page template, just before the Content `<div>`:
+Add the following code to the top of your home page template, just before the first Content `<div>`:
 
-*themes/tutorial/templates/Layout/HomePage.ss*
+**themes/tutorial/templates/Layout/HomePage.ss**
 
 	:::ss
 	...
@@ -125,12 +117,31 @@ Add the following code to the home page template, just before the Content `<div>
 		<h2>Browser Poll</h2>
 		$BrowserPollForm
 	</div>
-	<div id="Content">
+	<div class="Content">
 	...
 
+your HomePage.ss file should now look like this:
+	:::ss
+	<div id="BrowserPoll">
+		<h2>Browser Poll</h2>
+		 $BrowserPollForm
+	</div>
+
+	<div class="content-container typography">	
+		<article>
+			<div id="Banner">
+	  			<img src="http://www.silverstripe.org/themes/silverstripe/images/sslogo.png" alt="Homepage image" />
+			</div>
+			
+			<div class="content">$Content</div>
+		</article>
+		$Form
+		$PageComments
+	</div>	
+
 Add the following code to the form style sheet:
 
-*themes/tutorial/css/form.css*
+**themes/tutorial/css/form.css**
 
 	:::css
 	/* BROWSER POLL */
@@ -142,21 +153,27 @@ Add the following code to the form style sheet:
 		form FieldList {
 			border:0;
 		}
-		#BrowserPoll .message {
-			display: block;
-			color:red;
-			background:#ddd;
-			border:1px solid #ccc;
-			padding:5px;
-			margin:5px;
-		}
+   		#BrowserPoll .message {
+            float:left;
+            display: block;
+            color:red;
+            background:#efefef;
+            border:1px solid #ccc;
+            padding:5px;
+            margin:5px;
+        }
 		#BrowserPoll h2 {
 			font-size: 1.5em;
+			line-height:2em;
 			color: #0083C8;
 		}
 		#BrowserPoll .field {
 			padding:3px 0;
 		}
+		#BrowserPoll input.text {
+			padding: 0;
+			font-size:1em;
+		}
 		#BrowserPoll .Actions {
 			padding:5px 0;
 		}
@@ -165,25 +182,20 @@ Add the following code to the form style sheet:
 		}
 
 
-This CSS code will ensure that the form is formatted and positioned correctly. All going according to plan, if you visit
-[http://localhost/home?flush=1](http://localhost/home?flush=1) it should look something like below.
+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:
 
-![](_images/pollform.jpg)
+![](_images/tutorial3_pollform.jpg)
 
 
 ## Processing the form
 
-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.
+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.
 
-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]`.
+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]`.
 
-If you recall, in tutorial two we said that all objects that inherit from DataObject and that add fields are stored in
-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 extend DataObject directly.
+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:
 
-*mysite/code/BrowserPollSubmission.php*
+**mysite/code/BrowserPollSubmission.php**
 
 	:::php
 	<?php	
@@ -195,10 +207,9 @@ extending SiteTree (or `[api:Page]`) to create a page type, we extend DataObject
 	}
 
 
-If we then rebuild the database ([http://localhost/dev/build?flush=1](http://localhost/dev/build?flush=1)), we will see
-that the *BrowserPollSubmission* table is created. Now we just need to define 'doBrowserPoll' on *HomePage_Controller*.
+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*:
 
-*mysite/code/HomePage.php*
+**mysite/code/HomePage.php**
 
 	:::php	
 	class HomePage_Controller extends Page_Controller {
@@ -212,28 +223,21 @@ that the *BrowserPollSubmission* table is created. Now we just need to define 'd
 	}
 
 
-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.
+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.
 
-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.
-
-We call the 'write' method to write our data to the database, and 'redirectBack()' will redirect the user back
-to the home page.
+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.
 
+We call the 'write' method to write our data to the database, and '$this->redirectBack()' will redirect the user back to the home page.
 
 ## Form validation
 
-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.
+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.
 
-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.
+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.
 
 Change the end of the 'BrowserPollForm' function so it looks like this:
 
-** mysite/code/HomePage.php **
+**mysite/code/HomePage.php**
 
 	:::php
 	public function BrowserPollForm() {
@@ -243,24 +247,20 @@ Change the end of the 'BrowserPollForm' function so it looks like this:
 	}
 
 
-If we then open the homepage and attempt to submit the form without filling in the required fields an error will be
-shown.
-
-![](_images/validation.jpg)
+If we then open the homepage and attempt to submit the form without filling in the required fields errors should appear.
 
+![](_images/tutorial3_validation.jpg)
 
 
 ## Showing the poll results
 
 Now that we have a working form, we need some way of showing the results.
 
-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.
+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.
 
-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.
+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.
 
-*mysite/code/HomePage.php*
+**mysite/code/HomePage.php**
 
 	:::php
 	// ...
@@ -288,23 +288,18 @@ it is.
 	}	
 
 
-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.
+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).
 
-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.
+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.
 
-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.
+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.
+
+
+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.
 
 Create the function 'BrowserPollResults' on the *HomePage_Controller* class.
 
-** mysite/code/HomePage.php **
+**mysite/code/HomePage.php**
 
 	:::php
 	public function BrowserPollResults() {
@@ -327,17 +322,11 @@ This code introduces a few new concepts, so let's step through it.
 	:::php
 	$submissions = new GroupedList(BrowserPollSubmission::get());
 
-
-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).
+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). 
 
 	:::php
 	$total = $submissions->Count();
 
-
 We get the total number of submissions, which is needed to calculate the percentages.
 
 	:::php
@@ -351,17 +340,14 @@ We get the total number of submissions, which is needed to calculate the percent
 	}
 
 
-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 iterate over the 'Browser' submissions field. 
-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.
+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. 
 
-The final step is to create the template to display our data. Change the 'BrowserPoll' div in
-*themes/tutorial/templates/Layout/HomePage.ss* to the below.
+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.
+
+
+The final step is to create the template to display our data. Change the 'BrowserPoll' div to the below.
+
+**themes/tutorial/templates/Layout/HomePage.ss** 
 
 	:::ss
 	<div id="BrowserPoll">
@@ -384,20 +370,12 @@ The final step is to create the template to display our data. Change the 'Browse
 Here we first check if the *BrowserPollForm* is returned, and if it is display it. Otherwise the user has already voted,
 and the poll results need to be displayed.
 
-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.
+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.
 
-![](_images/pollresults.jpg)
-
-<div class="hint" markdown="1">
-While the ORM is
-</div>
+![](_images/tutorial3_pollresults.jpg)
 
 ## Summary
 
-In this tutorial we have explored forms, and seen 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.
+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.
 
 [Next Tutorial >>](4-site-search)

docs/en/tutorials/4-site-search.md

@@ -2,15 +2,11 @@
 
 ## Overview
 
-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. 
+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. 
 
 ## What are we working towards?
 
-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.
+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.
 
 ![](_images/tutorial4_search.png)