Fragmentor Plugin for SkyBlueCanvas

scott — Sun, 08 Mar 2009 01:19:46 +0000

For a really cool Fragmentor usage example, check out my blog post on the Editable Sidebar Content Hack

System Requirements

SkyBlueCanvas v1.1
PHP 5 (Not tested with PHP 4)
Apache Web Server

Important

Unlike most SkyBlueCanvas Plugins, the Fragmentor Plugin must be installed manually via FTP. If you install this Plugin through the admin console, it will not function properly.

Installation Instructions

Connect to your SkyBlueCanvas web site using the FTP Client of your choice.
Locate the Fragmentor Plugin file in source/plugin_fragmentor/plugin.fragmentor.php in this download.
Upload the Fragmentor Plugin file to /skyblue_root/data/plugins/.

Usage

The Fragmentor Plugin allows you to pass a standard query string, similar to a URL query string, to your custom SkyBlueCanvas fragments. A query string is simply a string of key=>value pairs in the format:

key1=value1&key2=value2

Reserved Keywords

The Fragmentor Plugin has 2 reserved keywords:

name – name tells Fragmentor which Fragment to laod.
view – view tells Fragmentor which Fragment View to load.

Syntax

You can use one of or a mix of two call syntaxes to call the Fragmentor Plugin:

HTML Comment Syntax:

Use this syntax to add Fragmentor calls to your HTML skin templates.

In-line Text Syntax:

{fragment(name=fragment_name&view=view_name&key1=value1)}

Use this syntax to add Fragmentor calls in-line in your page article text.

If you are familiar with SkyBlueCanvas Fragments, you know that the default Fragment Plugin attempts to load any data objects associated with the fragment automatically. The plugin determines the data to load based on the name of the fragment. For instance, if you have the Links Manager installed on your SkyBlueCanvas site, and you create a fragment named links, the Fragment Plugin will automatically load the links data objects. The data objects are passed to your fragment in a variable named $data;

Fragmentor maintains this automatic data loading and your data is still passed in the $data variable. Fragmentor, however, adds a new variabled named $params which is a keyed (associative) array corresponding to the key=>value pairs of your query string.

Your query string can contain as many key=>value pairs as you like and your key names can be anything you like. The only limitations are:

The name and view keywords are reserved by the plugin
Your query string must be a well-formed query string meaning it must follow the rules or a standard URL query string (no spaces, no special characters, etc.)

Important

Existing SkyBlueCanvas fragments are not currently configured to work with the Fragmentor Plugin. Fragmentor is intended to give you more flexibility in creating your custom plugins. We may eventually merge Fragmentor with the core SkyBlueCanvas code but at the present time it should be considered and treated like any other third-party add-on.

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.

SkyBlueCanvas » Fragmentor Plugin for SkyBlueCanvas – SkyBlueCanvas

Fragmentor Plugin for SkyBlueCanvas

System Requirements

Important

Installation Instructions

Usage

Reserved Keywords

Syntax

HTML Comment Syntax:

In-line Text Syntax:

Important

Converting Themes for SkyBlueCanvas

The Basics

Tip

Tip

The Main Content

The Side Bar

A Few Caveats

Required Skin Structure

Standard Page Approach

Content-specific Layout Approach

A Final Note