System Requirements

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

Installation Instructions

1. Connect to your SkyBlueCanvas web site using the FTP Client of your choice.
2. Locate the Fragmentor Plugin file in source/plugin_fragmentor/plugin.fragmentor.php in this download.
3. 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:

1. name – name tells Fragmentor which Fragment to laod.
2. 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:

<!--fragment(name=fragment_name&view=view_name&key1=value1)-->

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:

1. The name and view keywords are reserved by the plugin
2. 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.)

A few nights ago, Steve Fister, one of the SkyblueCanvas Development Team Members posed the question again and offered a few ideas on how to pull it off. After thinking about Steve’s suggetions, I realized that this is actually quite easy to do. In fact, with Steve’s idea, you can add an editable text block anywhere on a web page. What’s more, with a little SkyBlueCanvas Skin Magic, you can build page-specific text blocks, so if you want a different block of text to appear on different pages, you can do it with this trick.

Out-of-the-box, this is still not possible with SkyBlueCanvas, but I have been working on a new Plugin that – unbeknownst to me when I built it – is the missing piece. The plugin is called Fragmentor and is a super-charged version of the Fragment Plugin that comes pre-installed with SkyBlueCanvas.

About Fragmentor

The existing Fragment Plugin has one design limitation: it uses pre-defined parameters whose meaning is determined by both position and name. I built the super-charged Fragmentor Plugin to correct this design mistake and to make the plugin much more flexible.

Whereas one would load a Fragment with the old Fragment Plugin with a call like this:

<!--#plugin:fragment(fragment_name,view_name,
    match_param[id1,id2,...],
    page=[id1,id2,...]})-->

The new plugin uses a query string of key=>value pairs much like a URL query string that looks like this:

{fragment(name=fragment_name&view=view_name
    &param1=value1&param2=value2)}

There are 3 benefits of this approach:

1. The position of parameters is irrelevant
2. The query string can contain an arbitrary number of key=>value pairs
3. Only your fragment needs to understand the optional parameters*

* There are two exceptions to this rule: the name and view keywords are reserved. Some might call this a shortcoming but I tend to disagree. Every language, whether for markup or code execution, uses reserved keywords so we are not introducing a new concept by reserving these two keywords.

The Editable Text Anywhere Trick.

What You Will Need

• The Editable Region Hack Package Download
• Basic PHP and HTML know-how
• A SkyBlueCanvas web site
• FTP access to your site
• A text editor

First, download the Editable Region Hack Package. Follow the installation instructions included with the download.

Next, open one of your SkyBlueCanvas Skins in a text editor. We are going to use the sidebar for this demonstration, so in the sidebar of your template, add the following code:

{fragment(name=region&view=view
    &content_id=
    <?php $this->get_page_name(); ?>-sidebar)}

For the time being, don’t worry about what this code means. After we have created our content item to display in the region, I will explain how this code works.

Now for the Trick

We are actually going to use a SkyBlueCanvas Page for our editable content that goes in this region. However, we will only be using the Page Menu Text and the Page Article Text in the region. The reason we created an empty Skin File was so our page does not get rendered as a full HTML document.

The Page Menu Text is what SkyBlueCanvas’s Router Class uses as it’s unique identifier, so we will need to use this as well. The Fragment code I told you not to worry about earlier comes into play now. If you look at the code, you will see a PHP call embedded in the Fragment call. When this page is loaded, the template PHP will be parsed before the Plugins are fired, so when the Fragmentor Plugin sees this page, the PHP code will be replaced by the Menu Text or unique identifier of the current page. So if we are currently viewing the “Home Page”, the final key=>value pair in our query string will actually read:

content_id=home-page-sidebar

This is critical in order for the trick to work.

The Finale

With all of our pieces in place, log into the admin section of your site and navigate to Admin > Pages and click the Add Page button. Once in the Page Form View, click the Meta Tab and name your content item Home Page Sidebar.

In the selector labeled Layout, select Region. This tells SkyBlueCanvas to use our empty Region Skin to build this page. Since the Region Skin is empty, the only output of the page will be the article cotnent.

In the selector labeled Menu, select No Menu (this is important).

Set Published to No.

You can choose to syndicate this content item.

Finally, click the Article Text tab and enter text and images the same as you would on a SkyBlueCanvas page. Once you have finished entering your text, click the Save button, then view your home page. You should see your newly created content in the side bar.

Important

We are exploiting SkyBlueCanvas’s Unique Identifier format to match content items with the including page so it is critical that your editable region content Menu Text match the Menu Text of the including page exactly, except for the additional ’sidebar’ bit.

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.

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.

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

<?php
  global $Router;
  global $Filter;
?>
<div class="horizontal-menu">
  <?php if (count($data)) : ?>
  <ul>
    <?php foreach ($data as $item) : ?>
    <?php if (not_valid_menu($item)) continue; ?>
    <li<?php the_class($item); ?>>
      <a href="<?php the_link($item); ?>">
          <?php the_text($item); ?></a>
    </li>
    <?php endforeach; ?>
  </ul>
  <?php endif; ?>
</div>

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.

<?php

  /*
  * Set this to the ID of the menu you created
  */

  $my_menu_id = 3;

  /*
  * Get the new menu from storage
  */

  $menu = $Core->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:

<div class="mymenu">
  <?php if ($menu->showtitle) : ?>
  <h2><?php echo $menu->title; ?></h2>
  <?php endif; ?>
  <ul class="verticalmenu">

  </ul>
</div>

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:

  <?php foreach ($data as $item) : >

  <?php endforeach; ?>

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:

  <?php foreach ($data as $item) : >
  <?php if (not_valid_menu($item)) continue; ?>

  <?php endforeach; ?>

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:

  <?php foreach ($data as $item) : >
  <?php if (not_valid_menu($item)) continue; ?>
  <?php if ($item->menu != $menu->id) continue ; ?>

  <?php endforeach; ?>

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

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

  <?php foreach ($data as $item) : >
  <?php if (not_valid_menu($item)) continue; ?>
  <?php if (!$item->menu == $my_menu_id) continue ; ?>
  <li<?php the_class($item); ?>>
    <a href="<?php the_link($item); ?>">
        <?php the_text($item); ?></a>
  </li>
  <?php endforeach; ?>

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:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" {doc:lang}>
  <head>
    <title>[[page.title]]</title>
    <meta http-equiv="Content-Type"
      content="text/html;charset=UTF-8" />
    <?php echo $this->get_meta_data(); ?>
    <link rel="stylesheet"
    type="text/css"
    href="<?php echo $this->get_path(); ?>css/TechJunkie.css" />
    <!--#plugin.preloader-->
  </head>
  <body id="homepage">
    <div id="wrap">
      <!--#plugin:fragment(header)-->
      <div id="menu">
        <!--#plugin:fragment(menu,view,menu=1)-->
      </div>
      <div id="content-wrap">
        <div id="main">
          <!--#plugin:fragment(page,view)-->
        </div>
        <div id="sidebar">
          <!--#plugin:fragment(sidebar)-->
        </div>
      </div>
      <div id="footer-wrap">
        <!--#plugin:fragment(footer)-->
      </div>
    </div>
  </body>
</html>

Notice the lines that look like this:

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

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:

 <!--#plugin:fragment(menu,mymenu)-->

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

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:

<?php

function get_published(&$items) {
  $pub = array();
  foreach ($items as $item) {
    if (!isset($item->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:

<?php
  global $Core;
  global $Filter;

  $groups = get_published(
    $Core->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.

<div>
  <?php foreach ($groups as $group) : ?>
    <?php $data = get_items($group, $items); ?>
    <h2>
      <?php echo $group->name; ?>
    </h2>
    <ul class="links">
      <?php if (count($data)) : ?>
        <?php foreach ($data as $obj) : ?>
          <li>
            <a href="<?php echo $obj->url; ?>">
              <?php echo $obj->name; ?>
            </a>
          </li>
        <?php endforeach; ?>
      <?php endif; ?>
    </ul>
  <?php endforeach; ?>
</div>

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.

<div>
  <?php foreach ($groups as $group) : ?>

  <?php endforeach; ?>
</div>

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

<div>
  <?php foreach ($groups as $group) : ?>
    <?php $data = get_items($group, $items); ?>

  <?php endforeach; ?>
</div>

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

<div>
  <?php foreach ($groups as $group) : ?>
    <?php $data = get_items($group, $items); ?>
    <h2><?php echo $group->name; ?></h2>
    <ul class="links">
      <?php if (count($data)) : ?>
        <?php foreach ($data as $obj) : ?>
          <li>
            <a href="<?php echo $obj->url; ?>">
              <?php echo $obj->name; ?>
            </a>
          </li>
        <?php endforeach; ?>
      <?php endif; ?>
    </ul>
  <?php endforeach; ?>
</div>

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

<?php
  global $Core;
  global $Filter;

  $groups = get_published(
    $Core->xmlHandler->ParserMain(
      "data/xml/linksgroups.xml"
    )
  );

  $items = get_published($data);
  unset($data);
?>
<div>
  <?php foreach ($groups as $group) : ?>
    <?php $data = get_items($group, $items); ?>
    <h2><?php echo $group->name; ?></h2>
    <ul class="links">
    <?php if (count($data)) : ?>
      <?php foreach ($data as $obj) : ?>
        <li>
          <a href="<?php echo $obj->url; ?>">
            <?php echo $obj->name; ?>
          </a>
        </li>
      <?php endforeach; ?>
    <?php endif; ?>
    </ul>
  <?php endforeach; ?>
</div>

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:

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

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:

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

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.