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.

Download It Now

How It Works

Let’s say you have your phone number littered throughout your web site. If your phone number ever changes, you would normally have to find and change every instance of the phone number on your site. With the MyVars extension and plugin, you can set your phone number in one place, and use a simple string replacement token to have the phone number automatically update immediately throughout your site.

MyVars has three possible variable types:

Variables

Variables are single word tokens that you can use anywhere in your page text, template HTML or even field inputs such as page titles, menu text or link text. The tokens are formatted as [[search_value]]. For instance, if you create a phone_number variable, you simply insert the [[phone_number]] token anywhere on your site, and the MyVars Plugin will automatically replace the token with the value you enter in the MyVars Manager.

Example:

Let’s say you create a variable with the search value phone_number and give it the replacement value (555) 555-1234.

In your page text, you enter:

For more information, please contact us at [[phone_number]].

Your page will appear as:

For more information, please contact us at (555) 555-1234.

Strings

Strings are any string of text, of any length that you want to replace throughout your site. For instance, let’s say the name of your company changes from Acme Industries, LLC to Acme Global Industries, Inc. Rather than search throughout your entire site for every instance of the old name, you can create a string search value in MyVars Managers where the old name is the search value of the variable, and the new name is the replacement value. When your pages are rendered, the old name will be automatically replaced with the new value.

Example:

Let’s say you create a string search value Acme Industries, LLC and specify the replacement value Acme Global Industries, Inc..

Your original page text contains:

Welcome to Acme Industries, LLC….

Your page will appear as:

Welcome to Acme Global Industries, Inc.….

Regular Expressions (Advanced Users)

Regular Expressions is a pattern matching language to allow you to match patterns or letters and/or numbers. MyVars allows you to specify a Regular Expression as a variable name to be replaced with the value you choose. For instance, if you want to add an area code to all instances of your phone number on your web site, you can specify /[0-9]{3}-[0-9]{4}/ as the search value, enter (555) $0 as the replacement value, and MyVars will automatically add the area code to each matching phone number.

Example:

Let’s say you create a Regular Expression search value /[0-9]{3}-[0-9]{4}/ and give it the
replacement value +1 (555) $0.

Your original page text contains:

Please contact us today at 555-1234….

Your page will appear as:

Please contact us today at +1 (555) 555-1234….

MyVars Extension Installation

System Requirements

• SkyBlueCanvas v1.1
• PHP 4 or above
• Apache Web Server

Installation Instructions

1. Log into the Admin section of your SkyBlueCanvas site at www.yoursite.com/admin.php.
2. Navigate to Admin > Collections > Installer.
3. • Click on the Managers tab.
   • Click the button labeled New in the upper-right corner of the admin page.
   • Click the button labeled Browse.
   • Using the file browser that appears, locate the MyVars Manager ZIP file in ext_myvars/packages/manager/myvars.zip.
   • Click the button labeled Install.
4. • Locate the MyVars Plugin file in ext_myvars/source/plugin/plugin.variables.php.
   • Open the MyVars Plugin file in a text editor and copy the code.
   • Go to Admin > Collections > Plugins
   • Click the button labeled Add in the upper-right corner of the admin page.
   • Paste the plugin code you copied into the textarea on the form.
   • Name the plugin plugin.variables.php.
   • Click the button labeled Save.

If you currently have the Teasers Module enabled and displaying on your site, this technique may display some content twice.

SkyBlueCanvas Plugins to the Rescue

Since the creation of content and rendering of content is fairly well separated in SkyBlueCanvas, it is possible to display content in an unlimited number of ways. To solve this particular problem I chose to write a simple plugin to allow me to specify the specific Teaser I want to display and even restrict the display to an individual page or a list of pages.

The concept is actually pretty simple:

• Create a plugin that accepts a Teaser ID and Page ID as its arguments
• Add the Plugin Call to my template or page text

The Plugin Call

The plugin will make more sense if we first examine the plugin call. If you need a refresher on the SkyBlueCanvas Plugin API see the post on SkyBlueCanvas Plugins.

There are two ways to explicitly call a SkyBlueCanvas Plugin:

An HTML comment plugin call:

<!--#plugin:myPluginFunction(arg1, arg2,...)-->

Or a plugin call from within the text of a story:

{plugin:myPluginFunction(arg1, arg2,...)}

For this plugin we are going to pass two arguments, the Teaser ID and the Page ID and we’ll use an HTML comment plugin call. The code below will be added to our HTML template (skin):

<!--#plugin:plgSnippet(2,1)-->

The above plugin call will tells the Snippet Plugin that we will create next to display Teaser ID 2 on Page ID 1 (the home page). It won’t actually do anything yet, however. It is just an HTML comment and will not display on the page.

The Plugin Code

The PHP code below includes comments to explain each step of the process so I won’t repeat it.

<?php

  /**
  * Show an individual Teaser item in a page region indicated by
  * <!--#plugin:plgSnippet($id, $pageId)-->
  *
  * @param  array  An argument array
  * @return string The html of the snippet
  */

  function plgSnippet($args)
  {
    global $Core;

    /*
    *  If no arguments are passed, return a null value.
    */

    if (!count($args)) return null;
    $id = $args[0];

    /*
    * The second argument is optional. If you want to
    * only show the snippet on a specific page, pass
    * the page ID as the second arguemnt.
    */

    $pageId = count($args) == 2
      ? plgSnippetConvertArg($args[1])
      : null ;

    /*
    * Store the current page id in a variable.
    */

    $thisPageId = $Core->GetVar($_GET, 'pid', null);

    /*
    * The page id passed by the plugin call can be a single
    * page id or an array of page ids. If the page id is set,
    * make sure it matches the current page id.
    */

    if (is_array($pageId) && !in_array($thisPageId, $pageId))
    {
      return null;
    }
    else if (!empty($pageId) && $thisPageId !== $pageId)
    {
      return null;
    }

    /*
    * If we made it this far, we need to show the snippet.
    */

    $snippets = $Core->xmlHandler->parserMain(
        SB_XML_DIR . 'teaser.xml'
      );
    $snippet = $Core->SelectObj($snippets, $id);
    if (!$snippet) return null;
    $html  = "<div id=\"snippet-$id\">\n";
    $html .= "<h2>{$snippet->name}</h2>\n";
    $html .= "<p>" .
      base64_decode($snippet->intro) .
      "</p>\n";
    $html .= "</div>\n";
    return $html;
  }

  /**
  * Convert an argument to an array if it contains the
  * ',' delimiter. Otherwise return the argument untouched.
  */

  function plgSnippetConvertArg($arg)
  {
    if (strpos($arg, ',') == false) return $arg;
    $args = explode(',', $arg);
    for ($i=0; $i<count($args); $i++)
    {
      $args[$i] = trim($args[$i]);
    }
    return $args;
  }

?>

Putting It All Together

Now, log into your SkyBlueCanvas Site Admin and go to: Collections > Plugins

Click the Add button to create a new plugin. You can name the plugin anything you like but keep in mind that plugins must be named ‘plugin.your_plugin_name.php’. Let’s just name it plugin.snippet.php.

Next, paste the PHP code above into the text area on the Plugin Editor and click Save.

The plugin is created and is now active. The next step is to create a Teaser (or Teasers) to display so go to Collections > Teasers. Click the Add button and give your Teaser a name. The name can be anything you like and may include spaces. Add the Teaser text. Be sure to leave the Link selector set to No Link. Click Save.

Next, go to Collections > Collections Publishing and make sure that mod.teaser.php is not published on any pages.

Okay, we are down to the final step – calling our Snippet Plugin to display our snippet(s). Go to Main Dashboard > Pages and click Edit in the task list next to your home page.

In the HTML editor, add the following code:

{plugin:plgSnippet(2)}

Notice that we did not provide the second argument (the page id). Since we are calling the plugin from the Home Page text, we do not need the second argument.

Save your page and go to your site’s home page. You should see the Teaser name and text displayed on the page. The Snippet output has a unique id formatted as snippet-n where n is the Teaser ID. This allows you to write CSS rules specific to each Snippet.

The Snippet output will look like this:

<div id="snippet-2">
<h2>My Snippet Title</h2>
<p>This is my first Snippet.</p>
</div>

Alternative Display Techniques

The Snippet Plugin gives you a couple of display options depending on which call method you use (i.e., HTML comment call or text-based call), and what arguments you pass to the plugin.

For instance, if you are using an HTML comment call, you can restrict the display of the snippet(s) to a single page or a list of pages.

<!--#plugin:plgSnippet(2, [1,2,3])-->

The call to the Snippet plugin shown above tells the plugin to display Teaser ID 2 on pages 1, 2 and 3. To display the Teaser only on the first page, use the following format:

<!--#plugin:plgSnippet(2,1)-->

That’s all there is to it. As you can see, the SkyBlueCanvas Plugin API gives you a lot of flexibility in what content is displayed on your site and how.

Updated

The SiteVars plugin is included in the SkyBlueCanvas core code. This article is still a good reference about how to use the plugin but you do not need to download or install any additional code.

The SiteVars plugin adds a lot of flexibility and power to a SkyBlueCanvas site without requiring any knowledge of PHP or HTML. In fact, you do not even need a lot of knowledge about how the insides of SkyBlueCanvas work to use this plugin.

The plugin uses a simple ASCII-based syntax to insert values from properties that you set in the admin control panel. One of the biggest benefits of this approach is that if the values change, you do not need to update references to these values in your template or content.

There are three basic objects or domains that can be referenced by the plugin’s grammar. These are: site, page and page.link. The syntax is very simple and will always be written like this:

[[ object . property ]]

Notice the double square brackets enclosing the variable on the left and right sides. When you create these tokens, omit the spaces shown above.

Site Variables

Example Usage:

Welcome to [[site . name]]

Page Variables

Example Usage:

Bread Crumbs: <a href="index.php?pid=[[page . parent . id]]">
    [[page . parent . title]]</a> / [[page . title ]]

Page Link Variables

The wrap_tag parameter in each variable below can be any HTML element.

Example Usage:

Pagination: [[page . link(first)]] -
    [[page . link(previous)]] -
    [[page . link(next)]] -
    [[page . link(last)]]

Example Usage 2:

<h2>Related Articles</h2>
<ul>
    [[page . link(children, li)]]
</ul>

Example Usage 3:

    [[page . redirect(http://www.skybluecanvas.com)]]

Ad zones are defined using a special kind of commment in the HTML Skin of your site. Ad replacement tokens are a specially-formatted token that appears in your site Skin. An example from my own site is:

Defining Banner Ad Zones

<!--#ads:main-top-->

When the ads plugin loads, SkyBlueCanvas passes the page HTML to the plugin call which looks like this:

The Ads Plugin

plgLoadAds($html);

The ads plugin parses all comments that are formatted as above and determines the zone. In this case ‘main-top’. As the plugin encounters each token, it then looks in /skyblue/data/ads/ for any files whose names match the zone specified in the token. You can have an unlimited number of ads for each zone and the ads plugin will display them randomly.
Saving Your Ads

NOTE: In order to upload ads to your site, you will need FTP access.

Ads are saved as text files in /skyblue/data/ads/. It doesn’t matter if your ad is a JavaScript? or HTML block. SkyBlueCanvas sends whatever is stored in the ad file to the browser and lets the browser determine how it should be displayed. Since the ads are saved as text, there is no code execution that takes place on the server, so you do not need to worry about malicious code – at least on the server side.
Naming Your Ad Files

SkyBlueCanvas matches the file to the zone in which it is to be displayed based on the file name. You can name your zones anything you like, as long as your ad file names match the zone names you defined.

For example, if I have defined a zone ‘main-top’, then I would include the following token in my HTML skin:

<!--#ads:main-top-->

Then, I would save my add files with names like this:

• main-top.skypead.txt
• main-top.yahoo.txt
• main-top.googleads.txt

Styling Your Ad Blocks

Each ad block is wrapped in a div with a unique ID to allow you to create CSS rules corresponding to each ad block.

Using the example above, the ad block wrapper would look like this:

<div id="ads-main-top">
    <!-- the ad code here -->
</div>

SkyBlueCanvas has a very flexible yet simple plugin API. Actually, it has 2 plugin APIs for greater flexibility. The first API is almost identical to the API used by Wordpress and Joomla – both of which use the Observer design pattern.

Calling an Observer plugin in SkyBlueCanvas is simple. Create a file named ‘myplugin.php’ and save it in /skyblue/data/plugins/myplugin.php. In the file, include the following code:

global $Core;

$Core->RegisterEvent('OnBeforeShowPage', 'AllYourPlugins');

function AllYourPlugins($html) {
    $html .= "<p>All your plugins are belong to us</p>n";
    return $html;
}

That’s it. Now when the $Core object gets to the ‘BeforeShowPage’ marker, it will call the AllYourPlugins function, passing the $html variable containing the page data to the function. The function can perform any operation it need to on the page code, then must return it to the $Core object.

SkyBlueCanvas currently has 4 events to which plugin execution can be attached:

• OnBeforeInitPage

  is triggered before the page is built.

• OnAfterLoadStory

  is triggered when the article for the current page is loaded.

• OnBeforeShowPage

  is triggered after the entire page is built but before it is sent to the browser.

• OnAfterCache

  is triggered after the page has been retrieved from and/or saved to cache.

I am working on implementing more events but they will not be available until the next release.

Plugin Method No. 2

There are instances when you want to insert some code or execute some code at a certain point within the flow of a story. Well, SkyBlueCanvas allows you to do just that with the second Plugin API.

This API allows you to call specific functions, with arguments within the flow of the text using special tokens and function calls that look like this:

{plugin:myfunction('Plugins')}

Before SkyBlueCanvas displays the page, it will parse all of the special plugin tokens, and call the function specified in the token. So, in this example, when the token is parsed, the SkyBlueCanvas PluginParser will call ‘myfunction’ passing it the argument ‘Plugins’.

Now create a file in /skyblue/data/plugins/myplugin.php and create the myfunction function like so:

function myfunction($args) {
    if (!count($args)) return false;
    $what = $args[0];
    echo "<p>All your $what are belong to us</p>n";
}

Additionally, this method can be embedded in the HTML of your template as well like so:

<!--#plugin:myfunction(Plugins)-->