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
12th December 2014

In this tutorial, we’ll migrate a static site into your SilverStripe project. HTML, CSS, and JavaScript will provide a nice common ground and starting point for getting introduced to the design patterns of the framework. Further, designs are commonly delivered to developers in the form of a static site, especially if the theme has been purchased from a thirdparty vendor.

Migrating static templates into your theme

Level: Beginner

Duration: 5:36

In this lesson:

Drop your bags

You know that feeling you get when you’ve been traveling all day, and you finally breach the door to your hotel room? You drop your bags in the first vacant spot you can find, suspending your impending obligation to unpack and get organised, and gift yourself that moment of relaxation.

When migrating a static site into SilverStripe, it is often helpful to follow that same pattern. In this section, we’ll drop all of our HTML and other static assets into their own directory so that they are browseable by our web server and living in our project, albeit as poorly assimilated outsiders. Sure, we’ve still got a lot of “unpacking” to do, but you’ll feel better knowing that everything is where it is supposed to be, under one roof.

Let’s create a directory called static/ in our theme. Again, this label is entirely up to you, so if it’s more meaningful to you to use something like html/, or raw/, feel free to invoke that option.

Your folder structure should now look like this:

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

Now we’ll simply dump the all the contents of our static site into the static/ folder, preserving the file structure. Since we’ve used relative paths for all the assets, having the site deep into the directory structure will not break anything.

Let’s test it out. Navigate your browser to /themes/one-ring/static/default.html off whatever hostname you’re using (e.g. http://localhost:8888/tutorial), and you should see our home page. Try the same thing for home.html.

SS-izing

Now that we’ve dropped our bags and have rewarded ourselves with a quick glimpse of our site in living flesh, it’s time to start cutting up our static site into SilverStripe templates.

Copy and correct

We’ll start with default.html. This mockup is intended to represent the most basic of page types in our site. As discussed earlier, SilverStripe conventionally purposes the Page.ss template for this case. Copy the contents of default.html into your templates/Page.ss file, which currently contains our “Hello, world” proof-of-concept, and reload your site on the base URL (e.g. http://localhost:8888/tutorial).

Look good? No, it shouldn’t. It should look like an unstyled mess. Let’s copy over all the static assets into our theme. Make the following copies:

From To
themes/one-ring/static/css themes/one-ring/css
themes/one-ring/static/js themes/one-ring/javascript
themes/one-ring/static/images themes/one-ring/images
themes/one-ring/static/fonts themes/one-ring/fonts

The easiest place to start is in your Webkit web inspector tool. Click on the Network tab, and refresh. You should see a lot of red. The first thing we notice is that the CSS is not loading properly. The browser is trying to load css/bootstrap.min.css, which is incorrect. Let’s update all of the CSS to load from our theme dir. Make the following changes to all of the stylesheet “href” attributes:

Original New
css/bootstrap.min.css themes/one-ring/css/bootstrap.min.css
css/style.css themes/one-ring/css/style.css

Reload the page, and you should see a bit more style.

Using $ThemeDir

As a matter of best practice, we never want to repetitively hardcode any values in our template that are subject to change. This principle is more commonly referred to as DRY (Don’t Repeat Yourself). We’ll talk more about DRY practices in future tutorials, but for now, our main offender of this rule is the reference to themes/one-ring. SilverStripe provides a global helper variable that returns our current theme directory named $ThemeDir. Replace the references to themes/one-ring with $ThemeDir, as follows:

Original New
themes/one-ring/css/bootstrap.min.css $ThemeDir/css/bootstrap.min.css
themes/one-ring/css/style.css $ThemeDir/css/style.css

Now, if we change our theme, we don’t have to make any updates to the paths in the template.

While the site looks better, a quick glance at the web inspector shows us that there are still a lot of 404s coming through, mostly for our Javascript files. Let’s update all the <script> tags to point to $ThemeDir/javascript instead of js/ . For example, js/common/modernizr.js becomes $ThemeDir/javascript/common/modernizr.js. Most of these updates are at the bottom of the document.

Refresh, and you should see a lot less red in your web inspector. The last 404 we need to fix is logo.png. Simply prepend $ThemeDir/ to the tags that reference that file.

Everything should be loading correctly now. We have migrated our static document into a SilverStripe theme.

Questions and Feedback

I can´t find static resources to do this lesson... Where are the files that appear in the video? (minute 1:25)

by Francisco at 11:01pm, 17 March 2015

Author

Hi, Francisco,

That's the link to the repository, but the static assets should be downloaded separately to follow with the tutorial.

by UncleCheese at 09:45am, 18 March 2015

Hi, Im having problems getting the css etc to load once I transfer the html over the html loads as it should with the expected errors. However once the paths to these files are corrected it does not correct these errors its still coming up with the unsucessul GET 404 error no css styling applied etc. Although it is def showing the paths updated to where they should be pointing. I tried on your example as well as one of my own static sites. Static sites js css etc all load fine when tested prior to switch over to Page.ss doc. Any ideas? Thks Fleur

by fleur at 01:29pm, 26 April 2015

Author

Could you please list the paths that are 404ing?

by UncleCheese at 01:56pm, 27 April 2015

For my test site it is all paths to css js etc although I corrected every single one of them. On the one ring example I have just changed the first two paths the ones to the css to check the effect. See Error code below the paths seem to be correct but css is not kicking in. GET http://localhost/themes/one-ring/css/bootstrap.min.css [HTTP/1.1 404 Not Found 3ms] GET http://localhost/themes/one-ring/css/style.css [HTTP/1.1 404 Not Found 2ms] GET http://localhost/js/common/modernizr.js [HTTP/1.1 404 Not Found 5ms] GET http://localhost/images/logo.png [HTTP/1.1 404 Not Found 519ms] GET http://localhost/js/common/jquery-1.11.1.min.js [HTTP/1.1 404 Not Found 2ms] GET http://localhost/js/common/bootstrap.min.js [HTTP/1.1 404 Not Found 6ms] GET http://localhost/js/common/bootstrap-datepicker.js [HTTP/1.1 404 Not Found 4ms] GET http://localhost/js/common/chosen.min.js [HTTP/1.1 404 Not Found 3ms] GET http://localhost/js/common/bootstrap-checkbox.js [HTTP/1.1 404 Not Found 5ms] GET http://localhost/js/common/nice-scroll.js [HTTP/1.1 404 Not Found 5ms] GET http://localhost/js/common/jquery-browser.js [HTTP/1.1 404 Not Found 5ms] GET http://localhost/js/scripts.js [HTTP/1.1 404 Not Found 5ms] GET http://localhost/js/common/jquery-1.11.1.min.js [HTTP/1.1 404 Not Found 3ms] GET http://localhost/js/common/bootstrap.min.js [HTTP/1.1 404 Not Found 1ms] GET http://localhost/js/common/bootstrap-datepicker.js [HTTP/1.1 404 Not Found 1ms] GET http://localhost/js/common/chosen.min.js [HTTP/1.1 404 Not Found 4ms] GET http://localhost/js/common/bootstrap-checkbox.js [HTTP/1.1 404 Not Found 2ms] GET http://localhost/js/common/nice-scroll.js [HTTP/1.1 404 Not Found 0ms] GET http://localhost/js/common/jquery-browser.js [HTTP/1.1 404 Not Found 1ms] GET http://localhost/js/scripts.js [HTTP/1.1 404 Not Found 2ms]

Thks

by fleur at 03:51pm, 27 April 2015

Author

It seems unusual that you would run the project at the document root. It's not running off a subdirectory or anything, like http://localhost/example?

Feel free to give me a link to download an archive of your website, and I have have a look.

by UncleCheese at 05:53pm, 27 April 2015

Hi there My problem is got to point where one creates the static folder, make it resemble the themes folder and then we add in our site tried to load my full site but my site is in php and nothing happened the hello world was still displaying I changed the site to a simple one page html page with a simple css fiile and again still only seeing hello world I am entering SilverStripe-cms-v3.3.1/themes/star/default.html I changed the config file in mysite to star

please can you tell me what gives :) thanks Elli

by elli at 08:43pm, 1 March 2016

Hello, I seem to be having a problem getting my $ThemeDir to work.

Hard coding the path to my css file works, but does not.

Any help?

by Duncan at 10:46pm, 10 March 2016

Hello, I seem to be having a problem getting my $ThemeDir to work.

Hard coding the path to my css file link rel="stylesheet" href="css/source.css" works, but link rel="stylesheet" href="$ThemeDir/css/source.css" does not.

Any help?

P.S I noticed in my last comment my code was omitted.

by Duncan at 10:48pm, 10 March 2016

Hi there, thanks for your time to write the good tutorial for the beginners. But in writing, here is the mistake that in directory, the dir is showing at the same level with all other directories e.g. , , , ..... etc. and as shown below structure (copied from the tutorial).

  • themes
    • one-ring
    • css
    • images
    • javascript
    • static
    • templates
      • Includes
      • Layout But actually all the folders will come under parent directory. That was the confusion for me when reading the tutorial as I don't use headphones in office. Kindly correct the above structure in the tutorial i.e.
  • themes
    • one-ring
      • css
      • images
      • javascript
      • static
      • templates
        • Includes
        • Layout

Hope this will be helpful for other new comers. Good Luck!

Cheers, Naveed.

by Naveed A. at 01:05pm, 11 May 2016

I have unzipped the one-ring website resources to my themes/one-ring/static directory and this works fine.

My "hello world" theme in themes/one-ring/templates/Page.ss is also working ok.

However, when I overwrite Page.ss with the contents of the resource themes/one-ring/static/default.html, I expected the styling to be lost, but it isn't - the Pages.ss is identical to default.html, even though the stylesheet paths should no longer be valid (I modified the title to distinguish Page.ss from the default.html). Somehow it appears to be finding the stylesheets.

I have discovered that only when I append the command to the url: localhost/silverstripe/?flush, the Page.ss is displayed unstyled, as required. The url changes to http://localhost/silverstripe/Security/login?BackURL=%2Fsilverstripe%2F%3Fflush.

Re-issuing the command localhost/silverstripe/ without the flush command, restores Page.ss to its fully styled page, as if the "flushing" is undone. I thought flushing would permanently clear out the styled page version so that it would display unstyled even without the flush command.

Why must I always issue to flush command to view the unstyled Pages.ss? This seems contrary to your tutorial.

Thanks.

by Dave at 12:13am, 6 July 2017

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

Keep learning!

Creating your first theme

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

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