mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 12:05:37 +00:00
Proof reading tutorials 1 and 2
This commit is contained in:
Ingo Schommer
parent
aa8dfd127c
commit
3ef394c448
@ -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".
|
||||
|
||||
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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
|
||||
<% %>
|
||||
@ -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
|
||||
|
||||
@ -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 {
|
||||
|
||||
}
|
||||
|
||||
|
||||
@ -383,24 +359,21 @@ In the CMS, navigate to the "Home" page and switch to the "Settings" tab. Change
|
||||
|
||||
|
||||
|
||||
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>
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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 {
|
||||
|
||||
}
|
||||
|
||||
|
||||
@ -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 {
|
||||
|
||||
}
|
||||
|
||||
|
||||
@ -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
|
||||
@ -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.
|
||||
|
||||
@ -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;
|
||||
@ -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');
|
||||
@ -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**
|
||||
@ -274,7 +256,6 @@ First, the template for displaying a single article:
|
||||
<div class="content">$Content</div>
|
||||
</article>
|
||||
$Form
|
||||
$PageComments
|
||||
</div>
|
||||
<% include SideBar %>
|
||||
|
||||
@ -545,7 +526,6 @@ The *StaffPage* template is also very straight forward.
|
||||
$Content</div>
|
||||
</article>
|
||||
$Form
|
||||
$PageComments
|
||||
</div>
|
||||
<% include SideBar %>
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user