Showing Text Shreds Anywhere in SkyBlueCanvas

A recent visitor to the SkyBlueCanvas forum asked how to display individual blurbs of text in a specific spot on a SkyBlueCanvas site page. If you are familiar with the SkyBlueCanvas Managers and Modules you probably recognize that this concept is very similar to the Teasers. The problem with using the Teasers module in this instance is, however, that the module will display all teasers in the page region where the module is displayed.

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.