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.

Migrating static templates into your theme

In this lesson: templates, themes, html, static
SilverStripe version: 4.x (stable)

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.

UncleCheese |

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.htmloff whatever hostname you're using (e.g. http://localhost/), and you should see our home page. Try the same thing forhome.html`.


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 template for this case. Copy the contents of default.html into your templates/ file, which currently contains our "Hello, world" proof-of-concept, and reload your site on the base URL (e.g. http://{your hostname}).

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 browser's inspector dev-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 directory. 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.

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 themes/one-ring/javascript instead of js/. For example, js/common/modernizr.js becomes themes/one-ring/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 themes/one-ring/ to the tags that reference that file.

Everything should be loading correctly now. You can now delete the themes/one-ring/static folder, as we don't need it anymore. We have migrated our static document into a SilverStripe theme.

Related Documentation

Keep learning!

Adding Dynamic Content

In this tutorial, we’ll start using SilverStripe’s native template syntax to inject dynamic content into our site, such as navigation, page titles, CMS content, and...

Working with Multiple Templates

Typically a site has more than one distinct template used across all pages. The home page, for instance, is likely to have a different layout than...

The holder/page pattern

In this tutorial we’re going to focus on the Travel Guides section of our website for this topic. As we can see in the designs, there...