Download

Download Pure PHP

Quick links

Page extension

Building Pure PHP extensions for Sitemagic CMS

Writing an extension for Sitemagic CMS is actually quite simple once you understand the life cycle and how to integrate your extension with Sitemagic CMS, making it accessible throughout the user interface. But lately it has become clear that some people just want to write code the way they use to - whether that be based on object oriented programming (Wikipedia), functional programming (Wikipedia) or classic imperative programming (Wikipedia).
Making the functionality of an extension available throughout the user interface can be completely hassle-free, without you having to write code against the Menu and Pages extension.

Advantages and disadvantages
Writing Pure PHP extensions have the obvious benefit of allowing you to write code the way you use to. It also greately simplifies how to integration functionality throughout the user interface using a simple configuration array (see code sample below). It only comes with a fairly insignificant performance penalty.
If you are not sure whether you should write an ordinary extension or a Pure PHP extension, we'd recommend starting with a Pure PHP extension for simplicity.


Install and enable
PurePhp is actually a regular extension for Sitemagic CMS. Download from the box in the upper right corner, install it to the extensions folder on your server, and enable it from Settings (find Pure PHP Extensions in the Extensions enabled panel).
Be aware that Pure PHP comes with two demo files that will now add demo extensions to your installation. To get rid of them simply remove example.extension.php and example.pageextension.php from the extensions/SMPurePhp folder.

Writing the code
Before proceeding, make sure you have enabled debugging which will help you identify code errors.
Browse to extensions/SMPurePhp and create a new file named HelloWorld.extension.php. The file must have the .extension.php suffix. To integrate it with Sitemagic CMS, simply use the $cfg configuration array as shown below (all options are optional - you can use those that makes sense to you and leave the rest of them out).
HelloWorld.extension.php
<?php

// ===========================================================================================

// Add extension to the navigation menu. Specify "Admin" in
// Target option to add link to Admin drop down menu instead.
$cfg["Menu"]["Title"] = "Product list";
$cfg["Menu"]["Target"] = "Normal";

// Add extension to menu editor's link picker. This will allow the website owner to easily
// create a link to this extension file by clicking the yellow folder within the menu editor.
$cfg["MenuLinkPicker"]["Title"] = "Link to product list";
$cfg["MenuLinkPicker"]["Category"] = "WebShop";

// Add extension to page editor's link picker. This will allow the website owner to easily
// create a link to this extension file by clicking the link button within the page editor.
$cfg["PageLinkPicker"]["Title"]    = "Link to product list";
$cfg["PageLinkPicker"]["Category"] = "WebShop";

// Specify whether extension requires website owner to log in to Sitemagic CMS (Yes/No).
$cfg["Settings"]["LoginRequired"] = "No";

// This file is executed multiple times during different stages of the life cycle.
// The render functionality below could potentially take some time to execute. It is
// therefore skipped if not needed. The check also prevents functions and classes from being
// redeclared. As these are now declared runtime, they cannot be called before declaration.
if ($render === true) {

// ===========================================================================================

// YOUR CODE GOES HERE.
// Simply print/echo the code you wish to display
// within the content area of Sitemagic CMS.

echo "Hello world - this is my first extension";

// ===========================================================================================

}

?>
The first 7 lines of PHP code is what it takes to fully integrate your Pure PHP extension with the navigation menu and page editor. The rest is up to you. Simply echo og print out the content you wish to display.

Linking to other Pure PHP extensions
Obviously you can create an infinite number of Pure PHP extensions as described above, so you may need to be able to create a link from one Pure PHP extension to another. Simply use the following code:
HelloWorld.extension.php
<?php

$url = $this->getUrl("MyShop.extension.php");
echo "Click <a href=\"" . $url . "\">here</a> to go to our web shop";

?>


Using the framework
Although you can now write extensions using nothing but ordinary PHP, there is a good chance you will find some parts of the framework useful for your application. Fortunately you can still use the framework to help you add more functionality with less code. Adding functionality using Pure PHP extensions will not reduce framework support.
For instance, taking a look at how easily data can be stored and retrived using a DataSource.

Packaging and re-distribution
If you plan on distributing your Pure PHP extensions (whether that be free of charge or for money), you will most likely want to have your solution show up in Sitemagic CMS as a real and independent extension with a name different from Pure PHP Extensions in Settings. Fortunately this is quite easy to achieve.
  1. Copy the folder extensions/SMPurePhp to e.g. extensions/MyWebShop
  2. Open Main.class.php for editing and go to the first line of code:
    class SMPurePhp extends SMExtension
    Replace SMPurePhp with the name of your new folder (MyWebShop):
    class MyWebShop extends SMExtension
  3. Open PageExtension.class.php for editing and go to the first line of code:
    class SMPurePhpPageExtension extends SMPagesExtension
    Replace SMPurePhp (NOT the PageExtension part) with the name of your new folder (MyWebShop):
    class MyWebShopPageExtension extends SMPagesExtension.
  4. Open metadata.xml for editing and change the title and description for your extension
That's it - you now have a completely independent extension for Sitemagic CMS. Remember that it needs to be enabled from Settings now that it exists under a new name.
With Pure PHP extensions you are allowed to copy, redistribute, and charge money for your copy of SMPurePhp.

Best practices
For general information on developing design templates and extensions for Sitemagic CMS, please refer to the Best Practices developing for Sitemagic CMS. The chapter contains relevant information about file encoding and the <form> element that you should read.