Skip to content
This repository
Browse code

MINOR: Documentation, tutorial (part2)

  • Loading branch information...
commit 14753e9b5fe4e887dfaf9d8bbaa12a194a922c31 1 parent 2c024e4
Naomi Guyer authored June 28, 2012
80  docs/en/tutorials/1-building-a-basic-site.md
Source Rendered
@@ -105,31 +105,47 @@ for a template file in the *simple/templates* folder, with the name `<PageType>`
105 105
 
106 106
 Open *themes/simple/templates/Page.ss*. It uses standard HTML apart from these exceptions: 
107 107
 
108  
-`<% base_tag %>` is replaced with the HTML [base element](http://www.w3.org/TR/html401/struct/links.html#h-12.4). This
  108
+	:::ss
  109
+	<% base_tag %>
  110
+
  111
+The base_tag variable is replaced with the HTML [base element](http://www.w3.org/TR/html401/struct/links.html#h-12.4). This
109 112
 ensures the browser knows where to locate your site's images and css files.
110 113
 
111  
-*$MetaTitle, $Title, and $SiteConfig.Title* in the html <title> tag are replaced by the title set in the Meta tags, Page Name, or Settings -> Site Title.
  114
+	:::ss
  115
+	$MetaTitle
  116
+	$Title
  117
+	$SiteConfig.Title
112 118
 
113  
-*$Title* is simply replaced with the name of the page ('Page name' on the 'Main' tab in the editor).
  119
+These three variables are found within the html <title> tag, and are replaced by the text set in the Meta Title, Page Name, or Settings -> Site Title in the CMS.
  120
+	
  121
+	:::ss
  122
+	$MetaTags 
114 123
 
115  
-*$MetaTags* adds meta tags for search engines, as well as the page title ('Title' on the 'Meta-data' tab in the
116  
-editor). You can define your metatags in the meta-data tab off the content editor in the CMS. 
  124
+The MetaTags variable will add meta tags, which are used by search engines. You can define your meta tags in the tab fields at the bottom of the content editor in the CMS. 
  125
+	:::ss
  126
+	$Layout 
117 127
 
118  
-*$Layout* is replaced with the contents of a template file with the same name as the page type we are using. 
  128
+The Layout variable is replaced with the contents of a template file with the same name as the page type we are using. 
119 129
 
120 130
 Open *themes/simple/templates/Layout/Page.ss*. You will see more HTML and more SilverStripe template replacement tags and variables.
  131
+	
  132
+	:::ss
  133
+	$Content
121 134
 
122  
-*$Content* is replaced with the content of the page currently being viewed. This allows you to make all changes to
  135
+The Content variable is replaced with the content of the page currently being viewed. This allows you to make all changes to
123 136
 your site's content in the CMS.
124 137
 
125 138
 These template markers are processed by SilverStripe into HTML before being sent to your
126  
-browser and are formatted either with a *$* at the beginning or are between the SilverStripe template tags *`<%  %>`*.
  139
+browser and are formatted either with a *$* at the beginning or are between the SilverStripe template tags: 
  140
+
  141
+	:::ss
  142
+	<%  %>
127 143
 
128 144
 
129 145
 **Flushing the cache**
130 146
 
131 147
 Whenever we edit a template file, we need to append *?flush=all* onto the end of the URL, e.g.
132  
-http://localhost/home/?flush=all. SilverStripe stores template files in a cache for quicker load times. Whenever there are
  148
+http://localhost/your_site_name/?flush=all. SilverStripe stores template files in a cache for quicker load times. Whenever there are
133 149
 changes to the template, we must flush the cache in order for the changes to take effect.
134 150
 
135 151
 ##  The Navigation System
@@ -138,11 +154,16 @@ We are now going to look at how the navigation system is implemented in the temp
138 154
 
139 155
 Open up *themes/simple/templates/Includes/Navigation.ss*
140 156
 
141  
-Menu for our site are created using a **loop**. Loops allow us to iterate over a data set, and render each item using a sub-template. The
142  
-**loop** *Menu(1)* returns the set of the first level menu items. We can then use the template variable
143  
-*$MenuTitle* to show the title of the page we are linking to, $Link for the URL of the page and $LinkingMode to help style our menu with CSS (explained in more detail shortly).
  157
+The Menu for our site is created using a **loop**. Loops allow us to iterate over a data set, and render each item using a sub-template.
  158
+	 
  159
+	:::ss 
  160
+	<% loop Menu(1) %>
  161
+
  162
+returns a set of first level menu items. We can then use the template variable
  163
+*$MenuTitle* to show the title of the page we are linking to, *$Link* for the URL of the page and *$LinkingMode* to help style our menu with CSS (explained in more detail shortly).
  164
+
  165
+> *$Title* refers to **Page Name** in the CMS, whereas *$MenuTitle* refers to (the often shorter) **Navigation label**
144 166
 
145  
-> $Title refers to *Page Name* in the CMS, whereas $MenuTitle refers to (the often shorter) *Navigation label*
146 167
 
147 168
 	:::ss
148 169
 	<ul>
@@ -164,8 +185,11 @@ This creates the navigation at the top of the page:
164 185
 
165 186
 ### Highlighting the current page
166 187
 
167  
-A useful feature is highlighting the current page the user is looking at. We can do this with the template variable
168  
-*$LinkingMode*, mentioned earlier. *$LinkingMode* returns one of three values:
  188
+A useful feature is highlighting the current page the user is looking at. We can do this with the template variable:
  189
+	:::ss
  190
+	$LinkingMode
  191
+
  192
+*$LinkingMode* returns one of three values:
169 193
 
170 194
 *  *current* - This page is being visited
171 195
 *  *link* - This page is not currently being visited
@@ -178,16 +202,23 @@ A useful feature is highlighting the current page the user is looking at. We can
178 202
 	</li>
179 203
 
180 204
 you will then be able to target a section in css (*simple/css/layout.css*), ie: 
181  
-	:::ss
  205
+	:::css
182 206
 	.section { 
183 207
 		background:#ccc;
184 208
 	} 
185 209
 You may also style the link to the current page this way, eg:
186  
-	:::ss	
  210
+	:::css	
187 211
 	.current { 
188 212
 		/* Your styles here */
189 213
 	} 
190 214
 
  215
+Or, target links that are neither current nor in the same section as the current link, eg:
  216
+
  217
+	:::css	
  218
+	.link { 
  219
+		/* Your styles here */
  220
+	} 
  221
+
191 222
 ## A second level of navigation
192 223
 
193 224
 The top navigation system is currently quite restrictive. There is no way to
@@ -203,11 +234,9 @@ Either way, your site tree should now look something like this:
203 234
 
204 235
 ![](_images/tutorial1_2nd_level-cut.jpg)
205 236
 
206  
-Great, we now have a hierarchical site structure, let's now look at how this is created and displayed in our template.
  237
+Great, we now have a hierarchical site structure! Let's look at how this is created and displayed in our template.
207 238
 
208  
-Adding a second level menu is very similar to adding the first level menu. 
209  
-
210  
-Open up */themes/simple/templates/Includes/Sidebar.ss* template and look at the following code:
  239
+Adding a second level menu is very similar to adding the first level menu. Open up */themes/simple/templates/Includes/Sidebar.ss* template and look at the following code:
211 240
 
212 241
 	:::ss
213 242
 	<ul>
@@ -265,6 +294,7 @@ Breadcrumbs are only useful on pages that aren't in the top level. We can ensure
265 294
 the top level with another if statement.
266 295
 
267 296
 The *Level* page control allows you to get data from the page's parents, e.g. if you used *Level(1)*, you could use:
  297
+	
268 298
 	:::ss
269 299
 	$Level(1).Title 
270 300
 
@@ -301,7 +331,6 @@ The following example runs an if statement, and a loop on *Children*, checking t
301 331
 
302 332
 
303 333
 
304  
-
305 334
 ## Using a different template for the home page
306 335
 
307 336
 So far, a single template layout *Layouts/Page.ss* is being used for the entire site. This is useful for the purpose of this
@@ -339,7 +368,7 @@ Create a new file *HomePage.php* in *mysite/code*. Copy the following code into
339 368
 
340 369
 
341 370
 Every page type also has a database table corresponding to it. Every time we modify the database, we need to rebuild it.
342  
-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). 
  371
+We can do this by going to [http://localhost/your_site_name/dev/build?flush=all](http://localhost/your_site_name/dev/build?flush=1) (replace *localhost/your_site_name* with your own domain name if applicable). 
343 372
 
344 373
 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
345 374
 does this non-destructively - it will never delete your data.
@@ -366,10 +395,13 @@ to the template of the page type's parents.
366 395
 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. 
367 396
 
368 397
 First, remove the breadcrumbs and the secondary menu by removing:
  398
+	:::ss
369 399
 	<% include SideBar %> 
  400
+	
370 401
  we don't need it for the homepage. 
371 402
 
372 403
 Let's replace the title with an image. Find this line:
  404
+
373 405
 	:::ss
374 406
 	<h1>$Title</h1>
375 407
 
@@ -396,7 +428,7 @@ then descend into the *themes/simple/templates/Layout* folder, and will use *Pag
396 428
 
397 429
 ## Summary
398 430
 
399  
-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.
  431
+So far we have taken a look at the different areas and functionality within the pages area of the CMS. We have learnt about template variables, controls and if statements and 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 this knowledge, we have customized our website's homepage design.
400 432
 
401 433
 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.
402 434
 
197  docs/en/tutorials/2-extending-a-basic-site.md
Source Rendered
@@ -3,58 +3,49 @@
3 3
 ## Overview
4 4
 
5 5
 
6  
-In the [first tutorial](1-building-a-basic-site) we learned how to create a basic site using SilverStripe. This
7  
-tutorial builds on what you have learned in [the first tutorial](1-building-a-basic-site), so it is recommended
8  
-that you complete it first. 
9  
-
10  
-In this tutorial you will explore extending SilverStripe by creating your own page types. In doing this you will get a
11  
-good overview of how SilverStripe works.
  6
+In the [first tutorial](1-building-a-basic-site) we learnt how to create a basic site using SilverStripe. This tutorial will build on that, and explore extending SilverStripe by creating our own page types. After doing this we should have a better understanding of how SilverStripe works.
12 7
 
13 8
 ## What are we working towards?
14 9
 
15  
-Throughout this tutorial we are going to work on adding two new sections to the site we built in the first tutorial. The
16  
-first is a news section, with a recent news listing on the homepage and an RSS feed. The second is a staff section,
17  
-which demonstrates more complex database structures by associating an image with each staff member.
  10
+We are going to work on adding two new sections to the site we built in the first tutorial. 
  11
+
  12
+The first of these new sections will be *News*, with a recent news listing on the homepage and an RSS feed: 
18 13
 
19 14
 ![](_images/tutorial2_newslist.jpg)
20 15
 
  16
+
  17
+The second will be a *Staff* section, to demonstrate more complex database structures (such as associating an image with each staff member):
  18
+
21 19
 ![](_images/tutorial2_einstein.jpg)
22 20
 
23 21
 
24 22
 
25 23
 ## The SilverStripe data model
26 24
 
27  
-A large part of designing complex SilverStripe sites is the creation of your own page types. Before we progress any
28  
-further, it is important to understand what a page type is, and how the SilverStripe data model works.
  25
+A large part of designing complex SilverStripe sites is the creation of our own page types. Before we progress any further, it is important to understand what a page type is and how the SilverStripe data model works.
29 26
 
30  
-SilverStripe is based on the **"Model-View-Controller"** design pattern. This means that SilverStripe attempts to separate
31  
-data, logic and presentation as much as possible. Every page has three separate parts which are combined to give you the
  27
+SilverStripe is based on the **"Model-View-Controller"** design pattern. This means that SilverStripe attempts to separate data, logic and presentation as much as possible. Every page has three separate parts which are combined to give you the
32 28
 final page. Lets look at each one individually:
33 29
 
34 30
 ### Model
35 31
 
36  
-All content on your site is stored in a database. There is a table in the database corresponding for every class that is
37  
-a child of the `[api:DataObject]` class. Every object of that class corresponds to a row in that table -
38  
-this is your "data object", the **"model"** of Model-View-Controller. A page type has a data object that represents all the data for your page - rather than inheriting 
39  
-directly from data object it inherits from `[api:SiteTree]`.  We generally create a "Page" data object, and subclass this for 
40  
-the rest of the page types. This allows us to define behavior that is consistent across all pages in our site.
  32
+All content on our site is stored in a database. Each class that is a child of the `[api:DataObject]` class will have its own table in our database. 
  33
+
  34
+Every object of such a class will correspond to a row in that table -
  35
+this is our "data object", the **"model"** of Model-View-Controller. A page type has a data object that represents all the data for our page. Rather than inheriting 
  36
+directly from `[api:DataObject]`, it inherits from `[api:SiteTree]`.  We generally create a "Page" data object, and subclass this for all other page types. This allows us to define behavior that is consistent across all pages in our site.
41 37
 
42 38
 ### View
43 39
 
44  
-The **"view"** is the presentation of your site. As we have already seen, the templates SilverStripe uses to render a page
45  
-is dependent on the page type. Using both your templates and css, you are able to have full control over the
46  
-presentation of your site.
  40
+The **"view"** is the presentation of our site. As we have already seen, the templates SilverStripe uses to render a page are dependent on the page type. Using templates and css, we are able to have full control over the
  41
+presentation of our website.
47 42
 
48 43
 ### Controller
49 44
 
50  
-A page type also has a **"controller"**. A controller contains all the code used to manipulate your data before it is
51  
-rendered. For example, suppose you were making an auction site, and you only wanted to display the auctions closing in
52  
-the next ten minutes. You would implement this in the controller. The controller for a page should inherit from
53  
-`[api:ContentController]`. Just as we create a "Page" data object and subclass it for the rest of the
54  
-site, we also create a "Page_Controller" that is subclassed.
  45
+Each page type also has a **"controller"**. The controller contains all the code used to manipulate our data before it is rendered. For example, suppose we were making an auction site, and we only wanted to display the auctions closing in the next ten minutes. We would implement this logic in the controller. The controller for a page should inherit from `[api:ContentController]`. Just as we create a "Page" data object and subclass it for the rest of the site, we also create a "Page_Controller" that is subclassed.
  46
+
55 47
 
56  
-Creating a new page type simply requires creating these three things. You can then have full control over presentation,
57  
-the database, which fields can be edited in the CMS, and can use code to make our pages do much more clever things. 
  48
+Creating a new page type requires creating each of these three elements. We will then have full control over presentation, the database, and editable CMS fields. 
58 49
 
59 50
 A more in-depth introduction of Model-View-Controller can be found
60 51
 [here](http://www.slash7.com/articles/2005/02/22/mvc-the-most-vexing-conundrum).
@@ -63,13 +54,9 @@ A more in-depth introduction of Model-View-Controller can be found
63 54
 
64 55
 ## Creating the news section page types
65 56
 
66  
-Let's make our news section. We'll need two new page types for this. The first one is obvious: we need an *ArticlePage*
67  
-page type. The second is a little less obvious: we need an *ArticleHolder* page type that contains our articles.
  57
+To create a news section we'll need two new page types. The first one is obvious: we need an *ArticlePage* page type. The second is a little less obvious: we need an *ArticleHolder* page type to contain our article pages.
68 58
 
69  
-We'll start with the *ArticlePage* page type. First we create the model, a class called "ArticlePage". We put the
70  
-*ArticlePage* class into a file called "ArticlePage.php" inside *mysite/code*. We also put the controller,
71  
-*ArticlePage_Controller*, in here. Any other classes that are related to *ArticlePage* – for example, the class
72  
-*ArticlePage_AnythingElse* - will also go into "ArticlePage.php".
  59
+We'll start with the *ArticlePage* page type. First we create the model, a class called "ArticlePage". We put the *ArticlePage* class into a file called "ArticlePage.php" inside *mysite/code*. All other classes relating to *ArticlePage* should be placed within "ArticlePage.php", this includes our controller (*ArticlePage_Controller*). 
73 60
 
74 61
 **mysite/code/ArticlePage.php**
75 62
 
@@ -91,9 +78,7 @@ We'll start with the *ArticlePage* page type. First we create the model, a class
91 78
 	 
92 79
 
93 80
 
94  
-Here we've created our data object/controller pair, but we haven't actually extended them at all. Don't worry about the
95  
-*$db* and *$has_one* arrays just yet, we'll explain them soon, as well as other ways in which you can extend your page
96  
-types. SilverStripe will use the template for the *Page* page type as explained in the first tutorial, so we don't need
  81
+Here we've created our data object/controller pair, but we haven't extended them at all. Don't worry about the *$db* and *$has_one* arrays just yet, we'll explain them shortly. SilverStripe will use the template for the *Page* page type as explained in the first tutorial, so we don't need
97 82
 to specifically create the view for this page type.
98 83
 
99 84
 Let's create the *ArticleHolder* page type.
@@ -119,17 +104,12 @@ Let's create the *ArticleHolder* page type.
119 104
 	}
120 105
 
121 106
 
122  
-Here we have done something interesting: the *$allowed_children* field. This is one of a number of static fields we can
123  
-define to change the properties of a page type. The *$allowed_children* field is an array of page types that are allowed
124  
-to be children of the page in the site tree. As we only want news articles in the news section, we only want
125  
-*ArticlePage* pages for children. We can enforce this in the CMS by setting the *$allowed_children* field.
  107
+Here we have done something interesting: the *$allowed_children* field. This is one of a number of static fields we can define to change the properties of a page type. The *$allowed_children* field is an array of page types that are allowed
  108
+to be children of the page in the site tree. As we only want **news articles** in the news section, we only want pages of the type *ArticlePage* as children. We can enforce this in the CMS by setting the *$allowed_children* field within this class.
126 109
 
127  
-We will be introducing other fields like this as we progress; there is a full list in the documentation for
128  
-`[api:SiteTree]`.
  110
+We will be introduced to other fields like this as we progress; there is a full list in the documentation for `[api:SiteTree]`.
129 111
 
130  
-Now that we have created our page types, we need to let SilverStripe rebuild the database. If we rebuild the database by 
131  
-going to [http://localhost/dev/build?flush=1](http://localhost/dev/build?flush=1), SilverStripe will detect that there are two
132  
-new page types and add them to the list of page types in the database.
  112
+Now that we have created our page types, we need to let SilverStripe rebuild the database: [http://localhost/your_site_name/dev/build?flush=all](http://localhost/your_site_name/dev/build?flush=all). SilverStripe should detect that there are two new page types, and add them to the list of page types in the database.
133 113
 
134 114
 > It is SilverStripe convention to suffix general page types with "Page", and page types that hold other page types with
135 115
 > "Holder". This is to ensure that we don't have URLs with the same name as a page type; if we named our *ArticleHolder*
@@ -139,7 +119,7 @@ new page types and add them to the list of page types in the database.
139 119
 
140 120
 Now that we have an *ArticlePage* page type, let's make it a little more useful. Remember the *$db* array? We can use
141 121
 this array to add extra fields to the database. It would be nice to know when each article was posted, and who posted
142  
-it. Change the *$db* array in the *ArticlePage* class so it looks like this:
  122
+it. Change the *$db* array in the *ArticlePage* class to look like this:
143 123
 
144 124
 	:::php
145 125
 	<?php
@@ -153,17 +133,14 @@ it. Change the *$db* array in the *ArticlePage* class so it looks like this:
153 133
 	}
154 134
 
155 135
 
156  
-Every entry in the array is a key-value pair. The key is the name of the field, and the value is the type. We have a
157  
-`[api:Date]` for a complete list of different data types.
  136
+Every entry in the array is a *key => value* pair. The **key** is the name of the field, and the **value** is the type. See *`[api:Date]`* for a complete list of data types associated with *Date*.
158 137
 
159 138
 > Note: The names chosen for the fields you add must not already be used. Be careful using field names such as Title,
160 139
 > Content etc. as these may already be defined in the page types your new page is extending from.
161 140
 
162  
-If we rebuild the database, we will see that now the *ArticlePage* table is created. Even though we had an *ArticlePage*
163  
-page type before, the table was not created because we had no fields that were unique to the article page type. We now
164  
-have the extra fields in the database, but still no way of changing them. To add these fields to the CMS we have to
165  
-override the *getCMSFields()* method, which is called by the CMS when it creates the form to edit a page. Add the
166  
-method to the *ArticlePage* class.
  141
+When we rebuild the database, we will see that the *ArticlePage* table has been created. Even though we had an *ArticlePage* page type before, a table was not created because there were no fields unique to the article page type. There are now extra fields in the database, but still no way of changing them. 
  142
+
  143
+To add our new fields to the CMS we have to override the *getCMSFields()* method, which is called by the CMS when it creates the form to edit a page. Add the method to the *ArticlePage* class.
167 144
 
168 145
 	:::php
169 146
 	<?php
@@ -201,19 +178,26 @@ returned is a `[api:FieldList]` object.
201 178
 
202 179
 
203 180
 We can then add our new fields with *addFieldToTab*. The first argument is the tab on which we want to add the field to:
204  
-"Root.Main" is the tab which the content editor is on (another is "Root.Metadata". The second argument is the field to add; this is not a database field, but a `[api:FormField]` - see the documentation for more details.
  181
+"Root.Main" is the tab which the content editor is on. The second argument is the field to add; this is not a database field, but a `[api:FormField]` - see the documentation for more details. 
205 182
 
206  
-We add two fields: A simple `[api:TextField}` and a `[api:DateField]`. There are many more FormFields available in the default installation, please refer to [Form Field Types](form-field-types) for the list.
  183
+> Note: By default, the CMS only has one tab. Creating new tabs is much like adding to existing tabs. For instance:
  184
+
  185
+>	$fields->addFieldToTab('Root.NewTab', new TextField('Author'));
  186
+
  187
+> would create a new tab called "New Tab", and a single "Author" textfield inside.
  188
+
  189
+
  190
+
  191
+We have added two fields: A simple `[api:TextField]` and a `[api:DateField]`.   
  192
+There are many more FormFields available in the default installation, please refer to [Form Field Types](form-field-types) for the list.
207 193
 
208 194
 	:::php
209 195
 	return $fields;
210 196
 
211 197
 
212  
-Finally, we return the fields to the CMS. If we flush the cache (by adding ?flush=1 at the end of the URL), we will be able
213  
-to edit the fields in the CMS.
  198
+Finally, we return the fields to the CMS. If we flush the cache (by adding ?flush=all at the end of the URL), we will be able to edit the fields in the CMS.
214 199
 
215  
-Now that we have created our page types, let's add some content. Go into the CMS and create an *ArticleHolder* page
216  
-named "News", and create some *ArticlePage*s inside it.
  200
+Now that we have created our page types, let's add some content. Go into the CMS and create an *ArticleHolder* page named "News", then create a few *ArticlePage*'s within it.
217 201
 
218 202
 ![](_images/tutorial2_news-cms.jpg)
219 203
 
@@ -259,24 +243,22 @@ Set *showCalendar* to true to have a calendar appear underneath the Date field w
259 243
 	:::php
260 244
 	$dateField->setConfig('dateformat', 'dd/MM/YYYY');
261 245
 
262  
-*dateFormat* allows you to specify how you wish the date to be entered and displayed in the CMS field.
  246
+*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 details of the DateField configuration.
263 247
 
264 248
 	:::php
265 249
 	$fields->addFieldToTab('Root.Content', new TextField('Author','Author Name'), 'Content');
266 250
 
267  
-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,
268  
-add the new title as the second argument. See the `[api:DateField]` documentation for more details of the DateField configuration.
  251
+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.
269 252
 
270 253
 
271 254
 ##  Creating the templates
272 255
 
273  
-We can already look at the content of news pages on our site, because the article holder page and the article pages
274  
-inherit their templates from Page. But we're not getting the author and date fields displayed in either case.
  256
+Because our new pages inherit their templates from *Page*, we can view anything entered in the content area when navigating to these pages on our site. However, as there is no reference to the date or author fields in the *Page* template this data is not being displayed.
275 257
 
276  
-So let's create a template for each of our new page types. We'll put these in *themes/tutorial/templates/Layout* so we
277  
-only have to define the page specific parts: SilverStripe will use *themes/tutorial/templates/Page.ss* for the basic
  258
+To fix this we will create a template for each of our new page types. We'll put these in *themes/tutorial/templates/Layout* so we only have to define the page specific parts: SilverStripe will use *themes/tutorial/templates/Page.ss* for the basic
278 259
 page layout.
279 260
 
  261
+###ArticlePage Template
280 262
 First, the template for displaying a single article:
281 263
 
282 264
 **themes/simple/templates/Layout/ArticlePage.ss**
@@ -299,13 +281,9 @@ First, the template for displaying a single article:
299 281
 
300 282
 Most of the code is just like the regular Page.ss, we include an informational div with the date and the author of the Article.
301 283
 
302  
-We use *$Date* and *$Author* to access the new fields. In fact, all template variables and page controls come from
303  
-either the data object or the controller for the page being displayed. The *$Title* variable comes from the
304  
-*Title* field of the `[api:SiteTree]` class. *$Date* and *$Author* come from the *ArticlePage* table through
305  
-your custom Page. *$Content* comes from the *SiteTree* table through the same data object. The data for your page is
  284
+To access the new fields, we use *$Date* and *$Author*. In fact, all template variables and page controls come from either the data object or the controller for the page being displayed. The *$Title* variable comes from the *Title* field of the `[api:SiteTree]` class. *$Date* and *$Author* come from the *ArticlePage* table through your custom Page. *$Content* comes from the *SiteTree* table through the same data object. The data for your page is
306 285
 spread across several tables in the database matched by id - e.g. *Content* is in the *SiteTree* table, and *Date* and
307  
-*Author* are in the *ArticlePage* table. SilverStripe matches these records by their ids and collates them into the single
308  
-data object.
  286
+*Author* are in the *ArticlePage* table. SilverStripe matches this data, and collates it into a single data object.
309 287
 
310 288
 ![](_images/tutorial2_data-collation.jpg)
311 289
 
@@ -315,8 +293,8 @@ database.
315 293
 
316 294
 ![](_images/tutorial2_news.jpg)
317 295
 
318  
-Now we'll create a template for the article holder: we want our news section to show a list of news items, each with a
319  
-summary.
  296
+###ArticleHolder Template
  297
+We'll now create a template for the article holder. We want our news section to show a list of news items, each with a summary and a link to the main article (our Article Page).
320 298
 
321 299
 **themes/simple/templates/Layout/ArticleHolder.ss**
322 300
 
@@ -339,22 +317,18 @@ summary.
339 317
 	<% include SideBar %>
340 318
 
341 319
 
342  
-Here we use the page control *Children*. As the name suggests, this control allows you to iterate over the children of a
343  
-page, which in this case is our news articles. The *$Link* variable will give the address of the article which we can
344  
-use to create a link, and the *FirstParagraph* function of the `[api:HTMLText]` field gives us a nice summary of the
345  
-article. The function strips all tags from the paragraph extracted.
  320
+Here we use the page control *Children*. As the name suggests, this control allows you to iterate over the children of a page. In this case, the children are our news articles. The *$Link* variable will give the address of the article which we can use to create a link, and the *FirstParagraph* function of the `[api:HTMLText]` field gives us a nice summary of the article. The function strips all tags from the paragraph extracted.
346 321
 
347 322
 ![](_images/tutorial2_articleholder.jpg)
348 323
 
349 324
 
350 325
 ### Using include files in templates
351 326
 
352  
-You can make your templates more modular and easier to maintain by separating commonly-used pieces into include files. 
353  
-You are already familiar with the `<% include Sidebar %>`-Line for the menu.
  327
+We can make our templates more modular and easier to maintain by separating commonly-used components in to *include files*.  We are already familiar with the `<% include Sidebar %>` line from looking at the menu in the [first tutorial](1-building-a-basic-site).
354 328
 
355 329
 We'll separate the display of linked articles as we want to reuse this code later on.
356 330
 
357  
-Replace the code in *ArticleHolder.ss** with an include statement:
  331
+Cut the code in *ArticleHolder.ss** and replace it with an include statement:
358 332
 
359 333
 **themes/simple/templates/Layout/ArticleHolder.ss**
360 334
 
@@ -365,7 +339,7 @@ Replace the code in *ArticleHolder.ss** with an include statement:
365 339
 	<% end_loop %>
366 340
 	...
367 341
 
368  
-and paste the code in a new include snippet:
  342
+Paste the code that was in ArticleHolder into a new include file called ArticleTeaser.ss:
369 343
 
370 344
 **themes/simple/templates/Includes/ArticleTeaser.ss**
371 345
 
@@ -397,9 +371,7 @@ This will change the icons for the pages in the CMS.
397 371
 
398 372
 ## Showing the latest news on the homepage
399 373
 
400  
-It would be nice to greet page visitors with a summary of the latest news when they visit the homepage. This requires a
401  
-little more code though - the news articles are not direct children of the homepage, so we can't use the *Children*
402  
-control. We can get the data for the news articles by implementing our own function in *HomePage_Controller*.
  374
+It would be nice to greet page visitors with a summary of the latest news when they visit the homepage. This requires a little more code though - the news articles are not direct children of the homepage, so we can't use the *Children* control. We can get the data for news articles by implementing our own function in *HomePage_Controller*.
403 375
 
404 376
 **mysite/code/HomePage.php**
405 377
 
@@ -412,9 +384,7 @@ control. We can get the data for the news articles by implementing our own funct
412 384
 	...
413 385
 
414 386
 
415  
-This function simply runs a database query that gets the latest news articles from the database. By default, this is
416  
-five, but you can change it by passing a number to the function. See the [Data Model](../topics/datamodel) documentation for
417  
-details. We can reference this function as a page control in our *HomePage* template:
  387
+This function simply runs a database query that gets the latest news articles from the database. By default, this is five, but you can change it by passing a number to the function. See the [Data Model](../topics/datamodel) documentation for details. We can reference this function as a page control in our *HomePage* template:
418 388
 
419 389
 **themes/tutorial/templates/Layout/Homepage.ss**
420 390
 
@@ -428,14 +398,9 @@ details. We can reference this function as a page control in our *HomePage* temp
428 398
 	...
429 399
 
430 400
 
431  
-When SilverStripe comes across a variable or page control it doesn't recognize, it first passes control to the
432  
-controller. If the controller doesn't have a function for the variable or page control, it then passes control to the
433  
-data object. If it has no matching functions, it then searches its database fields. Failing that it will return nothing.
  401
+When SilverStripe comes across a variable or page control it doesn't recognize, it first passes control to the controller. If the controller doesn't have a function for the variable or page control, it then passes control to the data object. If it has no matching functions, it then searches its database fields. Failing that it will return nothing.
434 402
 
435  
-The controller for a page is only created when page is actually visited, while the data object is available when the
436  
-page is referenced in other pages, e.g. by page controls. A good rule of thumb is to put all functions specific to the
437  
-page currently being viewed in the controller; only if a function needs to be used in another page should you put it in
438  
-the data object.
  403
+The controller for a page is only created when page is actually visited, while the data object is available when the page is referenced in other pages, e.g. by page controls. A good rule of thumb is to put all functions specific to the page currently being viewed in the controller; only if a function needs to be used in another page should you put it in the data object.
439 404
 
440 405
 ![](_images/tutorial2_homepage-news.jpg)
441 406
 
@@ -443,8 +408,7 @@ the data object.
443 408
 
444 409
 ## Creating a RSS feed
445 410
 
446  
-An RSS feed is something that no news section should be without. SilverStripe makes it easy to create RSS feeds by
447  
-providing an `[api:RSSFeed]` class to do all the hard work for you. Create the following function in the
  411
+An RSS feed is something that no news section should be without. SilverStripe makes it easy to create RSS feeds by providing an `[api:RSSFeed]` class to do all the hard work for us. Create the following function in the
448 412
 *ArticleHolder_Controller*:
449 413
 
450 414
 	:::php
@@ -454,18 +418,13 @@ providing an `[api:RSSFeed]` class to do all the hard work for you. Create the f
454 418
 	}
455 419
 
456 420
 
457  
-This function simply creates an RSS feed of all the news articles, and outputs it to the browser. If you go to
458  
-[http://localhost/news/rss](http://localhost/news/rss) you will see our RSS feed. What happens here is that
459  
-when there is more to a URL after the page's base URL - "rss" in this case - SilverStripe will call the function with
460  
-that name on the controller if it exists.
  421
+This function creates an RSS feed of all the news articles, and outputs it to the browser. If we go to [http://localhost/your_site_name/news/rss](http://localhost/your_site_name/news/rss) we should see our RSS feed. When there is more to a URL after a page's base URL, "rss" in this case, SilverStripe will call the function with that name on the controller if it exists.
461 422
 
462  
-Depending on your browser, you should see something like the picture below. If your browser doesn't support RSS, you
463  
-will most likely see the XML output instead.
  423
+Depending on your browser, you should see something like the picture below. If your browser doesn't support RSS, you will most likely see the XML output instead. For more on RSS, see `[api:RSSFeed]`
464 424
 
465 425
 ![](_images/tutorial2_rss-feed.jpg)
466 426
 
467  
-Now all we need is to let the user know that our RSS feed exists. The `[api:RSSFeed]` in your controller, it will be
468  
-called when the page is requested. Add this function to *ArticleHolder_Controller*:
  427
+Now all we need is to let the user know that our RSS feed exists. Add this function to *ArticleHolder_Controller*:
469 428
 
470 429
 	:::php
471 430
 	public function init() {
@@ -474,17 +433,11 @@ called when the page is requested. Add this function to *ArticleHolder_Controlle
474 433
 	}
475 434
 
476 435
 
477  
-This automatically generates a link-tag in the header of our template. The *init* function is then called on the parent
478  
-class to ensure any initialization the parent would have done if we hadn't overridden the *init* function is still
479  
-called. Depending on your browser, you can see the RSS feed link in the address bar:
480  
-
481  
-![](_images/tutorial2_rss.jpg)
  436
+This automatically generates a link-tag in the header of our template. The *init* function is then called on the parent class to ensure any initialization the parent would have done if we hadn't overridden the *init* function is still called. Depending on your browser, you can see the RSS feed link in the address bar.
482 437
 
483 438
 ## Adding a staff section
484 439
 
485  
-Now that we have a complete news section, let's move on to the staff section. We need to create *StaffHolder* and
486  
-*StaffPage* page types, for an overview on all staff members and a detail-view for a single member. First let's start
487  
-with the *StaffHolder* page type.
  440
+Now that we have a complete news section, let's take a look at the staff section. We need to create *StaffHolder* and *StaffPage* page types, for an overview on all staff members and a detail-view for a single member. First let's start with the *StaffHolder* page type.
488 441
 
489 442
 **mysite/code/StaffHolder.php**
490 443
 
@@ -505,9 +458,7 @@ with the *StaffHolder* page type.
505 458
 	}
506 459
 
507 460
 
508  
-Nothing here should be new. The *StaffPage* page type is more interesting though. Each staff member has a portrait
509  
-image. We want to make a permanent connection between this image and the specific *StaffPage* (otherwise we could simply
510  
-insert an image in the *$Content* field).
  461
+Nothing here should be new. The *StaffPage* page type is more interesting though. Each staff member has a portrait image. We want to make a permanent connection between this image and the specific *StaffPage* (otherwise we could simply insert an image in the *$Content* field).
511 462
 
512 463
 **mysite/code/StaffPage.php**
513 464
 
@@ -535,10 +486,7 @@ insert an image in the *$Content* field).
535 486
 	}
536 487
 
537 488
 
538  
-Instead of adding our *Image* as a field in *$db*, we have used the *$has_one* array. This is because an *Image* is not
539  
-a simple database field like all the fields we have seen so far, but has its own database table. By using the *$has_one*
540  
-array, we create a relationship between the *StaffPage* table and the *Image* table by storing the id of the respective
541  
-*Image* in the *StaffPage* table.
  489
+Instead of adding our *Image* as a field in *$db*, we have used the *$has_one* array. This is because an *Image* is not a simple database field like all the fields we have seen so far, but has its own database table. By using the *$has_one* array, we create a relationship between the *StaffPage* table and the *Image* table by storing the id of the respective *Image* in the *StaffPage* table.
542 490
 
543 491
 We then add an `[api:UploadField]` in the *getCMSFields* function to the tab "Root.Images". Since this tab doesn't exist,
544 492
 the *addFieldToTab* function will create it for us. The *UploadField* allows us to select an image or upload a new one in
@@ -546,7 +494,7 @@ the CMS.
546 494
 
547 495
 ![](_images/tutorial2_photo.jpg)
548 496
 
549  
-Rebuild the database ([http://localhost/dev/build?flush=1](http://localhost/dev/build?flush=1)) and open the CMS. Create
  497
+Rebuild the database ([http://localhost/your_site_name/dev/build?flush=1](http://localhost/your_site_name/dev/build?flush=1)) and open the CMS. Create
550 498
 a new *StaffHolder* called "Staff", and create some *StaffPage*s in it.
551 499
 
552 500
 ![](_images/tutorial2_create-staff.jpg)
@@ -601,14 +549,13 @@ The *StaffPage* template is also very straight forward.
601 549
 	</div>
602 550
 	<% include SideBar %>
603 551
 
604  
-Here we also use the *SetWidth* function to get a different sized image from the same source image. You should now have
  552
+Here we use the *SetWidth* method to get a different sized image from the same source image. You should now have
605 553
 a complete staff section.
606 554
 
607 555
 ![](_images/tutorial2_einstein.jpg)
608 556
 
609 557
 ## Summary
610 558
 
611  
-In this tutorial we have explored the concept of page types. In the process of creating and extending page types you
612  
-have been introduced to many of the concepts required to build a site with SilverStripe.
  559
+In this tutorial we have explored the concept of page types. In the process of creating and extending page types we have covered many of the concepts required to build a site with SilverStripe.
613 560
 
614 561
 [Next Tutorial >>](3-forms)
BIN  docs/en/tutorials/_images/tutorial2_create-staff.jpg
BIN  docs/en/tutorials/_images/tutorial2_icons2.jpg
BIN  docs/en/tutorials/_images/tutorial2_photo.jpg

0 notes on commit 14753e9

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