MINOR: Documentation, tutorial (part1)

docs/en/tutorials/1-building-a-basic-site.md

@@ -4,8 +4,7 @@
 
 Welcome to the first in this series of tutorials on the SilverStripe Content Management System (CMS). 
 
-These tutorials are designed to take you from an absolute beginner to being able to build large, complex websites with
-SilverStripe. We assume to begin with, that you have some XHTML, CSS and PHP knowledge. This first tutorial provides an absolute
+These tutorials are designed to take you from an absolute beginner to being able to build large, complex websites with SilverStripe. We assume to begin with, that you have some XHTML, CSS and PHP knowledge. This first tutorial provides an absolute
 introduction to building a simple website using SilverStripe. It will also teach you how to use the content management system at a basic level.
 
 ##  What are we working towards?
@@ -16,8 +15,7 @@ templates - one for the home page, and one for the rest of the site.
 
 ##  Installation
 
-You need to [download the SilverStripe software](http://www.silverstripe.org/stable-download) and install it to your local
-machine or to a webserver. 
+You need to [download the SilverStripe software](http://www.silverstripe.org/stable-download) and install it to your local machine or to a webserver. 
 
 For more infomation about installing and configuring a webserver read the [Installation instructions and videos](../installation). 
 
@@ -27,7 +25,7 @@ This tutorial uses the SilverStripe CMS default theme 'Simple' which you will fi
 
 After installation, open up the folder where you installed SilverStripe. 
 
-If you installed on windows with WAMP, it will likely be at *c:\wamp\wwww*. On Mac OS X with MAMP, it will likely be at */Applications/MAMP/htdocs/*
+If you installed on windows with WAMP, it will likely be at *c:\wamp\wwww*. On Mac OS X, using the built in webserver, it will be in your sites directory */Sites/* (with MAMP, it will likely be at */Applications/MAMP/htdocs/*)
 
 Let's have a look at the folder structure.
 
@@ -36,8 +34,8 @@ Let's have a look at the folder structure.
  | assets/   | | Contains images and other files uploaded via the SilverStripe CMS. You can also place your own content inside it, and link to it from within the content area of the CMS. | 
  | cms/      | | Contains all the files that form the CMS area of your site. It’s structure is similiar to the mysite/ directory, so if you find something interesting, it should be easy enough to look inside and see how it was built. | 
  | framework/ | | The framework that builds both your own site and as the CMS that powers it. You’ll be utilizing files in this directory often, both directly and indirectly.                                                             | 
- | mysite/   | | Contains all your sites code (mainly PHP and JavaScript)  | 
- | themes/   | | Combines all images, stylesheets and templates powering your website into a reusable "theme" | 
+ | mysite/   | | Contains all your sites code (mainly PHP)  | 
+ | themes/   | | Combines all images, stylesheets, javascript and templates powering your website into a reusable "theme" | 
       
 When designing your site you should only need to modify the *mysite*, *themes* and *assets* folders. The rest of the folders contain files and data that are not specific to any site.
 
@@ -47,43 +45,34 @@ When designing your site you should only need to modify the *mysite*, *themes* a
 
 ![](_images/tutorial1_cms-basic.jpg)
 
-The CMS is the area in which you can manage your site content. You can access the cms at http://localhost/admin (or http://yourdomain.com/admin if you are using you own domain name). You
-will be presented with a login screen. You can login with the details you provided at installation. After logging in you
-should be greeted with the CMS and a list of the pages currently in the CMS. Here you can add, delete and reorganize the pages using the buttons at the top. Clicking on a page will open it in the page editing interface pictured below (we've entered some test content).
+The CMS is the area in which you can manage your site content. You can access the cms at http://localhost/your_site_name/admin (or http://yourdomain.com/admin if you are using you own domain name). You
+will be presented with a login screen. Login using the details you provided at installation. After logging in you
+should see the CMS interface with a list of the pages currently on your website (the site tree). Here you can add, delete and reorganize pages. If you need to delete, publish, or unpublish a page, first check "multi-selection" at the top. You will then be able to perform actions on any checked files using the "Actions" dropdown. Clicking on a page will open it in the page editing interface pictured below (we've entered some test content).
 
 ![](_images/tutorial1_cms-numbered.jpg)
 
-1.  These buttons allow you to move between the different sections in the CMS. There are four core sections in the CMS - "Pages", "Files", "Users" and "Settings". Modules may have their own sections here as well, if any are installed. In this tutorial we will be focusing on the "Pages" section.
-2.  While in "Pages" you can quickly move between the pages in the CMS by clicking the vertical bar between the CMS menu and the editor. This will slide out a sidebar. To hide this, click the arrow at the bottom of the sidebar.
-
-![](_images/tutorial1_cms-numbered-2b.jpg)
-
-3.  This section allows you to edit the content for the currently selected page, as well as changing other properties of the page such as the page name and URL. The content editor has full [WYSIWYG](http://en.wikipedia.org/wiki/WYSIWYG) abilities, allow you to change formatting and insert links, images and tables.
-4.  These buttons allow you to save your changes to the draft copy, publish your draft copy, unpublish from the live website or remove a page from the draft website. 
-The SilverStripe CMS workflow stores two copies of a page, a draft and a published one. By having separate draft & published copies, we can preview draft changes in the site before publishing them to the live website. You can quickly preview your draft pages without leaving the CMS by clicking the "Preview" button.
-
-### Page Editor
-
-Once you have selected a page to modify from the Pages section your page will open in the Page Editior. 
-
-The Edit Page section has 3 main areas in which you can edit the content of the page, change the settings and track your revision history (These will be covered in more detail further on in the tutorials).
-
-![](_images/tutorial1_editpage-numbered.jpg)
-
-1.  *Content* - Allows you to set the title, wysiwyg content, URL and Meta data for your page.
-2.  *Settings* - Here you set the type of page behavior, parent page, show in search, show in menu, and who can view or edit the page.
-3.  *History* - This allow you to view previous version of your page, compare change and revert to previous version if need be.
+1.  This menu allows you to move between different sections of the CMS. There are four core sections - "Pages", "Files", "Users" and "Settings". If you have modules installed, they may have their own sections here. In this tutorial we will be focusing on the "Pages" section.
+2.  The breadcrumbs on the left will show you a direct path to the page you are currently looking at. You can use this path to navigate up through a page's heirarchy. On the left there are tabs you may use to flick between different aspects of a page. By default, you should be shown three tabs: "Content", "Settings", and "History". 
+ * Content - Allows you to set the title, wysiwyg content, URL and Meta data for your page.  
+ * Settings - Here you set the type of page behavior, parent page, show in search, show in menu, and who can view or edit the page.  
+ * History - This allows you to view previous version of your page, compare change and revert to previous version if need be.  
+3.  Within the "Pages" section (provided you are in the "Content", or "Settings" tab) you can quickly move between pages in the CMS using the site tree. To collapse and expand this sidebar, click the arrow at the bottom. If you are in the history tab, you will notice the site tree has been replaced by a list of the alterations to the current page.  
+![](_images/tutorial1_cms-numbered-3.jpg)  
+4.  This section allows you to edit the content for the currently selected page, as well as changing other properties of the page such as the page name and URL. The content editor has full [WYSIWYG](http://en.wikipedia.org/wiki/WYSIWYG) abilities, allow you to change formatting and insert links, images and tables.
+5.  These buttons allow you to save your changes to the draft copy, publish your draft copy, unpublish from the live website or remove a page from the draft website. The SilverStripe CMS workflow stores two copies of a page, a draft and a published one. By having separate draft & published copies, we can preview draft changes in the site before publishing them to the live website. You can quickly preview your draft pages without leaving the CMS by clicking the "Preview" button.
 
+![](_images/tutorial1_cms-numbered-5.jpg)  
 
 ### Try it
 
 There are three pages already created for you - "Home", "About Us" and "Contact Us", as well as a 404 page. Experiment
-with the editor - try different formatting, tables and images. When you are done, click "Save" to save the page or "Save
+with the editor - try different formatting, tables and images. When you are done, click "Save Draft" or "Save
 & Publish" to post the content to the live site. 
 
-When you create a new page, you are given a drop down that allows you to set the structure of the page (Top level or Under another page) and the page type. 
-The page type specifies the templates used to render the page, the fields that are able to be edited in the CMS, and page specific
-behavior. We will explain page types in more depth as we progress; for now, make all pages of the type "Page".
+### New pages
+To create a new page, click the add new button above the site tree.  
+When you create a new page, you are given the option of setting the structure of the page (Top level or Under another page) and the page type. 
+The page type specifies the templates used to render the page, the fields that are able to be edited in the CMS, and page specific behavior. We will explain page types in more depth as we progress; for now, make all pages of the type "Page".
 
 ![](_images/tutorial1_addpage.jpg)
 
@@ -139,8 +128,8 @@ browser and are formatted either with a *$* at the beginning or are between the
 
 **Flushing the cache**
 
-Whenever we edit a template file, we need to append *?flush=1* onto the end of the URL, e.g.
-http://localhost/home/?flush=1. SilverStripe stores template files in a cache for quicker load times. Whenever there are
+Whenever we edit a template file, we need to append *?flush=all* onto the end of the URL, e.g.
+http://localhost/home/?flush=all. SilverStripe stores template files in a cache for quicker load times. Whenever there are
 changes to the template, we must flush the cache in order for the changes to take effect.
 
 ##  The Navigation System
@@ -158,7 +147,9 @@ Menu for our site are created using a **loop**. Loops allow us to iterate over a
 	:::ss
 	<ul>
 		<% loop Menu(1) %>	  
-			<li class="$LinkingMode"><a href="$Link" title="$Title.XML">$MenuTitle.XML</a></li>
+			<li class="$LinkingMode">
+				<a href="$Link" title="$Title.XML">$MenuTitle.XML</a>
+			</li>
 		<% end_loop %>
 	</ul>
 
@@ -171,20 +162,31 @@ This creates the navigation at the top of the page:
 
 
 
-## Highlighting the current page
+### Highlighting the current page
 
 A useful feature is highlighting the current page the user is looking at. We can do this with the template variable
-*$LinkingMode* which we mentioned before. *$LinkingMode* returns one of three values:
+*$LinkingMode*, mentioned earlier. *$LinkingMode* returns one of three values:
 
-*  *current* - This page is being visited, and should be highlighted
-*  *link* - The page is not currently being visited, so shouldn't be highlighted
-*  *section* - A page under this page is being visited so you probably want to highlight it.
+*  *current* - This page is being visited
+*  *link* - This page is not currently being visited
+*  *section* - A page under this page is being visited
 
-> For example: if you were visiting a staff member such as "Home > Company > Staff > Bob Smith", you would want to highlight 'Company' to say you are in that section.
+> For example, if you were here: "Home > Company > Staff > Bob Smith", you may want to highlight 'Company' to say you are in that section. If you add $LinkingMode to your navigation elements as a class, ie:
+	:::ss
+	<li class="$LinkingMode">
+	 	<a href="$Link" title="$Title.XML">$MenuTitle.XML</a>
+	</li>
 
-Highlighting the current page is easy, simply assign a css class based on the value of *$LinkingMode*. Then provide a different style for current/section in css, as has been provided for you in *simple/css/layout.css*. 
-
-![](_images/tutorial1_menu-highlighted.jpg)
+you will then be able to target a section in css (*simple/css/layout.css*), ie: 
+	:::ss
+	.section { 
+		background:#ccc;
+	} 
+You may also style the link to the current page this way, eg:
+	:::ss	
+	.current { 
+		/* Your styles here */
+	} 
 
 ## A second level of navigation
 
@@ -210,7 +212,12 @@ Open up */themes/simple/templates/Includes/Sidebar.ss* template and look at the
 	:::ss
 	<ul>
 	  <% loop Menu(2) %>
-	    <li class="$LinkingMode"><a href="$Link" title="Go to the $Title.XML page"><span class="arrow">&rarr;</span><span class="text">$MenuTitle.XML</span></a></li>
+	    <li class="$LinkingMode">
+		    <a href="$Link" title="Go to the $Title.XML page">
+		    	<span class="arrow">&rarr;</span>
+		    	<span class="text">$MenuTitle.XML</span>
+		    </a>
+	    </li>
 	  <% end_loop %>
 	</ul>
 
@@ -228,7 +235,12 @@ like this:
 		...
 			<ul>
 				<% loop Menu(2) %>
-				<li class="$LinkingMode"><a href="$Link" title="Go to the $Title.XML page"><span class="arrow">&rarr;</span><span class="text">$MenuTitle.XML</span></a></li>
+				<li class="$LinkingMode">
+					<a href="$Link" title="Go to the $Title.XML page">
+						<span class="arrow">&rarr;</span>
+						<span class="text">$MenuTitle.XML</span>
+					</a>
+				</li>
 				<% end_loop %>
 			</ul>
 		...
@@ -244,37 +256,44 @@ Open up */themes/simple/templates/Includes/BreadCrumbs.ss* template and look at
 
 	:::ss
 	<% if Level(2) %>
-	<div id="Breadcrumbs">
-	   	$Breadcrumbs
-	</div>
-<% end_if %>	
+		<div id="Breadcrumbs">
+		   	$Breadcrumbs
+		</div>
+	<% end_if %>	
 
 Breadcrumbs are only useful on pages that aren't in the top level. We can ensure that we only show them if we aren't in
 the top level with another if statement.
 
-The *Level* page control allows you to get data from the page's parents, e.g. if you used *Level(1)*, you could use
-*$Level(1).Title* to get the top level page title. In this case, we merely use it to check the existence of a second
-level page; if one exists then we include the breadcrumbs.
+The *Level* page control allows you to get data from the page's parents, e.g. if you used *Level(1)*, you could use:
+	:::ss
+	$Level(1).Title 
 
-This shows how the two level navigation system functions. Both menus should be updating and highlighting as you move
-from page to page. They will also mirror changes done in the SilverStripe CMS, such as renaming pages or moving them
-around.
+to get the top level page title. In this case, we merely use it to check the existence of a second level page: if one exists then we include breadcrumbs.
+
+Both the top menu, and the sidebar menu should be updating and highlighting as you move from page to page. They will also mirror changes done in the SilverStripe CMS, such as renaming pages or moving them around.
 
 ![](_images/tutorial1_menu-two-level.jpg)
 
-Feel free to experiment with the if and loop blocks, for example you could create a drop down style menu from the top navigation using a combination of the if blocks, loop blocks and some CSS to style it. This uses a *Children* if and loop block which checks to see if there is any sub-pages available within each top level navigation item, you will need to come up with your own CSS to correctly style this approach.
+Feel free to experiment with the if and loop statements, for example you could create a drop down style menu from the top navigation using a combination of if statements, loops and some CSS to style it. 
 
-	::ss
+The following example runs an if statement, and a loop on *Children*, checking to see if any sub-pages exist within each top level navigation item, you will need to come up with your own CSS to correctly style this approach.
+
+	:::ss
 	<ul>
 	  <% loop Menu(1) %>
 	    <li class="$LinkingMode">
 	      <a href="$Link" title="$Title.XML">$MenuTitle.XML</a>
 	      <% if Children %>
-	      <ul>
-	        <% loop Children %>
-	          <li class="$LinkingMode"><a href="$Link" title="Go to the $Title.XML page"><span class="arrow">&rarr;</span><span class="text">$MenuTitle.XML</span></a></li>
-	        <% end_loop %>
-	      <ul>
+		      <ul>
+		        <% loop Children %>
+		          <li class="$LinkingMode">
+		          	<a href="$Link" title="Go to the $Title.XML page">
+		          		<span class="arrow">&rarr;</span>
+		          		<span class="text">$MenuTitle.XML</span>
+		          	</a>
+		          </li>
+		        <% end_loop %>
+		      <ul>
 	      <% end_if %>
 	    </li>
 	  <% end_loop %>
@@ -294,8 +313,7 @@ banner to welcome visitors.
 ### Creating a new page type
 
 Earlier we stated that every page in a SilverStripe site has a **page type**, and that SilverStripe will look for a
-template or template layout corresponding to the page type. Therefore, the first step to get the homepage using a different template is to
-create a new page type.
+template, or template layout, corresponding to the page type. Therefore, the first step when switching the homepage template is to create a new page type.
 
 Each page type is represented by two php classes: a *data object* and a *controller*. Don't worry about the details of page
 types right now, we will go into much more detail in tutorial two.
@@ -321,7 +339,7 @@ Create a new file *HomePage.php* in *mysite/code*. Copy the following code into
 
 
 Every page type also has a database table corresponding to it. Every time we modify the database, we need to rebuild it.
-We can do this by going to [http://localhost/dev/build?flush=1](http://localhost/dev/build?flush=1) or replace *localhost* with your own domain name. 
+We can do this by going to [http://localhost/dev/build?flush=all](http://localhost/dev/build?flush=1) (replace *localhost* with your own domain name if applicable). 
 
 It may take a moment, so be patient. This add tables and fields needed by your site, and modifies any structures that have changed. It
 does this non-destructively - it will never delete your data.
@@ -332,7 +350,7 @@ As we have just created a new page type, SilverStripe will add this to the list
 
 After building the database, we can change the page type of the homepage in the CMS. 
 
-Navigate in the CMS to the "Home" page and under the "Behaviour" tab in the "Edit Page > Settings" section. Change it to *Home Page*, and click "Save & Publish".
+In the CMS, navigate to the "Home" page and switch to the "Settings" tab. Change "Page type" to *Home Page*, and click "Save & Publish".
 
 ![](_images/tutorial1_homepage-type.jpg)
 
@@ -345,11 +363,17 @@ to the template of the page type's parents.
 
 ### Creating a new template
 
-To create a new template layout, create a copy of *Page.ss* (found in *themes/simple/templates/Layouts*) and call it *HomePage.ss*. If we flush the cache (*?flush=1*), SilverStripe should now be using *HomePage.ss* for the homepage, and *Page.ss* for the rest of the site. Now let's customize the *HomePage* template. 
+To create a new template layout, create a copy of *Page.ss* (found in *themes/simple/templates/Layouts*) and call it *HomePage.ss*. If we flush the cache (*?flush=all*), SilverStripe should now be using *HomePage.ss* for the homepage, and *Page.ss* for the rest of the site. Now let's customize the *HomePage* template. 
 
-First, remove the breadcrumbs and the secondary menu by removing the `<% include SideBar %>` line of code; we don't need them for the homepage. Let's replace the title with an image. Add this line above the *$Content* variable.
+First, remove the breadcrumbs and the secondary menu by removing:
+	<% include SideBar %> 
+ we don't need it for the homepage. 
 
-Now add the following to replace the `<h1>$Title</h1>` code in your template:
+Let's replace the title with an image. Find this line:
+	:::ss
+	<h1>$Title</h1>
+
+ and replace it with:
 
 	:::ss
 	<div id="Banner">
@@ -365,21 +389,16 @@ Your Home page should now look like this:
 SilverStripe first searches for a template in the *themes/simple/templates* folder. Since there is no *HomePage.ss*,
 it will use the *Page.ss* for both *Page* and *HomePage* page types. When it comes across the *$Layout* tag, it will
 then descend into the *themes/simple/templates/Layout* folder, and will use *Page.ss* for the *Page* page type, and
-*HomePage.ss* for the *HomePage* page type. So while you could create a HomePage.ss in the *themes/simple/templates/* it is better to reuse the navigation and footer common to both our Home page and the rest of the pages on our website and lets you write less code to achieve the end result.
+*HomePage.ss* for the *HomePage* page type. So while you could create a HomePage.ss in the *themes/simple/templates/* it is better to reuse the navigation and footer common to both our Home page and the rest of the pages on our website.
 
 ![](_images/tutorial1_subtemplates-diagram.jpg)
 
 
 ## Summary
 
-We have introduced template variables, controls and if blocks, and we have used these
-to build a basic but fully functional site. You have also been briefly introduced to page types, and seen how they
-correspond to templates and sub-templates. By using these templates, you have seen how to customize the site content
-according to the page type of the page you are displaying.
+So far we have learnt about template variables, controls and if statements. We have used these to build a basic but fully functional website. We have also briefly covered page types, and looked at how they correspond to templates and sub-templates. Using templates, we have customized our website's design according to the page type of any given page.
 
-In the next tutorial, [Extending a Basic Site](2-extending-a-basic-site), we will explore page types on a
-deeper level, and see how you can customize your own page types to extend SilverStripe to do much more interesting
-things.
+In the next tutorial, [Extending a Basic Site](2-extending-a-basic-site), we will explore page types on a deeper level, and look at customising our own page types to extend the functionality of SilverStripe.
 
 [Next Tutorial >>](2-extending-a-basic-site)