My first extension for Sitemagic CMS

Building extensions is faily easy once you understand the concepts described in the Building extensions for Sitemagic CMS (introduction). Extensions can be build using almost pure PHP, while the underlaying framework provides additional functionality.

Before proceeding, make sure you have enabled debugging which will help you identify code errors.

In this example we will build an extension that allows us to change the background color of our website. Follow the instruction on this page, or download the example from the box in the upper right cornor, and install it to the extensions folder on the server. Make sure you enable the extension from Settings.

To manually create the extension, first create a folder named MyVeryFirstExtension in the extensions folder. Create the files metadata.xml and Main.class.php:

metadata.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<entries>
    <entry key="Title" value="Background colors" />
    <entry key="Description" value="Easily change background color using this extension" />
    <entry key="Author" value="James Thomson" />
    <entry key="Company" value="" />
    <entry key="Website" value="" />
    <entry key="Email" value="" />
    <entry key="Version" value="1" />
    <entry key="Dependencies" value="" />
    <entry key="Notes" value="" />
</entries>

The purpose of metadata.xml is to give Sitemagic CMS some basic information about our extension. These are used in the Settings section to display a list of available extensions that can be enabled.

Now add the basic code for an extension to Main.class.php:

Main.class.php

<?php

class MyVeryFirstExtension extends SMExtension
{
}

?>

The class name must be identical to the name of the extension folder (in this cause it would be MyVeryFirstExtension). Also the extension must inherit from (extend) SMExtension.

Before we proceed, make sure to enable the extension from Settings (find Background colors in the Extensions enabled panel).

We will now have our extension add a link to the navigation menu.

Main.class.php

<?php

class MyVeryFirstExtension extends SMExtension
{
    public function PreTemplateUpdate()
    {
        // Only add links to menu if it is installed and enabled
        if (SMExtensionManager::ExtensionEnabled("SMMenu") === true)
        {
            // Get menu (to which our link will be added)
            $menu = SMMenuManager::GetInstance();

            // Create and add link to menu
            $linkId = SMRandom::CreateGuid();
            $linkTitle = "Change color";
            $linkUrl = SMExtensionManager::GetExtensionUrl($this->context->GetExtensionName());
            $menu->AddChild(new SMMenuItem($linkId, $linkTitle, $linkUrl));
        }
    }
}

?>

First thing to notice here, is how the extension executes code during a given stage of the life cycle. Simply implement a function with the name of the life cycle stage - in this case the PreTemplateUpdate stage.

The code above is almost self-explanatory. First we make sure the navigation menu is installed and enabled. Then we access the menu, creates the link (which requires a unique ID, a title, and a URL), and adds it to the menu.

Try reloading the website. A link named Change color should now be available from the navigation menu. Clicking it will simply produce an empty page since we have not yet implemented any code for the Render stage.

Take extra notice of this piece of code:

Notice

$linkUrl = SMExtensionManager::GetExtensionUrl($this->context->GetExtensionName());

This will produce a URL to our extension that will make it execute privileged (explained in the introduction), hence having its Render stage executed when implemented. Let's implement the Render code now:

Main.class.php

<?php

class MyVeryFirstExtension extends SMExtension
{
    // PreTemplateUpdate code removed for clearity.

    public function Render()
    {
        $output = "";
        $output .= "<h1>Change background color</h1>";
        $output .= "Click on a color below:<br><br>";
        $output .= $this->createColorBox("red");
        $output .= $this->createColorBox("green");
        $output .= $this->createColorBox("blue");
        $output .= $this->createColorBox("black");
        $output .= $this->createColorBox("white");
        $output .= "<div style=\"clear: both\"></div><br>";

        return $output;
    }

    private function createColorBox($color)
    {
        $style = "width: 20px; height: 20px; float: left; margin-right: 3px;";
        $style .= "border: 1px solid gray; background-color: " . $color;
        $onclick = "document.getElementById('SMForm').style.backgroundColor='" . $color . "'";

        $output = "<div style=\"" . $style . "\" onclick=\"" . $onclick . "\"></div>";
        return $output;
    }
}

?>

This extension allows us to change the background color of our content area. Not very useful, but it proves that our extension works. It adds a link to the navigation menu, and it renders our extension when the link is clicked.

In many cases we want to build a user interface that allows us to enter some sort of data or configuration, and have it written and later retrieved again from a database. Let's dig deeper into that in the next chapter: A simple WebShop.