Building a page extension for Sitemagic CMS

page extension is an extension that can be added directly to a content page from within the page editor. We use this when adding an image gallery or a contact form (see image below).

/Extensions/PageExtension.png

Writing the code
A page extension is simply an extra file contained in a "normal" extension. Actually the "normal" extension is used to register the page extension, allowing the page editor to access and use it. This is how we register it:
Main.class.php
<?php

class MyExtension extends SMExtension
{
    public function InitComplete()
    {
        // Only register page extension if Pages extension is installed and enabled
        if (SMExtensionManager::ExtensionEnabled("SMPages") === true)
        {
            $extList = SMPagesExtensionList::GetInstance();

            // Only register page extension if needed (which is when the page editor is opened)
            if ($extList->GetReadyState() === true)
            {
                // Category and title displayed in page editor when inserting a page extension
                $category = "My extensions";
                $title = "Greeting";

                // Information used by page editor to find and load page extension
                $ext = $this->context->GetExtensionName();
                $file = "Greeting.class.php";
                $class = $ext . "Greeting";

                // $arg may be used to register the same page extension and have
                // it behave differently depending on the value within this variable.
                $arg = "This value is available from page extension using $this->argument";

                // Width and height (in pixels) of place holder image
                // used to display page extension within the page editor (see image above)
                $w = 300;
                $h = 50;

                // Register page extension to make it accessible from page editor
                $extList->AddExtension($category, $title, $ext, $file, $class, $arg, $w, $h);
            }
        }
    }
}

?>
Read the comments in the code sample above for an explanation. Now let's write the actual page extension responsible for adding data or functionality to our content page.
Notice that we made a few decisions regarding filename and class name when we registered the page extension in the code above - the file must be named Greeting.class.php, and the contained class must have the name of the extension folder followed by Greeting.
Greeting.class.php
<?php

class MyExtensionGreeting extends SMPagesExtension
{
    public function Render()
    {
        $idPrefix = $this->context->GetExtensionName();
        $message = "";

        // First create an input field and a link button
        $txtName = new SMInput($idPrefix . "Name", SMInputType::$Text);
        $cmdSend = new SMLinkButton($idPrefix . "Send");
        $cmdSend->SetTitle("Say hi");

        // Create a message if a value was entered in the input field on post back
        if ($txtName->GetValue() !== null && $txtName->GetValue() !== "")
            $message = "<br><br>Hi " . $txtName->GetValue() . ", good to see you!";

        // Create output (render text label, input field, link button, and message)
        $output = "";
        $output .= "Enter your name: ";
        $output .= $txtName->Render();
        $output .= $cmdSend->Render();
        $output .= $message;

        // Return output to Pages extension to have it displayed on content page
        return $output;
    }
}

?>
Again, please refer to the comments in the code sample for an explanation. It should be quite easy to understand.
One last thing worth mentioning is the argument variable set when we registered the page extension. This is now available from within the Render function:
Greeting.class.php
<?php

class MyExtensionGreeting extends SMPagesExtension
{
    public function Render()
    {
        return "Argument set: " . $this->argument;
    }
}

?>
The argument is commonly used when the same page extension is registered multiple times. The argument can then be used to tell the page extension how to look and behave.