Setup a new SilverStripe 4 Project
Created at 2020-08-02 Updated at 2020-10-05 Category Silverstripe
I have recently started a new job as a software developer, the tech stack includes a content management system (CMS) called Silverstripe. I therefore wanted to learn the Silverstripe CMS. The inital process of creating a project should be straight forward, there are supposed to be beginner lessons.
The first three lessons on how to set up a silverstripe project are confusing, as there is intermixed talk about upgrading from silverstripe v3. this is a simple guide to configure a new silverstripe v4 project from scratch, without the confusion of upgrading.
The guide from the official lessons:
- The original guide: silverstripe lessons v4
Sometimes it was useful to view the original video series:
- The original v3 guide, including videos: silverstripe lessons v3
Setup a local development environment. On Windows I recommend laragon.org, which has all the required components:
See lesson 0 for full details on a LAMP, MAMP or WAMP stack:
Use composer to create the silverstripe project using the silverstripe installer
composer create-project silverstripe/installer silverstrip4-example
.env.example file to make
copy .env.example .env
.env file with the local settings (change the values of names and passwords as required):
# DB credentials
Launch Laragon, start Apache and MySQL, the pretty url will automatically be created for the project
silverstripe4-example. For other dev environments configure Apache as required.
Open the browser to http://silverstripe4-example.test to populate the database
Based on lesson 1 Creating your first project
\silverstripe4-example\app directory, create a
app\templates and create a file called
Page.ss. Open that file, create a basic HTML document.
To activate the theme, we’ll have to dig into the project directory. Open the file
theme.yml in the
app theme and comment out
app.yml and change the project name to app.
To clear the cache, simply access any page on your site and append ?flush to the URL, e.g. http://silverstripe4-example.test?flush
The website will display Hello, world
Next configure PSR-4 autoloading. Open
\silverstripe4-example\composer.json. In particular the “autoload”: and app.yml
- Based on lesson 2 Migrating static templates into your theme
Download the zip file from https://github.com/silverstripe/one-ring-rentals
Create a folder
one-ring-rentals.zip, in a temp directory, and copy the
static folder into the newly created
Open the browser to http://silverstripe4-example.test/static/default.html to view the content.
Copy the contents of
app\templates\Page.ss (the file created in lesson one with “hello world”)
Copy the folders
Open http://silverstripe4-example.test/ and the default page will be the same as the static page.
Some code snippets were hard to follow, I have expanded the scope of these snippets to make the code block easier to identify.
- Based on lesson 3 Migrating static templates into your theme
Update the nav menu with Dynamic content from Silverstripe.
- <% loop $Menu(1) %> Begins a loop through all the menu items, repeating all the HTML that is in the loop for each one. By passing (1) as an argument, we are asking the CMS to give us all the pages at level 1 of the hierarchy. Changing that to (2) would give us all the pages at the second level of the hierarchy in the current section, and so on.
- $Link The link to the page in the current iteration of the loop.
- $Title The title of the page in the current iteration of the loop
- $MenuTitle SilverStripe distinguishes between the title of a page (i.e. in your
<h1>tag) and the title that should appear in the context of navigation. Often times these are the same, but since the user is given the option to customise the title in menus, we use the
- $LinkingMode A helper method that indicates the state of our menu. For each item in the list, this method will return one of three strings:
- link: the page is not active
- current: this is the current page
- section: the current page is a descendant of this page (i.e. on the URL /about-us/company, the “company” page is current, and the “about-us” page is “section.”
<!-- BEGIN MAIN MENU -->
Refresh the page. You should now see the three default pages SilverStripe creates for you in the primary navigation: Home, About Us, and Contact Us.
<% base_tag %> to the top of the html, under the
We can update our
<h1> tag to use the $Title variable.
Replace the contents of
<div class="breadcrumb"> with
Replace the contents of
<div class="main col-sm-8"> with
Let’s look quickly at the login page to the CMS by accessing the
/admin/ URL. Notice that we’re not presented with any login form. In order to get the form to show, we’ll need to add a
$Form variable, which primarily serves as a placeholder for the login form.
<div class="main col-sm-8">
Earlier in this tutorial we created a loop for primary navigation using $Menu(1). Similarly, we can create subnavigation using $Menu(2). We don’t want to include this block of content unless subnavigation exists, so we’ll wrap the whole thing in an <% if $Menu(2) %> block.
Replace the contents of the sidebar as follows:
<div class="sidebar gray col-sm-4">
We want to make sure this links to the base URL of our website. Let’s use the
$AbsoluteBaseURL variable in the link around the logo.
<div class="block col-sm-3">
The remaining lessons could be followed without too much problem, the main gotchas were:
- Importing images:
- I couldn’t find the source of the original images
- The work around was to use my own, however, they had to be uploaded one by one.
- Importing records e.g. to have data for filtering or pagination. (i.e. using SQL import):
- This didn’t work, I suspect the table names or versioning were different.
- The work around was to manually type in some records.
- Some code snippets weren’t always clear which files was being editing.
- I viewed the v3 videos to confirm.
I hope this setup helps new learners to set up Silverstripe and following the remaining lessons.