Skip to content
This repository
Browse code

MINOR: Documentation, tutorial (part1)

  • Loading branch information...
commit 2c024e444c744d7864bc35615d37f76e9411114e 1 parent fc98c68
Naomi Guyer authored
179  docs/en/tutorials/1-building-a-basic-site.md
Source Rendered
@@ -4,8 +4,7 @@
4 4
 
5 5
 Welcome to the first in this series of tutorials on the SilverStripe Content Management System (CMS). 
6 6
 
7  
-These tutorials are designed to take you from an absolute beginner to being able to build large, complex websites with
8  
-SilverStripe. We assume to begin with, that you have some XHTML, CSS and PHP knowledge. This first tutorial provides an absolute
  7
+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
9 8
 introduction to building a simple website using SilverStripe. It will also teach you how to use the content management system at a basic level.
10 9
 
11 10
 ##  What are we working towards?
@@ -16,8 +15,7 @@ templates - one for the home page, and one for the rest of the site.
16 15
 
17 16
 ##  Installation
18 17
 
19  
-You need to [download the SilverStripe software](http://www.silverstripe.org/stable-download) and install it to your local
20  
-machine or to a webserver. 
  18
+You need to [download the SilverStripe software](http://www.silverstripe.org/stable-download) and install it to your local machine or to a webserver. 
21 19
 
22 20
 For more infomation about installing and configuring a webserver read the [Installation instructions and videos](../installation). 
23 21
 
@@ -27,7 +25,7 @@ This tutorial uses the SilverStripe CMS default theme 'Simple' which you will fi
27 25
 
28 26
 After installation, open up the folder where you installed SilverStripe. 
29 27
 
30  
-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/*
  28
+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/*)
31 29
 
32 30
 Let's have a look at the folder structure.
33 31
 
@@ -36,8 +34,8 @@ Let's have a look at the folder structure.
36 34
  | 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. | 
37 35
  | 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. | 
38 36
  | 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.                                                             | 
39  
- | mysite/   | | Contains all your sites code (mainly PHP and JavaScript)  | 
40  
- | themes/   | | Combines all images, stylesheets and templates powering your website into a reusable "theme" | 
  37
+ | mysite/   | | Contains all your sites code (mainly PHP)  | 
  38
+ | themes/   | | Combines all images, stylesheets, javascript and templates powering your website into a reusable "theme" | 
41 39
       
42 40
 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.
43 41
 
@@ -47,43 +45,34 @@ When designing your site you should only need to modify the *mysite*, *themes* a
47 45
 
48 46
 ![](_images/tutorial1_cms-basic.jpg)
49 47
 
50  
-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
51  
-will be presented with a login screen. You can login with the details you provided at installation. After logging in you
52  
-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).
  48
+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
  49
+will be presented with a login screen. Login using the details you provided at installation. After logging in you
  50
+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).
53 51
 
54 52
 ![](_images/tutorial1_cms-numbered.jpg)
55 53
 
56  
-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.
57  
-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.
58  
-
59  
-![](_images/tutorial1_cms-numbered-2b.jpg)
60  
-
61  
-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.
62  
-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. 
63  
-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.
64  
-
65  
-### Page Editor
66  
-
67  
-Once you have selected a page to modify from the Pages section your page will open in the Page Editior. 
68  
-
69  
-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).
70  
-
71  
-![](_images/tutorial1_editpage-numbered.jpg)
72  
-
73  
-1.  *Content* - Allows you to set the title, wysiwyg content, URL and Meta data for your page.
74  
-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.
75  
-3.  *History* - This allow you to view previous version of your page, compare change and revert to previous version if need be.
  54
+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.
  55
+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". 
  56
+ * Content - Allows you to set the title, wysiwyg content, URL and Meta data for your page.  
  57
+ * 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.  
  58
+ * History - This allows you to view previous version of your page, compare change and revert to previous version if need be.  
  59
+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.  
  60
+![](_images/tutorial1_cms-numbered-3.jpg)  
  61
+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.
  62
+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.
76 63
 
  64
+![](_images/tutorial1_cms-numbered-5.jpg)  
77 65
 
78 66
 ### Try it
79 67
 
80 68
 There are three pages already created for you - "Home", "About Us" and "Contact Us", as well as a 404 page. Experiment
81  
-with the editor - try different formatting, tables and images. When you are done, click "Save" to save the page or "Save
  69
+with the editor - try different formatting, tables and images. When you are done, click "Save Draft" or "Save
82 70
 & Publish" to post the content to the live site. 
83 71
 
84  
-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. 
85  
-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
86  
-behavior. We will explain page types in more depth as we progress; for now, make all pages of the type "Page".
  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. 
  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".
87 76
 
88 77
 ![](_images/tutorial1_addpage.jpg)
89 78
 
@@ -139,8 +128,8 @@ browser and are formatted either with a *$* at the beginning or are between the
139 128
 
140 129
 **Flushing the cache**
141 130
 
142  
-Whenever we edit a template file, we need to append *?flush=1* onto the end of the URL, e.g.
143  
-http://localhost/home/?flush=1. SilverStripe stores template files in a cache for quicker load times. Whenever there are
  131
+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
144 133
 changes to the template, we must flush the cache in order for the changes to take effect.
145 134
 
146 135
 ##  The Navigation System
@@ -158,7 +147,9 @@ Menu for our site are created using a **loop**. Loops allow us to iterate over a
158 147
 	:::ss
159 148
 	<ul>
160 149
 		<% loop Menu(1) %>	  
161  
-			<li class="$LinkingMode"><a href="$Link" title="$Title.XML">$MenuTitle.XML</a></li>
  150
+			<li class="$LinkingMode">
  151
+				<a href="$Link" title="$Title.XML">$MenuTitle.XML</a>
  152
+			</li>
162 153
 		<% end_loop %>
163 154
 	</ul>
164 155
 
@@ -171,20 +162,31 @@ This creates the navigation at the top of the page:
171 162
 
172 163
 
173 164
 
174  
-## Highlighting the current page
  165
+### Highlighting the current page
175 166
 
176 167
 A useful feature is highlighting the current page the user is looking at. We can do this with the template variable
177  
-*$LinkingMode* which we mentioned before. *$LinkingMode* returns one of three values:
178  
-
179  
-*  *current* - This page is being visited, and should be highlighted
180  
-*  *link* - The page is not currently being visited, so shouldn't be highlighted
181  
-*  *section* - A page under this page is being visited so you probably want to highlight it.
  168
+*$LinkingMode*, mentioned earlier. *$LinkingMode* returns one of three values:
182 169
 
183  
-> 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.
  170
+*  *current* - This page is being visited
  171
+*  *link* - This page is not currently being visited
  172
+*  *section* - A page under this page is being visited
184 173
 
185  
-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*. 
  174
+> 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:
  175
+	:::ss
  176
+	<li class="$LinkingMode">
  177
+	 	<a href="$Link" title="$Title.XML">$MenuTitle.XML</a>
  178
+	</li>
186 179
 
187  
-![](_images/tutorial1_menu-highlighted.jpg)
  180
+you will then be able to target a section in css (*simple/css/layout.css*), ie: 
  181
+	:::ss
  182
+	.section { 
  183
+		background:#ccc;
  184
+	} 
  185
+You may also style the link to the current page this way, eg:
  186
+	:::ss	
  187
+	.current { 
  188
+		/* Your styles here */
  189
+	} 
188 190
 
189 191
 ## A second level of navigation
190 192
 
@@ -210,7 +212,12 @@ Open up */themes/simple/templates/Includes/Sidebar.ss* template and look at the
210 212
 	:::ss
211 213
 	<ul>
212 214
 	  <% loop Menu(2) %>
213  
-	    <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>
  215
+	    <li class="$LinkingMode">
  216
+		    <a href="$Link" title="Go to the $Title.XML page">
  217
+		    	<span class="arrow">&rarr;</span>
  218
+		    	<span class="text">$MenuTitle.XML</span>
  219
+		    </a>
  220
+	    </li>
214 221
 	  <% end_loop %>
215 222
 	</ul>
216 223
 
@@ -228,7 +235,12 @@ like this:
228 235
 		...
229 236
 			<ul>
230 237
 				<% loop Menu(2) %>
231  
-				<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>
  238
+				<li class="$LinkingMode">
  239
+					<a href="$Link" title="Go to the $Title.XML page">
  240
+						<span class="arrow">&rarr;</span>
  241
+						<span class="text">$MenuTitle.XML</span>
  242
+					</a>
  243
+				</li>
232 244
 				<% end_loop %>
233 245
 			</ul>
234 246
 		...
@@ -244,37 +256,44 @@ Open up */themes/simple/templates/Includes/BreadCrumbs.ss* template and look at
244 256
 
245 257
 	:::ss
246 258
 	<% if Level(2) %>
247  
-	<div id="Breadcrumbs">
248  
-	   	$Breadcrumbs
249  
-	</div>
250  
-<% end_if %>	
  259
+		<div id="Breadcrumbs">
  260
+		   	$Breadcrumbs
  261
+		</div>
  262
+	<% end_if %>	
251 263
 
252 264
 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
253 265
 the top level with another if statement.
254 266
 
255  
-The *Level* page control allows you to get data from the page's parents, e.g. if you used *Level(1)*, you could use
256  
-*$Level(1).Title* to get the top level page title. In this case, we merely use it to check the existence of a second
257  
-level page; if one exists then we include the breadcrumbs.
  267
+The *Level* page control allows you to get data from the page's parents, e.g. if you used *Level(1)*, you could use:
  268
+	:::ss
  269
+	$Level(1).Title 
  270
+
  271
+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.
258 272
 
259  
-This shows how the two level navigation system functions. Both menus should be updating and highlighting as you move
260  
-from page to page. They will also mirror changes done in the SilverStripe CMS, such as renaming pages or moving them
261  
-around.
  273
+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.
262 274
 
263 275
 ![](_images/tutorial1_menu-two-level.jpg)
264 276
 
265  
-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.
  277
+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. 
266 278
 
267  
-	::ss
  279
+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.
  280
+
  281
+	:::ss
268 282
 	<ul>
269 283
 	  <% loop Menu(1) %>
270 284
 	    <li class="$LinkingMode">
271 285
 	      <a href="$Link" title="$Title.XML">$MenuTitle.XML</a>
272 286
 	      <% if Children %>
273  
-	      <ul>
274  
-	        <% loop Children %>
275  
-	          <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>
276  
-	        <% end_loop %>
277  
-	      <ul>
  287
+		      <ul>
  288
+		        <% loop Children %>
  289
+		          <li class="$LinkingMode">
  290
+		          	<a href="$Link" title="Go to the $Title.XML page">
  291
+		          		<span class="arrow">&rarr;</span>
  292
+		          		<span class="text">$MenuTitle.XML</span>
  293
+		          	</a>
  294
+		          </li>
  295
+		        <% end_loop %>
  296
+		      <ul>
278 297
 	      <% end_if %>
279 298
 	    </li>
280 299
 	  <% end_loop %>
@@ -294,8 +313,7 @@ banner to welcome visitors.
294 313
 ### Creating a new page type
295 314
 
296 315
 Earlier we stated that every page in a SilverStripe site has a **page type**, and that SilverStripe will look for a
297  
-template or template layout corresponding to the page type. Therefore, the first step to get the homepage using a different template is to
298  
-create a new page type.
  316
+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.
299 317
 
300 318
 Each page type is represented by two php classes: a *data object* and a *controller*. Don't worry about the details of page
301 319
 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
321 339
 
322 340
 
323 341
 Every page type also has a database table corresponding to it. Every time we modify the database, we need to rebuild it.
324  
-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. 
  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). 
325 343
 
326 344
 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
327 345
 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
332 350
 
333 351
 After building the database, we can change the page type of the homepage in the CMS. 
334 352
 
335  
-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".
  353
+In the CMS, navigate to the "Home" page and switch to the "Settings" tab. Change "Page type" to *Home Page*, and click "Save & Publish".
336 354
 
337 355
 ![](_images/tutorial1_homepage-type.jpg)
338 356
 
@@ -345,11 +363,17 @@ to the template of the page type's parents.
345 363
 
346 364
 ### Creating a new template
347 365
 
348  
-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. 
  366
+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. 
349 367
 
350  
-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.
  368
+First, remove the breadcrumbs and the secondary menu by removing:
  369
+	<% include SideBar %> 
  370
+ we don't need it for the homepage. 
  371
+
  372
+Let's replace the title with an image. Find this line:
  373
+	:::ss
  374
+	<h1>$Title</h1>
351 375
 
352  
-Now add the following to replace the `<h1>$Title</h1>` code in your template:
  376
+ and replace it with:
353 377
 
354 378
 	:::ss
355 379
 	<div id="Banner">
@@ -365,21 +389,16 @@ Your Home page should now look like this:
365 389
 SilverStripe first searches for a template in the *themes/simple/templates* folder. Since there is no *HomePage.ss*,
366 390
 it will use the *Page.ss* for both *Page* and *HomePage* page types. When it comes across the *$Layout* tag, it will
367 391
 then descend into the *themes/simple/templates/Layout* folder, and will use *Page.ss* for the *Page* page type, and
368  
-*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.
  392
+*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.
369 393
 
370 394
 ![](_images/tutorial1_subtemplates-diagram.jpg)
371 395
 
372 396
 
373 397
 ## Summary
374 398
 
375  
-We have introduced template variables, controls and if blocks, and we have used these
376  
-to build a basic but fully functional site. You have also been briefly introduced to page types, and seen how they
377  
-correspond to templates and sub-templates. By using these templates, you have seen how to customize the site content
378  
-according to the page type of the page you are displaying.
  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.
379 400
 
380  
-In the next tutorial, [Extending a Basic Site](2-extending-a-basic-site), we will explore page types on a
381  
-deeper level, and see how you can customize your own page types to extend SilverStripe to do much more interesting
382  
-things.
  401
+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.
383 402
 
384 403
 [Next Tutorial >>](2-extending-a-basic-site)
385 404
 
BIN  docs/en/tutorials/_images/tutorial1_cms-basic.jpg
BIN  docs/en/tutorials/_images/tutorial1_cms-numbered-2b.jpg
BIN  docs/en/tutorials/_images/tutorial1_cms-numbered-3.jpg
BIN  docs/en/tutorials/_images/tutorial1_cms-numbered-5.jpg
BIN  docs/en/tutorials/_images/tutorial1_cms-numbered.jpg

0 notes on commit 2c024e4

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