Skip to main content

This site requires you to update your browser. Your browsing experience maybe affected by not having the most up to date version.

UncleCheese
5th December 2014

In this tutorial, we’ll cover how to build your first theme in SilverStripe. The SilverStripe installer ships with its own default theme -- Simple, but more than likely, you’ll want to override this to use your own custom design.

Creating your first theme

Level: Beginner

Duration: 9:32

In this lesson:

In this tutorial, we’ll cover how to build your first theme in SilverStripe. The SilverStripe installer ships with its own default theme -- Simple, but more than likely, you’ll want to override this to use your own custom design.

What is a theme?

In a conventional SilverStripe project, the code and business logic (backend) of a website is kept separate from the UI and design elements (frontend). More specifically, PHP classes and configuration files are kept in the project directory, while templates, CSS, images, and Javascript are kept in the theme directory.

In a default installation of SilverStripe, your project directory is called mysite/, and lives in the web root. Your theme directory, however, will be located one level deeper, under the themes/ folder. Because the code layer is detached from the UI, a given project can have multiple themes.

Building the theme structure

Let’s create our first theme by creating a new folder under themes/. The folder name is arbitrary, but must be comprised of only alphanumeric characters, dashes, or underscores. In this lesson, we’ll call the folder one-ring/, which refers to the name of our website, but feel free to choose any name you like. Remember the name you choose, as we’ll need to refer to it later.

Underneath your new theme folder, you’ll need to create some new folders, so that your theme has the following structure:

  • themes
    • one-ring
    • css
    • images
    • javascript
    • templates
      • Includes
      • Layout

Most of these folders are self-descriptive, but note that the only folders with compulsory names are templates and css. The images and javascript folders can be named anything you like. In fact, they can even remain absent if you don’t have anything to put there. Further, feel free to add any other folders you like, and subfolders thereof (i.e. a less/ or scss/ folder).

Next we’ll create the most fundamental component of a theme -- a template. In SilverStripe, templates are not HTML documents, but rather PHP code that is compiled from SilverStripe’s own template syntax behind the scenes. In alignment with that key that distinction, it is imperative that template files use the .ss extension.

In your templates/ directory, create a file called Page.ss. Inside that file, create a basic HTML document.

<html>
  <body>
    <h1>Hello, world</h1>
  </body>
</html>

Why Page.ss? A default installation of SilverStripe ships with a page type called Page. Typically, this page type is used to display the most basic form of content for a project. A common use case is for the “About Us” page, or even something more plain, like “Terms and Conditions.”

Activating the theme

To activate the theme, we’ll have to dig into the project directory. Open the file config.yml in the mysite/_config directory. Under the heading SSViewer, take note of the setting for theme, and change it to your theme name. In this case, we named our theme one-ring, so our new configuration file will look like this:

SSViewer:  theme: 'one-ring'

These files are written in YAML, which is a markup language, similar to JSON or XML, that is very well-documented. Configuration is a very rich topic in SilverStripe that we’ll cover in later tutorials, but for now, the only important bit you need to know is that any changes you make to these files have to be cleared from cache. To clear the cache, simply access any page on your site and append ?flush to the URL, e.g. http://localhost:8888/tutorial/?flush

Once the page is loaded, you should see your “Hello, world” page template. At this time, you can feel free to delete the “simple” theme from your themes directory, as we have now branched out on our own.

Questions and Feedback

'?flush' does not seem to work for me when I try to apply my theme... I am using MAMP.

Am I missing something?

by Jonathan at 04:20am, 7 April 2015

Author

Hi, Jonathan,

If you continue to have issues, feel free to send an archive of your site to the email provided at the end of the screencast, and I can test it out for you.

by UncleCheese at 03:12pm, 9 April 2015

Author

What makes you think it's not working?

by UncleCheese at 01:55pm, 27 April 2015

"Hello World" is not appearing. The orginal simple web page is still being displayed.

by mike at 02:18pm, 27 April 2015

Author

The last person who had this issue did not name his template folders correctly. Are they named templates/Layout and templates/Includes? Note the capitalisation.

by UncleCheese at 05:50pm, 27 April 2015

You were correct about the need for capitals. However making this change did not fix the problem. I am running Windows 7 64bit. I am able to to connect into the database using phpMyAdmin. I also use static ip. I mention this just in case its pertinent info. At the moment when I enter the url http://localhost:3000/silverstripe I get a web page coming back that is not formatted although the content is there and there is a message in the middle of it saying "Server Error - Sorry, there was a problem with handling your request". Any help would much appreciated.

by mike at 05:04pm, 29 April 2015

Author

If you're just getting a generic server error, your site isn't in dev mode. Try appending ?isDev=1 to the request. You might also check out the "Up and Running" tutorial, which covers environment configuration. https://vimeo.com/108861537 (skip to about 8:00).

by UncleCheese at 05:11pm, 29 April 2015

I was having the issue others were having, where /?flush was not working. Looking into it a bit, I realized it was because the theme was being loaded from the siteconfig table, and not the config.yml file. Is the problem that /?flush should be updating the table from the config file, but isn't for some reason (possibly having something to due with installation or OS, I used the zip file provided on a windows 7 64-bit). This issue can be bypassed by manually updating the table, or by going into the admin section to change the theme, so it isn't a big deal, but I just want to make sure things are working properly. Thanks!

by Justin at 12:08pm, 9 June 2015

?flush didn't work for me either but I finally got the site to update by going into the admin area and into settings and changing the theme there

by Dave at 11:17am, 29 August 2015

Why would you change the active theme by editing the config file when you can easily change themes through the CMS back-end?

by Faloude at 09:12am, 23 January 2016

Good question, Saman. The difference is a question of the level of permanence you want. By making the change in the config yaml, that data is stored in the repository, and therefore ships with the project, ensuring that all developers will be using the correct theme. Changing it in the config is at the database level, and therefore will vary on every environment.

The use case for an admin changing themes are quite rare. Maybe an online store wants to have a holiday theme in December, or something like that. In those cases, we want to empower the content editor to change the theme without getting a developer involved.

by UncleCheese at 09:56am, 26 January 2016

So I followed the tutorial and flushed the changes which worked fine and I now see the Hello, World! page.

However, how do I login to the CMS now as if I try to go to the login page, I just see Hello, World.

Is this as expected?

by Glenn at 01:43am, 27 January 2016

Hi, Glenn,

That is expected. We don't add the login form until Lesson #3 (Adding Dynamic Content).

by UncleCheese at 02:00pm, 27 January 2016

This may seem dumb but im working on microsoft..I'm not sure where to go that i can edit that is similar to what you have. I'm having so much trouble with putting my already built site into silverstripe. I was able to view the site locally from the file location but I got a little lost at about 02:20 in the video. Please let me know if you can help me learn this.

by Cassi at 06:03am, 14 April 2016

Ugg I meant to say Windows 10...jeez my brain is lost today

by Cassi at 06:04am, 14 April 2016

At 2:20 we are under the 'themes' folder. On Windows, assuming you're using Wamp, you may be somewhere around here:

C:\wamp\www\your-silverstripe-project\themes\

'one-ring' and 'simple' are 2 themes under the themes directory.

Under each theme we usually have the following folders containing:

  • css: the style sheets
  • images: e.g. sprites, pictures, graphics etc
  • javascript: custom and vendor scripts for your theme
  • templates: SilverStripe template files

The first 3 folders are quite straight forward. The templates, however, are unique to SilverStripe.

There are mainly 2 types of templates, Layout and Include. The Layout template are responsible for page layouts, Include templates are partial files, and commonly used for rendering components. Please continue watching to learn more specifics about them.

Hope this helps. Feel free to drop me a personal email if you'd like more pointers [email protected]

by suhongyang at 09:53pm, 16 June 2016

I'm getting a little bit confused at 5:15, when You are speaking about static files such as default and home.html. Where do these come from? And the page at 5:40, it also comes out of nowhere ;) It's quite importaint, because You say that we should copy what's inside default.html to page.ss ;)

by Emill at 02:29am, 20 July 2016

I have the same question as both comment right above this one. Where can I get states files you post at 5:15? I'm really looking forward to learning SilverStripe! Thanks.

by Victor at 12:14pm, 19 October 2016

Never mind. I found the files in the GitHub Repo. For some reason it was not listed prior to submitted my comment.

However, now I have another issue. $ThemeDir resolves to 'themes'

<link href="$ThemeDir/css/style.css" rel="stylesheet" />

resolves to...

<link href="themes/css/style.css" rel="stylesheet" />

Did I miss something?

Thanks for your help in advance.

by Victor at 12:48pm, 19 October 2016

I tried what is said in the first 5 mins and like others the ?flush didn't work. I think it only flushed the cookies of my browser, because I just got logged out of the original SilverStripe template. I could of course remedy the situation by changing the template in the Admin panel.

Anyway, the problem I'm having is that after changing the theme I don't get the "Hello World" page. I just get another page like before saying "Welcome to SilverStripe! This is the default homepage. You can edit this page by opening the CMS....", but without much design to it. It's a very basic one and checking it's source, it says it's getting its sylesheet at "mysite/framework/css/debug.css?m=1471276778". It looks like the Page.ss file doesn't have any effect so SilverStripe is loading something else.

by Samuel Carpentier at 06:21am, 29 October 2016

Hi there,

I would request you to make a tutorial how to install the lesson-1 for the first time. As, I installed the fresh installation of silverstripe and then replaced the theme/ and mysite/ folders of the tutorial in the silverstripe installation and then I got the following error i.e. "SilverStripe Framework requires a $databaseConfig defined."

Before, replacing the folders I was successfully saw the silverstripe new installation with default theme "simple".

Hope you will provide some instructions on it as well.

Cheers, Naveed.

by Naveed Anwar at 05:59pm, 20 November 2016

At 2:05 you say that the "Includes" and "Layout" folders are required unless you are not going to use them. What are those folders used for?

by Trekin at 09:39am, 2 December 2016

Where are the 'static' files coming from? I can't find them... Help please.

by Rod at 09:52pm, 25 September 2017

Thank you for the tutorial. I have followed all of the steps, but I cannot get the new theme to work, or make the contents of the new page.ss appear. What I get is a page with a dark blue header, no nav menu, and the SilverStripe logo on the right. I tested the page.ss in the simple theme with some additional text which appeared when the site's theme was reset to Simple, but with the new theme the text simply reverts to "Welcome to SilverStripe"etc. I am viewing the page in Firefox and Explorer. I don't understand where the narrow header formatting is coming from, and it doesn't seem clear to me where I should be changing the theme- config.yml, config.php or just in the CMS. Some tutorials are suggesting yml, some php. Perhaps I have overlooked something very obvious but I'm banging my head against the monitor in frustration right now.

by MFeaux at 12:32am, 27 September 2017

Stuck on something? Have something to share? Don't be shy!

Keep learning!

Up and Running: Setting up a local SilverStripe dev environment

In this introductory lesson, we cover installing a local webserver (e.g. MAMP), installing and using Composer, and configuring an _ss_environment.php file. Having a finely tuned local...