From 2c024e444c744d7864bc35615d37f76e9411114e Mon Sep 17 00:00:00 2001 From: Naomi Guyer Date: Thu, 28 Jun 2012 15:24:59 +1200 Subject: [PATCH 1/2] MINOR: Documentation, tutorial (part1) --- docs/en/tutorials/1-building-a-basic-site.md | 179 ++++++++++-------- .../tutorials/_images/tutorial1_cms-basic.jpg | Bin 32066 -> 33504 bytes .../_images/tutorial1_cms-numbered-2b.jpg | Bin 11490 -> 0 bytes .../_images/tutorial1_cms-numbered-3.jpg | Bin 0 -> 21156 bytes .../_images/tutorial1_cms-numbered-5.jpg | Bin 0 -> 32765 bytes .../_images/tutorial1_cms-numbered.jpg | Bin 45430 -> 44425 bytes 6 files changed, 99 insertions(+), 80 deletions(-) delete mode 100644 docs/en/tutorials/_images/tutorial1_cms-numbered-2b.jpg create mode 100644 docs/en/tutorials/_images/tutorial1_cms-numbered-3.jpg create mode 100644 docs/en/tutorials/_images/tutorial1_cms-numbered-5.jpg diff --git a/docs/en/tutorials/1-building-a-basic-site.md b/docs/en/tutorials/1-building-a-basic-site.md index 8625de45a..51cf62bc2 100644 --- a/docs/en/tutorials/1-building-a-basic-site.md +++ b/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 @@ -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 +
  • + $MenuTitle.XML +
    • -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 @@ -228,7 +235,12 @@ like this: ... ... @@ -244,37 +256,44 @@ Open up */themes/simple/templates/Includes/BreadCrumbs.ss* template and look at :::ss <% if Level(2) %> - -<% end_if %> + + <% 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