Converting Themes for SkyBlueCanvas

November 30, 2008

One of the most common questions we are asked is how to convert existing or stock HTML templates to work with SkyBlueCanvas. In this article I will guide you, step-by-step, through the process of adapting any existing skin to work with SkyBlueCanvas. This process, once you understand the fundamentals, usually takes about an hour - sometimes even less. In fact, the skin we will use in this tutorial took only 30 minutes.

For this demonstration I will be using the Eco Theme from ThemeForest.net. Since this is a copyrighted theme, I won’t be able to give you the code for download, but you can purchase the template for only $12 from ThemeForest.net. I selected this theme because it’s beautiful, and it has all of the elements we need to learn how to adapt just about any skin for SkyBlueCanvas.

Eco theme screen shot

The Eco Theme from ThemeForest.net

The Basics

Since all of the HTML, CSS and JavaScript code has already been written by the theme author, our task will involve:

Replacing content blocks with SkyBlueCanvas fragments
Replacing hard-coded page links with SkyBlueCanvas links
Updating CSS and JavaScript links for SkyBlueCanvas

Tip

If you have not read our articles on SkyBlueCanvas Skins and SkyBlueCanvas Fragments, you may want to do so to get a full understanding of how SkyBlueCanvas creates a page.

Before we start, we need to create our skin directory structure. Create a new directory named eco with the following sub-folders:

SkyBlueCanvas Skin directory structure

Next, copy the index.html file from the Eco Theme to your new eco directory and rename it to skin.default.html. Now copy the new eco directory to /skyblue/data/skins/. Be sure to change the file permissions as needed for your hosting environment.

First, we need to add our links to the CSS and JavaScript files. Let’s take a look at the HTML HEAD element:

<head>
<meta http-equiv="Content-Type"
  content="text/html; charset=UTF-8" />
<title>The Eco Company Site Template</title>
<link rel="stylesheet"
  href="css/style.css"
  type="text/css"
  media="screen" />
<script src="js/jquery-1.2.6.js"
  type="text/javascript"></script>
<script src="js/jquery.scrollTo-1.3.3.js"
  type="text/javascript"></script>
<script src="js/jquery.localscroll-1.2.5.js"
  type="text/javascript"></script>
<script src="js/jquery.serialScroll-1.2.1.js"
  type="text/javascript"></script>
<script src="js/coda-slider.js"
type="text/javascript"></script>
</head>

You will notice that the paths for the CSS and JavaScript files all point to the relative paths within the skin directory. These won’t work from the front-end of your site but they are easily updated. I will just show you how to update one JavaScript and one CSS link. The others will be done the same way.

You will need one simple bit of PHP code to get the path to the currently active skin in SkyBlueCanvas:

<?php echo $this->get_path(); ?>

So we just need to add this code before the existing paths in the Eco Theme code:

<head>
<link rel="stylesheet"
  href="<?php echo $this->get_path(); ?>css/style.css"
  type="text/css" media="screen" />
<script src="<?php echo $this->get_path(); ?>js/jquery-1.2.6.js"
  type="text/javascript"></script>
</head>

Next, let’s tackle the header. This will be very easy. I will give you the code, then explain it.

<div id="logo">
  <h1><a href="[[site.url]]”>
    <img src=”images/logo.gif” alt=”[[site.name]] logo” />
  </a></h1>
</div>

That’s it. All we have done is replaced the hard-coded URL of the home page and the site name with two SiteVars. Now, when our page is rendered, SkyBlueCanvas will replace these with the values you set in the SkyBlueCanvas admin.

Tip

You can find a full list of SiteVars in our article about the
SkyBlueCanvas SiteVars Plugin.

Now we will do the same for the Contacts region of the header:

<div id="contacts">
  <!-- Contact informations here -->
  <p>
    Call us at [[site.contact_phone]] <br />
    <a href=”mailto:[[site.contact_email]]”>
      [[site.contact_email]]
    </a>
  </p>
  <!– End of Contact informations –>
</div>

Next, let’s replace the hard-coded dynamic content blocks. Converting content blocks involves two SkyBlueCanvas concepts: Fragments and SiteVars (which we already mentioned). Fragments are scriptlets that render a particular kind of content - like a Links List - created by SkyBlueCanvas. SiteVars are tokens that refer to settings or values that you set in the SkyBlueCanvas admin. They allow you to change values related to your site, without having to change your HTML every time you update your site settings.

In the Eco Theme index.html file, we find the following code for the header and navigation:

<div id="header">
  <div id="logo">
    <h1><a href="index.html">
      <img src="images/logo.gif"
        alt="The Eco Company Site Template logo" />
      </a></h1>
  </div>
  <div id="contacts">
    <!-- Contact informations here -->
    <p>
      Call us on 001123456 <br />
      <a href="mailto:info@ecocompany-theme.com">
        info@ecocompany-theme.com
      </a>
    </p>
    <!-- End of Contact informations -->
  </div>
  <div class="clear"></div>
  <ul id="mainmenu">
   <!-- Put your menu links here -->
   <li><a href="index.html">Home</a></li>
   <li><a href="about-us.html">About Us</a></li>
   <li><a href="#">Services</a></li>
   <li><a href="#">Partners</a></li>
   <li><a href="contact.html">Contact</a></li>
   <!-- End of menu links -->
  </ul>
</div>

You can update the contact info using SiteVars like I explained earlier. We will replace the navigation with a fragment to be dynamically updated as we add and delete pages from our site. But you don’t need to write a fragment. You can simply download this fragment set: Fragments and copy the entire directory to /skyblue/data/skins/eco/.

After you have downloaded the fragment, we need to make one small change to the menu fragment. So open /fragments/menu/view.php and Find the line that reads <ul> and change it to:

<ul id="mainmenu">

We have simply added an ID to the UL element to match the Eco Theme style rules. I could have done this for you, but I wanted you to learn how to modify a fragment to match the template you are converting.

Now we can finish the header by adding the code to load the fragment when the page is created. We do that like this:

<div id="header">
  <div id="logo">
    <h1><a href="[[site.url]]”>
      <img src=”images/logo.gif” alt=”[[site.name]] logo” />
    </a></h1>
  </div>
  <div id=”contacts”>
      <!– Contact informations here –>
    <p>
      Call us at [[site.contact_phone]] <br />
      <a href=”mailto:[[site.contact_email]]”>
        [[site.contact_email]]
      </a>
    </p>
    <!– End of Contact informations –>
  </div>
  <div class=”clear”></div>
  <!–#plugin:fragment(menu,view)–>
</div>

Now our header is finished. If you are starting to suspect that this is pretty easy - you are right - it is.

I want to focus on helping you learn the concepts not convert a specific theme so we are going to skip the Scrolling Banner section for now. I have included the fragment required for that section in the file you just downloaded.

The Main Content

The main content, or body of a standard text page is created and edited in the WYSIWYG text editor in the Page Manager. We only need to tell SkyBlueCanvas where to place the content. This is accomplished using the Page Fragment that is included in the fragments download from earlier in this article.

The Page Fragment is just like any other fragment and is loaded the same way. So find the region of the Eco theme that the designer has designated as the maincontent area.

<div id="main">
  <div id="sidebar">
    <!-- We will come back to the side bar shortly -->
  </div>

  <div id="text">
    <!-- Put your text here -->

    <!-- End of Text -->
  </div>
</div>

The designer, Darinka, has conveniently labeled the content area with a comment indicating that to “Put your text here”, so that is what we will do. So delete the sample content she has placed between the comments, with our Page Fragment call like this:

<div id="main">
  <div id="sidebar">
    <!-- We will come back to this -->
  </div>

  <div id="text">
    <!-- Put your text here -->
    <!--#plugin:fragment(page,view)-->
    <!-- End of Text -->
  </div>
</div>

Now, when SkyBlueCanvas builds the page, it will replace the fragment call with the text we created for this page in the Page Manager.

The Side Bar

The side bar provides us with a good opportunity to talk a little about the usefulness of fragments and how to plan your pages when building or converting a skin for SkyBlueCanvas. We want updating our site to be as little work as possible. This means avoiding repeating or duplicating tasks and code. In fact, there is a concept in programming called DRY.

Fragments allow us to write a single piece of code for regions of a page that will be the same for every page and every type of page. Typically our header, footer and often the side bar will be the same for every page, so we don’t want to duplicate the same code for every layout type we have. We can simply create a fragment and load the fragment in each layout style.

There is also even better news - fragments can be nested, so your fragments can also load fragments. For instance, if our side bar will include a Links List, we can have a side bar fragment which includes a fragment call to load the Links fragment. And this is exactly what we are going to create now.

I purposefully did not include the Sidebar Fragment in the download I gave you. I want you to experience writing a fragment of your own - and this is a very simple one.

Inside the /skyblue/data/skins/eco/fragments/ folder, create a new folder named sidebar. Inside of this folder we need to create a sinlge PHP file named view.php. View is the name of the default HTML output agent in a fragment. You can have an unlimited number of agents and you can name them anything you like, but we will use view for this example.

We want to inlude our Links List in the side bar, so our Sidebar Fragment View File needs to inlude the call to the Links Fragment. You are probably catching on by now and already know that we do this with the following code:

<!--#plugin:fragment(links,view)-->

Now you simply save the file. But wait, we have not actually called the Sidebar Fragment from within our page yet. We need to go back a bit and re-visit the code we modified to load the page text, and - as you probably guessed - add a fragment call to our Sidebar Fragment like this:

<div id="main">
  <div id="sidebar">
    <!--#plugin:fragment(sidebar,view)-->
  </div>

  <div id="text">
    <!-- Put your text here -->
    <!--#plugin:fragment(page,view)-->
    <!-- End of Text -->
  </div>
</div>

If you recall, I said that view.php is the default view of a fragment. So in our code above, the second parameter ‘view’, is not really necessary. We can load the default fragment view by simply calling:

<!--#plugin:fragment(sidebar)-->

The rest of this page, and the other page layouts can be converted in the same way that we have converted the elements above. I will leave the remaining elements and pages to you. You now have all of the tools you need to convert just about any HTML theme to work with SkyBlueCanvas.

Since I know this is your first theme conversion, I’m sure you will have questions. Please feel free to post questions in the SkyBlueCanvas Forum. I try to respond within 24 hours and usually much sooner than that.

A Few Caveats

In this article we covered converting a basic text page template for SkyBlueCanvas. What we did not cover, however, is how to create a layout for a contact form, photo gallery or other content page that includes non-text content in the body of the page.

This is actually quite easy to do, and there are two ways to do it. Whether your non-text page is a contact form, photo gallery or perhaps a Flash animation, they are all fragments and therefor loaded in the same way as every other fragment.

You have a choice with these fragments. You can create a new page layout that is specific to the content - skin.contact.html - for instance, or you can just load the fragment in a standard text page, thus using only a single layout file.

Required Skin Structure

As you may be aware, in v1.1 we changed the way SkyBlueCanvas skins and content publishing works. The new format gives the site designer much greater flexibility and makes content publishing simpler for the site owner. We did not want to break compatibility with the old skin format so SkyBlueCanvas can still deal with both. In order to determine which skin format is being used, SkyBlueCanvas looks for the HTML closing tag </html> in the skin for whichever page is being rendered. If the closing tag is not present, SkyBlueCanvas assumes the skin is a legacy skin.

What this means to you when building a skin is that if you are building a skin following the new format (which you most likely will be), you must include the </html> tag in the skin.{skin_name}.html file (as opposed to in a fragment).

Standard Page Approach

If you want to use a single page layout for all of your pages, you can create non-text or text and fragment pages, by using the in-text fragment call to load your fragment. It is very simple to do. Create a new page, for instance Contact, then in the text editor in the Page Manager,include the following token:

{plugin:fragment(contacts,view)}

Content-specific Layout Approach

If you prefer to use a content-specific layout (or page type), you can simply duplicate your standard page, but rather than include the page fragment call in the main content area:

<!--#plugin:fragment(page,view)-->

Replace it with the call to the fragment for that page:

<!--#plugin:fragment(contacts,view)-->

And that’s it. You now know how to convert just about any HTML theme, with an unlimited number of layouts, to work with SkyBlueCanvas.

A Final Note

In Admin > Pages > Editor, you will find a Page Type selector on the Meta Data tab. The options in this selector correspond to your HTML layout files. So if you have two layouts, skin.default.html and skin.contact.html, the Page Type selector will have the options default and contact. You will need to be sure to select the Page Type you wish SkyBlueCanvas to use to build each page.

Discussion

[...] SkyBlueCanvas - Converting HMTL Themes for SkyBlueCanvas John Comment RSS « Free CSS Website Templates & Resources [...]

Tired Robot » Blog Archive » SkyBlueCanvas - Lightweight CMS | February 2, 2009, 9:52 am