Skip to content

Commit

Permalink
Proof reading tutorials 1 and 2
Browse files Browse the repository at this point in the history
  • Loading branch information
@chillu
chillu committed Jun 28, 2012
1 parent aa8dfd1 commit 3ef394c
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 90 deletions.
75 changes: 24 additions & 51 deletions docs/en/tutorials/1-building-a-basic-site.md
View file
Expand Up @@ -70,8 +70,8 @@ with the editor - try different formatting, tables and images. When you are done
& Publish" to post the content to the live site.

### 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.
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)
Expand All @@ -91,12 +91,13 @@ become *about-us*. You are able to change it yourself so that you can make long
example, *Employment Opportunities* could be shortened to *jobs*. The ability to generate easy to type, descriptive URLs
for SilverStripe pages improves accessibility for humans and search engines.

You should ensure the URL for the home page is *home*. By default, SilverStripe loads the page with the URL *home*.
You should ensure the URL for the home page is *home*, as that's the page SilverStripe loads by default.


## Templates

All pages on a SilverStripe site are rendered using a template. A template is an HTML file augmented with special
All pages on a SilverStripe site are rendered using a template. A template is an file
with a special `*.ss` file extension, containing HTML augmented with some
control codes. Because of this, you can have as much control of your site’s HTML code as you like.

Every page in your site has a **page type**. We will briefly talk about page types later, and go into much more detail
Expand All @@ -116,7 +117,7 @@ ensures the browser knows where to locate your site's images and css files.
$Title
$SiteConfig.Title

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.
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.

:::ss
$MetaTags
Expand All @@ -136,7 +137,8 @@ The Content variable is replaced with the content of the page currently being vi
your site's content in the CMS.

These template markers are processed by SilverStripe into HTML before being sent to your
browser and are formatted either with a *$* at the beginning or are between the SilverStripe template tags:
browser and are either prefixed with a dollar sign ($)
or placed between SilverStripe template tags:

:::ss
<% %>
Expand Down Expand Up @@ -185,39 +187,23 @@ This creates the navigation at the top of the 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:
:::ss
$LinkingMode

*$LinkingMode* returns one of three values:
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:

* *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 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:
For example, if you were here: "Home > Company > Staff > Bob Smith", you may want to highlight 'Company' to say you are in that section. If you add $LinkingMode to your navigation elements as a class, ie:

:::ss
<li class="$LinkingMode">
<a href="$Link" title="$Title.XML">$MenuTitle.XML</a>
</li>

you will then be able to target a section in css (*simple/css/layout.css*), ie:
you will then be able to target a section in css (*simple/css/layout.css*), e.g.:

:::css
.section {
background:#ccc;
}
You may also style the link to the current page this way, eg:
:::css
.current {
/* Your styles here */
}

Or, target links that are neither current nor in the same section as the current link, eg:

:::css
.link {
/* Your styles here */
}
.section { background:#ccc; }

## A second level of navigation

Expand Down Expand Up @@ -344,26 +330,16 @@ banner to welcome visitors.
Earlier we stated that every page in a SilverStripe site has a **page type**, and that SilverStripe will look for a
template, or template layout, corresponding to the page type. Therefore, the first step when switching the homepage template is to create a new page type.

Each page type is represented by two php classes: a *data object* and a *controller*. Don't worry about the details of page
types right now, we will go into much more detail in tutorial two.
Each page type is represented by two PHP classes: a *data object* and a *controller*. Don't worry about the details of page
types right now, we will go into much more detail in the [next tutorial](2-extending-a-basic-site).

Create a new file *HomePage.php* in *mysite/code*. Copy the following code into it:

:::php
<?php
/**
* Defines the HomePage page type
*/

class HomePage extends Page {
static $db = array(
);
static $has_one = array(
);
}

class HomePage_Controller extends Page_Controller {
}


Expand All @@ -383,24 +359,21 @@ In the CMS, navigate to the "Home" page and switch to the "Settings" tab. Change

![](_images/tutorial1_homepage-type.jpg)

Our homepage is now of the page type *HomePage*. However, even though it is of the *HomePage* page type, it is still
rendered with the *Page* template. SilverStripe still renders the homepage using the *Page* template because when we
created the *HomePage* page type, we inherited from *Page*. So when SilverStripe cannot find a *HomePage* template, it
will use the *Page* template. SilverStripe always attempts to use the most specific template first, and then falls back
to the template of the page type's parents.
Our homepage is now of the page type *HomePage*. Regardless, it is still
rendered with the *Page* template. SilverStripe does this the type inherits from *Page*,
which acts as a fallback if no *HomePage* template can be found.
It always tries to use the most specific template in an inheritance chain.


### Creating a new template

To create a new template layout, create a copy of *Page.ss* (found in *themes/simple/templates/Layouts*) and call it *HomePage.ss*. If we flush the cache (*?flush=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.
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.

First, remove the breadcrumbs and the secondary menu by removing:
First, we don't need the breadcrumbs and the secondary menu for the homepage. Let's remove them:
:::ss
<% include SideBar %>

we don't need it for the homepage.

Let's replace the title with an image. Find this line:
We'll also replace the title text with an image. Find this line:

:::ss
<h1>$Title</h1>
Expand Down Expand Up @@ -432,7 +405,7 @@ So far we have taken a look at the different areas and functionality within the

In the next tutorial, [Extending a Basic Site](2-extending-a-basic-site), we will explore page types on a deeper level, and look at customising our own page types to extend the functionality of SilverStripe.

[Next Tutorial >>](2-extending-a-basic-site)
[Next tutorial >>](2-extending-a-basic-site)

## Books on SilverStripe

Expand Down
58 changes: 19 additions & 39 deletions docs/en/tutorials/2-extending-a-basic-site.md
View file
Expand Up @@ -62,18 +62,9 @@ We'll start with the *ArticlePage* page type. First we create the model, a class

:::php
<?php
/**
* Defines the ArticlePage page type
*/
class ArticlePage extends Page {
static $db = array(
);
static $has_one = array(
);
}

class ArticlePage_Controller extends Page_Controller {
}

Expand All @@ -87,20 +78,10 @@ Let's create the *ArticleHolder* page type.

:::php
<?php
/**
* Defines the ArticleHolder page type
*/
class ArticleHolder extends Page {
static $db = array(
);
static $has_one = array(
);
static $allowed_children = array('ArticlePage');
}
class ArticleHolder_Controller extends Page_Controller {
}


Expand All @@ -111,15 +92,17 @@ We will be introduced to other fields like this as we progress; there is a full

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.

> It is SilverStripe convention to suffix general page types with "Page", and page types that hold other page types with
> "Holder". This is to ensure that we don't have URLs with the same name as a page type; if we named our *ArticleHolder*
> page type "News", it would conflict with the page name also called "News".
<div class="hint" markdown="1">
It is SilverStripe convention to suffix general page types with "Page", and page types that hold other page types with
"Holder". This is to ensure that we don't have URLs with the same name as a page type; if we named our *ArticleHolder*
page type "News", it would conflict with the page name also called "News".
</div>

## Adding date and author fields

Now that we have an *ArticlePage* page type, let's make it a little more useful. Remember the *$db* array? We can use
this array to add extra fields to the database. It would be nice to know when each article was posted, and who posted
it. Change the *$db* array in the *ArticlePage* class to look like this:
it. Add a *$db* property definition in the *ArticlePage* class:

:::php
<?php
Expand All @@ -133,10 +116,12 @@ it. Change the *$db* array in the *ArticlePage* class to look like this:
}


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*.
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.

> Note: The names chosen for the fields you add must not already be used. Be careful using field names such as Title,
> Content etc. as these may already be defined in the page types your new page is extending from.
<div class="hint" markdown="1">
The names chosen for the fields you add must not already be used. Be careful using field names such as Title,
Content etc. as these may already be defined in the page types your new page is extending from.
</div>

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.

Expand Down Expand Up @@ -180,16 +165,13 @@ returned is a `[api:FieldList]` object.
We can then add our new fields with *addFieldToTab*. The first argument is the tab on which we want to add the field to:
"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.

> 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'));
> would create a new tab called "New Tab", and a single "Author" textfield inside.

<div class="hint" markdown="1">
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'));`
would create a new tab called "New Tab", and a single "Author" textfield inside.
</div>

We have added 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.
There are many more fields available in the default installation, listed in ["form field types"](/reference/form-field-types).

:::php
return $fields;
Expand Down Expand Up @@ -238,12 +220,12 @@ Let's walk through these changes.
:::php
$dateField->setConfig('showcalendar', true);

Set *showCalendar* to true to have a calendar appear underneath the Date field when you click on the field.
By enabling *showCalendar* you show a calendar overlay when clicking on the field.

:::php
$dateField->setConfig('dateformat', 'dd/MM/YYYY');

*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.
*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.

:::php
$fields->addFieldToTab('Root.Content', new TextField('Author','Author Name'), 'Content');
Expand All @@ -258,7 +240,7 @@ Because our new pages inherit their templates from *Page*, we can view anything
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
page layout.

###ArticlePage Template
### ArticlePage Template
First, the template for displaying a single article:

**themes/simple/templates/Layout/ArticlePage.ss**
Expand All @@ -274,7 +256,6 @@ First, the template for displaying a single article:
<div class="content">$Content</div>
</article>
$Form
$PageComments
</div>
<% include SideBar %>

Expand Down Expand Up @@ -545,7 +526,6 @@ The *StaffPage* template is also very straight forward.
$Content</div>
</article>
$Form
$PageComments
</div>
<% include SideBar %>

Expand Down

0 comments on commit 3ef394c

Please sign in to comment.