SilverStripe tutorial for beginners

With this step by step-tutorial I would like to show beginners how SilverStripe CMS is used in web development. I will be using a practical example (blog module).

What you can expect to learn from this tutorial:

• The construction of the system-architecture of a SilverStripe module
• How to correctly apply a module and divide codes
• How to create models, controllers and templates
• How to manage models in the admin panel

Short description of a blog module
Let’s call our blog MyBlog. With the help of this blog it will be possible to enter blog entries into the backend or the admin panel and list them in the frontend. For every blog entry the following information will be saved:

• Blog Title
• Short description
• Blog content

1. Preparations
Firstly, we will create a phpinfo-file in our installation directory. This file will help us check whether our server fulfills SilverStripe’s requirements.

<?php
    echo phpinfo();
?>

Secondly, we download the latest version of SilverStripe (CMS + framework) from SilverStripe’s download website.
Now we can unpack the files to our installation directory, e.g. var/www/myproject.

Our installation directory should now contain the following folders and files:
assets is our upload folder. All pictures and files are uploaded here by CMS.

cms is the folder of the SilverStripe CMS module. Here we can see the recommended code allocation of a SilverStripe module. The files in this folder are not to be changed.

framework contains all SilverStripe-corefiles. At first, these corefiles are not to be changed, just like the files in the cms folder.

mysite is the working space of our project myproject. Controllers and models extension are created here.

themes is the template folder. Templates for our project MyBlog will be adjusted here.

vendor contains Thirdparty files.

Now that we’ve made all preparations, we can install CMS. The installation is a very quick and easy process.

We open our project site (e.g. http://localhost/myproject). The SilverStripe installation assistand will now run automatically. After successfully completing the installation, we log into the admin panel (http://localhost/myproject/admin). We can now take a look at the CMS-system in the admin panel and try to create, edit and delete a few sites in order to become acquainted with SilverStripe.

2. Creating a directory structure of a project
Firstly, we change the name of the directory mysite to myblog. Afterwards, we create two directories in myblog/code/: controllers and models. All controllers are saved in the controllers directory, all models in the models directory.

We now create a new directory in the themes-directory and call it myblog.

Then we copy all files from the directory themes/simple/ and paste them into themes/myblog/. Now we want to tell SilverStripe our new directory architecture by going to http://localhost/myproject/admin/settings/ and selecting the theme myblog from the list.

In order to update the new updates of the directory structure, we navigate to the following URLs:
http://localhost/myblog/dev/build/    this URL updates the directory structure
http://localhost/myblog/?flush=1    this URL clears the cache

3. Creating a model
At first, we create a model MyBlog.php in myproject/models/. Then we insert the following lines:

<?php
class MyBlog extends DataObject {
    private static $db = array(
        'BlogTitle' => 'varchar', 
        'BlogShortDescription' => 'text', 
        'BlogContent' => 'HTMLText');
    private static $summary_fields = array(
              'ID',
              'Title');
}
?>

With private static $db = array() we define the database scheme of the model.
With private static $summary_fields = array() we define which fields are listed on the site map of the model.

FOR EVERY MODEL SILVERSTRIPE AUTOMATICALLY CREATES AN ID, Created and LastEdited-fields

On the SilverStripe website you can find additional information on
DataObject (http://doc.silverstripe.org/framework/en/reference/dataobject), as well as
Data Types (http://doc.silverstripe.com/framework/en/topics/data-types)

After saving the file MyBlog.php, we access the URL http://localhost/myblog/dev/build/, in order to build up the database scheme of the model. Here, SilverStripe will create a mysql table MyBlog in the database.

 4. Modeladmin
In order to save blog entries in the database, we need a modeladmin for the MyBlog-model. We acquire a modeladmin by creating a file MyBlogAdmin.php in the model-directory myproject/code/models.
We insert the following lines into the file MyBlogAdmin.php:

<?php
class MyBlogAdmin extends ModelAdmin {
    static $managed_models = array('MyBlog');
    static $url_segment = 'MyBlog';
    static $menu_title = 'My Blog';
}
?>

static $managed_models defines, which models can be managed by the modeladmin in the admin panel (adding, editing and deleting entries)
static $url_segment defines the model URL in the admin panel, e.g. admin/MyBlog/
static $menu_title defines the navigation name of the model in the admin panel

You can find more information about modeladmin on the Silverstripe website:
http://doc.silverstripe.org/framework/en/reference/modeladmin

Now let’s save the file MyBlogAdmin.php and access the following URLs:
http://localhost/myblog/dev/build/
http://localhost/myblog/?flush=1

Then, we open http://localhost/myblog/admin/. In the left column of the admin menu we can see the navigation point My Blog. Clicking on it will take us to the MyBlog model page. Here we can edit our model MyBlog. In order to save a new blog entry in the database, we click on „Add My Blog“. Now we can create and edit a few test entries so that we can become acquainted with the model.

5. My Blog controller in the frontend
In order to list blog entries of the MyBlog-model in the frontend, we need a controller which takes the files from the MyBlog-model and sends them back to a template as an array.

We create a file MyBlog.php in myblog/code/controllers and insert the following lines:

<?php
class MyBlogPage extends Page {
}

class MyBlogPage_Controller extends Page_Controller {
}
?>

The class MyBlogPage lies in SilverStripe CMS. A new site type is called MyBlogPage.
We save the file MyBlogPage.php and access the following URLs again:
http://localhost/myblog/dev/build/
http://localhost/myblog/?flush=1

Then we create a new CMS site MyBlog in the admin panel. We select MyBlog as  site type. Our site name, URL segment and navigation name will be MyBlog as well. We now make a test entry and type „My Blog Site“ in our content box. Finally, we click on save and publish.

In CMS, our site MyBlog is already set up. We switch to http://localhost/myproject/. We can now see the navigation point MyBlog in the menu bar.

In order to list entries in the frontend, we create a new method items in MyBlogPage_Controller.

<?php
class MyBlogPage extends Page {
}

class MyBlogPage_Controller extends Page_Controller {

    public function items() {
        $items = MyBlog::get()->sort('BlogTitle ASC');
        if($items) return $items;
        else return false;
    }
}
?>

 6. List blog entries in the template
In order to list blog entries in the frontend, we must first create a template MyBlogPage.ss in myproject/themes/myblog/templates/layout/.

The name of the template should be the same as the name of the controller, but with the word „Page“ added at the end. SilverStripe automatically recognizes the template MyBlogPage.ss when we open the controller http://localhost/myproject/MyBlog.

If MyBlogPage.ss is not defined, Silverstripe will open the tempalte themes/myblog/templates/Layout/Page.ss as the default template.
After creating the template MyBlogPage.ss, we insert the following code into it:

<% if $items %>
    <% loop $items %>
        <h3<a href=”{$Up.URLSegment}/BlogDetails/{$ID}”>$BlogTitle</a></h3>
        <p>$BlogShortDescription</p>
    <% end_loop %>
<% end_if %>

Explanation of the code:
$items is an array (from method items in the MyBlogPage_Controller)

With the loop we read blog entries of the variable $items.
$Up.URLSegment (from CMS) defines the SegmentURL of the site MyBlog. In our case it is called $URLSegment myblog.

„With $Up we can access the global variable outside of a loop.“

BlogDetails is the action name in the MyBlog_controller, which we will later create as public function Blog Details in order to extract details of a blog entry from the database and depict them in a template.
$BlogTitle is the title of every single blog entry.

You can find put more about templates on the Silverstripe website:
http://doc.silverstripe.org/framework/en/reference/templates

Now, we save our templates and clear the cache with http://localhost/myproject/?flush=1. Afterwards, we access our MyBlog site http://localhost/myproject/myblog/.

7. Creating of an action
In order to list details of a blog entry in the frontend, we have to create an action (public function) in MyBlog_controller. In our case, the action is called BlogDetails.

Bevor creating public function BlogDetails, we have to define the action name BlogDetails in the variable  $allowed_actions, so that SilverStripe-CMS runs the action BlogDetails when the URL http://localhost/myblog/myblog/BlogDetails/1 is called up (1 is the ID of the blog entry). You can find more about controller here: http://doc.silverstripe.org/framework/en/topics/controller

Now we create the method BlogDetails in the MyBlog_controller.

//...
    public function BlogDetails() {
        $parm = $this->getURLParams();
        $item = MyBlog::get()->byID($parm['ID']);
        if ($item) return $this->customise(array('BlogItem' => $item));
        else return false;
    }

Creating a template for our action-MyBlog
In order to depict the details of a blog entry in a template, a new template MyBlogPage_BlogDetails.ss has to be created in myproject/themes/myblog/Layout/.

We now open the template MyBlogPage_BlogDetails.ss and insert the following ines: 

<% if $BlogItem %>
    <article>
        <h1>$BlogItem .BlogTitle</h1>
        <p>$BlogItem .BlogContent</p>
        <p>$BlogItem .Created.Format('d.m.Y')</p>
    </article>
<% end_if %>

Then, we save MyBlogPage_BlogDetails.ss and clear the cache again with http://localhost/myblog/?flush=1