SkyBlueCanvas» Fragmentor Plugin for SkyBlueCanvas – SkyBlueCanvas

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.

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 v1.1 RC1 Skins Explained

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

SkyBlueCanvas v1.1 RC1 Skins Explained

If you have used an earlier release of SkyBlueCanvas and are now upgrading to v1.1 RC1, you have probably noticed that the skins are a bit different. Normally, I would not want to make a change with as much impact on existing users as this one, but the change was really necessary.

This article will explain the underlying concepts of the new skin format and the API hooks at your disposal. For users of older versions of SkyBlueCanvas, your existing skins will still work. There are some minor caveats to this that I will explain later on.

Push vs. Pull Content Publishing

The old skin format used a “Push” method of publishing. What this means is that you specify what content items are published in what region of a page from within the Admin Control panel. This technique has many benefits, but, unfortunately, it also has many limitations.

The main problem with a push technique is that too much knowledge of the presentation of the data is attached to the data itself. This is generally frowned upon in software development because it does not allow the content to be easily published in other formats such as RSS, Mobile devices, etc.

The new skin format uses a “Pull” method of content publishing. This is widely accepted as the “correct” way to publish content from any type of content creation/management system. As with the push method, this technique has both advantages and disadvantages. However, the advantages of a pull method far outweigh the disadvantages.

The Disadvantages

The primary disadvantage of the pull method is that setting up skins is a bit more work and requires a higher level of technical skills. In SkyBlueCanvas, we have tried to minimize the extra labor as much as possible.

The other main disadvantage is that a new template is required for each “type” of content. For instance, a Photo Gallery page will require it’s own template. We are working on a solution to do away with this requirement but for now, this requirement will have to stand.

The Advantages

The biggest advantage, and in my opinion, the one that outweighs every other consideration, is the unlimited flexibility that the pull method affords the designer and developer. There are literally no limitations on what you can do.

Using the pull method of publishing, all knowledge of presentation is removed from the data itself. This means that you can create multiple (even unlimited) views of the same data. It also means that the format of the data can be anything you want or need it to be. The same data can be delivered as XML, RSS, HTML or any other format.

Fragments

The key to the new skin format 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.

You can find a full tutorial on Fragments in the post about Fragments

Basic Skin Structure

The basic structure of a SkyBlueCanvas skin is the same as any other HTML page. It is also almost identical to the old SkyBlueCanvas skin structure expect that it includes the full HTML document including the Doc Type declaration and HEAD and BODY elements.



    
        Page Title

The code above simply defines the structure of your HTML skin. It does not include any content or resource links (JavaScript or CSS) or meta data. We’re going to add these – in dynamic fashion – now.

First, we will want to add our meta data. The meta data for pages is managed both page-by-page in the Page Manager and through Admin > Collections > Meta Data. This means you can add, edit and delete meta data items and they are updated on your site automatically. To load the meta data, you need only a single function call, inserted in the HEAD element of the page like this:


    Page Title
    
    get_meta_data(); ?>

That’s all there is to it. And most features of the SkyBlueCanvas skin will be equally as simple. So let’s move on to loading JavaScript and CSS links. These will also be inserted in the HEAD element.


    Page Title
    
    get_meta_data(); ?>

The get_path(); ?> function automatically fills in the path to the current skin so if you want to create a new skin based on the current structure, all you need to do is copy the HTML file to the new skin folder and you won’t even need to update the paths.

Ok, so now for the really hard part. Just kidding. This part is a bit different but just as simple. Now we want to load the page content. This example will be for a basic text page created in Admin > Pages. I will use the full HTML document for this example so you can see a fully-functional page:



    
        Page Title

That was pretty easy wasn’t it?

Now, let’s go ahead and put our full page together with navigation, a sidebar and header and footer:



    
        Page Title

Now, just save the above code to /skyblue_root/data/skins/your_skin/skin.standard.html

To use this template for a page, go to Admin > Pages and create a new page. Enter your page text. Then on the Meta Data tab, set the Page Type to “standard”. When your new pages is requested, SkyBlueCanvas will use the template we created to build the page.

One final example will help round out your understanding of SkyBlueCanvas skins. This part is a little more difficult but still very simple. The example we have used so far only works for pages whose page type is set to Standard. What if you want a Gallery page?

You will need to read the article on Fragments in order to fully understand how this is done, but the page template itself, is almost identical to the Standard page, with one small change. Rather than including:

in the main content region, you will include:

Full List of Template Hooks:

// Load the page meta data:

$this->get_meta_data();

// Getting the Skin root path:

$this->get_path();

// Getting the page title:

$this->get_page_title();

// Get the home page URL:

$this->get_home_url();

// Get the page name as a CSS ID:

$this->get_page_name();

SkyBlueCanvas also has some additional hooks via the SiteVars plugin. The full list is beyond the scope of this article, but you can learn more in the blog post about SiteVars.