SkyBlueCanvas» Converting Themes for SkyBlueCanvas – SkyBlueCanvas

Converting Themes for SkyBlueCanvas

scott — Sun, 30 Nov 2008 20:14:19 +0000

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.

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:

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:



The Eco Company Site Template

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:

get_path(); ?>

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

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

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:


  
  
    Call us at [[site.contact_phone]] 

    
      [[site.contact_email]]

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:


  
    
      
      
  
  
    
    
      Call us on 001123456 

      
        info@ecocompany-theme.com
      
    
    
  
  
  
   
   Home
   About Us
   Services
   Partners
   Contact

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

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:


  
    
      
    
  
  
      
    
      Call us at [[site.contact_phone]] 

      
        [[site.contact_email]]

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.

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:

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:

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:

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:

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

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

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.

Creating Menus in SkyBlueCanvas v1.1

scott — Thu, 27 Nov 2008 17:58:40 +0000

When you create a new page in SkyBlueCanvas, a menu item is already created for you. In fact, there is not really a menu item to create because the system assumes, by default, that if you have created a page, there should be a menu link to it. I mean, how else would anyone find your page if there is no link, right?

The only trouble is, which menu should the new page go in? This is where you will have to give SkyBlueCanvas a little help. On the Meta Data tab in the Page Manager (Admin > Pages > Edit), you will see a selector field labeled Menu. You simply select the menu in which you want the page to appear.

There are two logical next questions that you may have. (1) How do I create a new menu? (2) How does the menu get placed on a page? In this article I will answer these two questions.

The answer to question (1), “How do I create a new menu?” is very simple. You simply navigate to Admin > Collections > Menus. From the list view, click the “Add” button. In the form that appears:

provide the requested information.

Note

The Menu Type property has been deprecated so you do not need to complete this field.

Tip

You will need to know the numeric ID of the new menu so make note of it and hold onto it.

Then click Save.

No you can go back to Admin > Pages > Edit (your page) and on the Meta Data tab, select your new menu from the options list and save your page.

You have now successfully created a new menu and added a page (menu item) to the new menu.

Displaying a Menu

Displaying your menu involves two other concepts in SkyBlueCanvas: templates and fragments.

Templates and fragments make up the presentation or “view” portion of your web page. They are where you define the HTML structure of pages (templates) and collections or content types (fragments). They may be a little tricky to grasp at first, but once you understand them, they are very powerful and flexible.

Your SkyBlueCanvas installation, provided you are using v1.1 RC1 or later, should already have a Menu Fragment included. We are going to modify this fragment, or add to it rather, first.

Using your FTP client, navigate to /skyblue_root/data/skins/techjunie/fragments/menu/ and make a copy of view.php. Name the new file mymenu.php. Then open the file with the text editor of your choice.

Tip

If you have installed your own skin, you can simply copy /skyblue_root/data/skins/techjunkie/fragments/ to your new skin.

In the file mymenu.php you will see the following code:

That looks pretty simple, huh?

We are going to need to modify the code a little bit but I promise it will be painless- and I will give you the full code when we are finished.

SkyBlueCanvas will know that this is a menu fragment (more on this later) so the menu items (actually the pages) will already be available to your code in the $data variable. We will only need to manually retrieve our new menu.

Now you can refer back to the Menu ID I asked you to hold onto.

SelectObj(
    $Core->xmlHandler->ParserMain(SB_XML_DIR . "menus.xml"),
    $my_menu_id
  );
?>

Now we have our menu items and our new menu. We can start building the menu HTML.

We will start with a basic HTML structure:


  showtitle) : ?>
  title; ?>

That’s not too bad. We are almost finished building our menu HTML. Now all we need to do is loop through the $data list, and display each of the items in our menu. Here is how the looping is done:

We only want to show links to pages that are published, so we will add a single line to make sure the menu item can be displayed:

Now we want to filter the $data items to only show items in our new menu. We do this with a single line of code:

  
  
  menu != $menu->id) continue ; ?>

Wow! That was pretty easy and we are moving right along …

The only thing we have left to do is display the menu item:

  
  
  menu == $my_menu_id) continue ; ?>
  >

And believe it or not, you have just built a new menu, as well as your first SkyBlueCanvas Fragment. There is only one last step, and this one is the simplest of all.

Up to this point, we have created a new Menu object in the SkyBlueCanvas admin and written a new menu Fragment. The only thing that remains is to tell SkyBlueCanvas where to display the fragment. To do this, go to /skyblue_root/data/skins/techjunkie/ (or your skin) and open skin.text.html in your text editor. You will see the following code:



  
    [[page.title]]
    
    get_meta_data(); ?>

Notice the lines that look like this:

These tokens are the code that tell SkyBlueCanvas where to load a fragment, which fragment to load, and which view (PHP file) to load. So the only thing you need to do is add a token for your new menu in the location in the HTML where you want the menu to appear. Let’s assume you want your new menu to appear at the top of the sidebar. You will change the code to look like this:

Now test your new menu by pointing your browser to your web site. Your new menu should appear at the top of the sidebar.

Note

You will need to make this change for all of the skins HTML files, skin.contacts.html and skin.standard.html.

SkyBlueCanvas Fragments Explained

scott — Wed, 26 Nov 2008 06:18:14 +0000

The key buidling dynamic content into a SkyBlueCanvas site is what we call fragments. An easy way to think about fragments is as a piece of a page. The fragment code creates the HTML for a particular data type. For instance, if you have a collection of Links you want to display on your site, the Links Fragment will take care of generating the HTML. One neat thing about fragments, though, is that a single fragment can have numerous different HTML formats.

Creating a basic fragment is pretty simple. You simply go to /your_skyblue_root/data/skins/your_skin/ and create a new folder named fragments. Inside this folder, you create another folder named links. There are two pre-defined files that you can create in this folder but both are optional.

functions.php

If you create a file named functions.php in your /fragments/your_fragment/ folder, SkyBlueCanvas will load this file automatically before loading your fragment. This allows you to creat more robust fragments without cluttering your presentation code with a lot of logic.

view.php

view.php is the default fragment view name. You can name your views anything you like. The significance of the view.php file will be explained a little later on when we talk about Loading Fragments in a web page.

By default, SkyBlueCanvas will attempt to figure out which data set to make available to your fragment view. It does this by matching the fragment name (for instance Links) with an existing data set. If the fragment name correspongs to an Admin Manager name, that data set will be loaded and made available to your fragment view in a variable named $data. For very simple fragments that use a single data set, this means you don’t need to write any code to retrieve the data set.

About Data Sets

SkyBlueCanvas stores data objects in an XML file named according to the Admin Manager that manages that data set. Using our Links Manager as an example, SkyBlueCanvas stores Links data in /skyblue_root/data/xml/links.xml.

If the Admin Manager also has groups associated with the data objects, then the data is usually stored in a file named [data]groups.xml. Again using the Links Manager as an example, the Links Groups are stored in /skyblue_root/data/xml/linksgroups.xml.

A Simple Example

Theory is wonderful, but examples are perhaps more useful so let’s create a simple fragment so you can get the hang of it.

If you do not have a folder named fragments in your skin folder, create it now. Inside that directory, create a new directory named links. The, inside the links folder, create two PHP files: functions.php and view.php.

This is not a lesson on writing PHP, so I will just give you the code to paste into functions.php:

published)) {
      array_push($pub, $item);
    }
    else if ($item->published) {
      array_push($item->published);
    }
  }
  return $pub;
}

function get_items(&$group, $items) {
  $items = get_published($items);
  $these = array();
  foreach ($items as $item) {
    if ($item->group == $group->id) {
    if ($item->groups == $group->id) {
      array_push($these, $item);
    }
  }
  return $these;
}

?>

The View

The view is where the data items are transformed into HTML. A little bit of PHP is required, however, to make sure we have all the data we need. So past the following code into view.php:

xmlHandler->ParserMain(
      "data/xml/linksgroups.xml"
    )
  );

  $items = get_published($data);
  unset($data);
?>

This code is very easy to understand. First, we declare the Core and Filter objects as global. This allows us to access these items which were created in the global scope of the PHP script (index.php).

in the next section of the code, we are getting all of the published groups, by calling get_published (from functions.php) with the output of the xmlHandler.

In the last piece of code, we are fitlering our complete list of data items in $data, by getting the published links with get_published.

Then, just for good house-keeping, we unset the $data variable because it is no longer needed.

The Output

The next bit creates the actual output using our data items and groups.

Let’s look at this block of code in smaller pieces. In the outer-most block of code, we are simply looping through all of the groups. Each pass through the loop, the next group is stored in the $group variable so we can access it’s data.

In the next block, we are retrieving all of the items in the current group:

And finally, we loop through each item in $items. Each pass through the loop, the next item is stored in the $item variable.

You will notice that there is HTML code mixed with the PHP code. When view.php is loaded, the PHP will be executed and merged with the HTML.

The Full Code

xmlHandler->ParserMain(
      "data/xml/linksgroups.xml"
    )
  );

  $items = get_published($data);
  unset($data);
?>

  
    
    name; ?>
    
    
      
        
          
            name; ?>

Loading Fragments

Well, the hard part is over. All we need to do now is tell SkyBlueCanvas where to load the fragment. This is very easy and there are two ways to do it.

You can load fragments as part of a template or within the body (text) of a page. To load a fragment as part of the template, you simply include the following code in the the desired location of the template:

If you recall, however, I stated earlier that view.php is the default view file, so the view argument in the code just given is not needed. So you can load the links fragment with this code:

If you want to display your links in the body of a page or text article, you can do so by inserting the following token in the body of your page text:

{plugin:fragment(links)}

You can try this technique out by going to Admin > Pages and inserting the token above in the page text.

Caveats

In order for the fragments to work, you will need to make sure that the PluginParser and FragmentsPlugin are enabled. To do this, go to Admin > Collections > Plugins and make sure plugin.parser.php and plugin.fragments.php are loaded.