Skip to content
This repository
Browse code

Proof reading tutorials 1 and 2

  • Loading branch information...
commit 3ef394c448260abe2cbfa675212711c74d0135c5 1 parent aa8dfd1
Ingo Schommer authored
75  docs/en/tutorials/1-building-a-basic-site.md
Source Rendered
@@ -70,8 +70,8 @@ with the editor - try different formatting, tables and images. When you are done
70 70
 & Publish" to post the content to the live site. 
71 71
 
72 72
 ### New pages
73  
-To create a new page, click the add new button above the site tree.  
74  
-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. 
  73
+To create a new page, click the "Add New" button above the site tree.  
  74
+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. 
75 75
 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".
76 76
 
77 77
 ![](_images/tutorial1_addpage.jpg)
@@ -91,12 +91,13 @@ become *about-us*. You are able to change it yourself so that you can make long
91 91
 example, *Employment Opportunities* could be shortened to *jobs*. The ability to generate easy to type, descriptive URLs
92 92
 for SilverStripe pages improves accessibility for humans and search engines.
93 93
 
94  
-You should ensure the URL for the home page is *home*. By default, SilverStripe loads the page with the URL *home*.
  94
+You should ensure the URL for the home page is *home*, as that's the page SilverStripe loads by default.
95 95
 
96 96
 
97 97
 ## Templates
98 98
 
99  
-All pages on a SilverStripe site are rendered using a template. A template is an HTML file augmented with special
  99
+All pages on a SilverStripe site are rendered using a template. A template is an file 
  100
+with a special `*.ss` file extension, containing HTML augmented with some
100 101
 control codes. Because of this, you can have as much control of your site’s HTML code as you like.
101 102
 
102 103
 Every page in your site has a **page type**. We will briefly talk about page types later, and go into much more detail
@@ -116,7 +117,7 @@ ensures the browser knows where to locate your site's images and css files.
116 117
 	$Title
117 118
 	$SiteConfig.Title
118 119
 
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
+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
 	
121 122
 	:::ss
122 123
 	$MetaTags 
@@ -136,7 +137,8 @@ The Content variable is replaced with the content of the page currently being vi
136 137
 your site's content in the CMS.
137 138
 
138 139
 These template markers are processed by SilverStripe into HTML before being sent to your
139  
-browser and are formatted either with a *$* at the beginning or are between the SilverStripe template tags: 
  140
+browser and are either prefixed with a dollar sign ($)
  141
+or placed between SilverStripe template tags: 
140 142
 
141 143
 	:::ss
142 144
 	<%  %>
@@ -185,39 +187,23 @@ This creates the navigation at the top of the page:
185 187
 
186 188
 ### Highlighting the current page
187 189
 
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:
  190
+A useful feature is highlighting the current page the user is looking at. We can do this with the template variable: `$LinkingMode`. It returns one of three values:
193 191
 
194 192
 *  *current* - This page is being visited
195 193
 *  *link* - This page is not currently being visited
196 194
 *  *section* - A page under this page is being visited
197 195
 
198  
-> 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:
  196
+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:
  197
+
199 198
 	:::ss
200 199
 	<li class="$LinkingMode">
201 200
 	 	<a href="$Link" title="$Title.XML">$MenuTitle.XML</a>
202 201
 	</li>
203 202
 
204  
-you will then be able to target a section in css (*simple/css/layout.css*), ie: 
  203
+you will then be able to target a section in css (*simple/css/layout.css*), e.g.:
  204
+
205 205
 	:::css
206  
-	.section { 
207  
-		background:#ccc;
208  
-	} 
209  
-You may also style the link to the current page this way, eg:
210  
-	:::css	
211  
-	.current { 
212  
-		/* Your styles here */
213  
-	} 
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  
-	} 
  206
+	.section { background:#ccc; } 
221 207
 
222 208
 ## A second level of navigation
223 209
 
@@ -344,26 +330,16 @@ banner to welcome visitors.
344 330
 Earlier we stated that every page in a SilverStripe site has a **page type**, and that SilverStripe will look for a
345 331
 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.
346 332
 
347  
-Each page type is represented by two php classes: a *data object* and a *controller*. Don't worry about the details of page
348  
-types right now, we will go into much more detail in tutorial two.
  333
+Each page type is represented by two PHP classes: a *data object* and a *controller*. Don't worry about the details of page
  334
+types right now, we will go into much more detail in the [next tutorial](2-extending-a-basic-site).
349 335
 
350 336
 Create a new file *HomePage.php* in *mysite/code*. Copy the following code into it:
351 337
 
352 338
 	:::php
353 339
 	<?php
354  
-	/**
355  
-	 * Defines the HomePage page type
356  
-	 */
357  
-	
358 340
 	class HomePage extends Page {
359  
-	   static $db = array(
360  
-	   );
361  
-	   static $has_one = array(
362  
-	   );
363 341
 	}
364  
-	
365 342
 	class HomePage_Controller extends Page_Controller {
366  
-		
367 343
 	}
368 344
 
369 345
 
@@ -383,24 +359,21 @@ In the CMS, navigate to the "Home" page and switch to the "Settings" tab. Change
383 359
 
384 360
 ![](_images/tutorial1_homepage-type.jpg)
385 361
 
386  
-Our homepage is now of the page type *HomePage*. However, even though it is of the *HomePage* page type, it is still
387  
-rendered with the *Page* template. SilverStripe still renders the homepage using the *Page* template because when we
388  
-created the *HomePage* page type, we inherited from *Page*. So when SilverStripe cannot find a *HomePage* template, it
389  
-will use the *Page* template. SilverStripe always attempts to use the most specific template first, and then falls back
390  
-to the template of the page type's parents.
  362
+Our homepage is now of the page type *HomePage*. Regardless, it is still
  363
+rendered with the *Page* template. SilverStripe does this the type inherits from *Page*,
  364
+which acts as a fallback if no *HomePage* template can be found. 
  365
+It always tries to use the most specific template in an inheritance chain.
391 366
 
392 367
 
393 368
 ### Creating a new template
394 369
 
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. 
  370
+To create a new template layout, create a copy of *Page.ss* (found in *themes/simple/templates/Layout*) 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. 
396 371
 
397  
-First, remove the breadcrumbs and the secondary menu by removing:
  372
+First, we don't need the breadcrumbs and the secondary menu for the homepage. Let's remove them:
398 373
 	:::ss
399 374
 	<% include SideBar %> 
400 375
 	
401  
- we don't need it for the homepage. 
402  
-
403  
-Let's replace the title with an image. Find this line:
  376
+We'll also replace the title text with an image. Find this line:
404 377
 
405 378
 	:::ss
406 379
 	<h1>$Title</h1>
@@ -432,7 +405,7 @@ So far we have taken a look at the different areas and functionality within the
432 405
 
433 406
 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.
434 407
 
435  
-[Next Tutorial >>](2-extending-a-basic-site)
  408
+[Next tutorial >>](2-extending-a-basic-site)
436 409
 
437 410
 ## Books on SilverStripe 
438 411
 
58  docs/en/tutorials/2-extending-a-basic-site.md
Source Rendered
@@ -62,18 +62,9 @@ We'll start with the *ArticlePage* page type. First we create the model, a class
62 62
 
63 63
 	:::php
64 64
 	<?php
65  
-	/**
66  
-	 * Defines the ArticlePage page type
67  
-	 */
68 65
 	class ArticlePage extends Page {
69  
-		static $db = array(
70  
-		);
71  
-		static $has_one = array(
72  
-		);
73 66
 	}
74  
-	
75 67
 	class ArticlePage_Controller extends Page_Controller {
76  
-		
77 68
 	}
78 69
 	 
79 70
 
@@ -87,20 +78,10 @@ Let's create the *ArticleHolder* page type.
87 78
 
88 79
 	:::php
89 80
 	<?php
90  
-	/**
91  
-	 * Defines the ArticleHolder page type
92  
-	 */
93 81
 	class ArticleHolder extends Page {
94  
-		static $db = array(
95  
-		);
96  
-		static $has_one = array(
97  
-		);
98  
-	   
99 82
 		static $allowed_children = array('ArticlePage');
100 83
 	}
101  
-	 
102 84
 	class ArticleHolder_Controller extends Page_Controller {
103  
-		
104 85
 	}
105 86
 
106 87
 
@@ -111,15 +92,17 @@ We will be introduced to other fields like this as we progress; there is a full
111 92
 
112 93
 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.
113 94
 
114  
-> It is SilverStripe convention to suffix general page types with "Page", and page types that hold other page types with
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*
116  
-> page type "News", it would conflict with the page name also called "News".
  95
+<div class="hint" markdown="1">
  96
+It is SilverStripe convention to suffix general page types with "Page", and page types that hold other page types with
  97
+"Holder". This is to ensure that we don't have URLs with the same name as a page type; if we named our *ArticleHolder*
  98
+page type "News", it would conflict with the page name also called "News".
  99
+</div>
117 100
 
118 101
 ## Adding date and author fields
119 102
 
120 103
 Now that we have an *ArticlePage* page type, let's make it a little more useful. Remember the *$db* array? We can use
121 104
 this array to add extra fields to the database. It would be nice to know when each article was posted, and who posted
122  
-it. Change the *$db* array in the *ArticlePage* class to look like this:
  105
+it. Add a *$db* property definition in the *ArticlePage* class:
123 106
 
124 107
 	:::php
125 108
 	<?php
@@ -133,10 +116,12 @@ it. Change the *$db* array in the *ArticlePage* class to look like this:
133 116
 	}
134 117
 
135 118
 
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*.
  119
+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 ["data types"](/topics/data-types) for a complete list of types.
137 120
 
138  
-> Note: The names chosen for the fields you add must not already be used. Be careful using field names such as Title,
139  
-> Content etc. as these may already be defined in the page types your new page is extending from.
  121
+<div class="hint" markdown="1">
  122
+The names chosen for the fields you add must not already be used. Be careful using field names such as Title,
  123
+Content etc. as these may already be defined in the page types your new page is extending from.
  124
+</div>
140 125
 
141 126
 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 127
 
@@ -180,16 +165,13 @@ returned is a `[api:FieldList]` object.
180 165
 We can then add our new fields with *addFieldToTab*. The first argument is the tab on which we want to add the field to:
181 166
 "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. 
182 167
 
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  
-
  168
+<div class="hint" markdown="1">
  169
+Note: By default, the CMS only has one tab. Creating new tabs is much like adding to existing tabs. For instance: `$fields->addFieldToTab('Root.NewTab', new TextField('Author'));`
  170
+would create a new tab called "New Tab", and a single "Author" textfield inside.
  171
+</div>
190 172
 
191 173
 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.
  174
+There are many more fields available in the default installation, listed in ["form field types"](/reference/form-field-types).
193 175
 
194 176
 	:::php
195 177
 	return $fields;
@@ -238,12 +220,12 @@ Let's walk through these changes.
238 220
 	:::php
239 221
 	$dateField->setConfig('showcalendar', true);
240 222
 
241  
-Set *showCalendar* to true to have a calendar appear underneath the Date field when you click on the field. 
  223
+By enabling *showCalendar* you show a calendar overlay when clicking on the field. 
242 224
 
243 225
 	:::php
244 226
 	$dateField->setConfig('dateformat', 'dd/MM/YYYY');
245 227
 
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.
  228
+*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.
247 229
 
248 230
 	:::php
249 231
 	$fields->addFieldToTab('Root.Content', new TextField('Author','Author Name'), 'Content');
@@ -258,7 +240,7 @@ Because our new pages inherit their templates from *Page*, we can view anything
258 240
 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
259 241
 page layout.
260 242
 
261  
-###ArticlePage Template
  243
+### ArticlePage Template
262 244
 First, the template for displaying a single article:
263 245
 
264 246
 **themes/simple/templates/Layout/ArticlePage.ss**
@@ -274,7 +256,6 @@ First, the template for displaying a single article:
274 256
 			<div class="content">$Content</div>
275 257
 		</article>
276 258
 			$Form
277  
-			$PageComments
278 259
 	</div>
279 260
 	<% include SideBar %>
280 261
 
@@ -545,7 +526,6 @@ The *StaffPage* template is also very straight forward.
545 526
 				$Content</div>
546 527
 		</article>
547 528
 			$Form
548  
-			$PageComments
549 529
 	</div>
550 530
 	<% include SideBar %>
551 531
 

0 notes on commit 3ef394c

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