Building extensions for Sitemagic CMS

Extensions (or plug-ins) are packages that extends the functionality of Sitemagic CMS. Writing an extension is fairly easy, although we need to understand a couple of concepts first to ensure full compatibility.

Two types of extensions

In this documentation we will be talking about two kinds of extensions, and two ways of making them.

We have extensions and (content) page extensions. The extension type is rendered to the entire content area of our website (e.g. the File manager and Menu editor) while a page extension can be added to a content page using the page editor (e.g the Contact form or Image gallery).

A page extension is part of an extension - it's simply an extra file defining what to render (display) on the content page. More on this later.

Two ways of making extensions

Originally there was only one way to do extensions for Sitemagic CMS - by Object Oriented Programming and using a mechanism called the life cycle (which is explained in a bit).

But recently an extension was released (Pure PHP) allowing you to write code and new functionality for Sitemagic CMS using nothing but ordinary PHP. Such extensions are called Pure PHP Extensions. You no longer need to fully understand the concepts explained on this page, and you can write your code just the way you use to. Using Pure PHP has both advantages and disadvantages. Learn more about building Pure PHP extensions for Sitemagic CMS.

If you are new to building extensions for Sitemagic CMS, Pure PHP is a good way to get started, and to get familiar with the framework, should you choose to use it. On this page we will be focusing on normal extensions for Sitemagic CMS.

Extension structure

Extensions are located in the extensions folder. Each extension is stored in its own folder, e.g. extensions/MyExtension. An extension requires only two files to work.

Main.class.php: This is where we add our functionality.
metadata.xml: Contains extension details such as Title, Version, and Author.

Multitasking

Conceptually Sitemagic CMS features multitasking, enabling multiple extensions to run at the same time, much like a computer allow multiple programs to run at the same time. Technically this is achieved using a concept called the life cycle. Extensions goes through different stages in turn. First all extensions goes through a stage called PreInit. When that is done executing, all extensions execute the Init stage, then the InitComplete stage, and so forth.

This approach enable extensions to interact with the underlaying framework during different stages of the life cycle, and share data, resources, and functionality with other extensions.

Privileged extension

One extension is privileged. This extension is allowed to render (display) content on the website within the content area, which is where the {[Extension]} place holder is defined in our design template (explained in Building design templates).

Which extension is privileged is determined by the SMExt argument in the URL. The following URL will execute and render the Login extension to the content area: http://mydomain.com/index.php?SMExt=SMLogin

Obviously the user will never need to enter or modify this argument in the URL. It is set when the user click various links (or buttons) on the website. These links can be added by any extension, allowing the user to "execute" an extension (make it privileged) by simply clicking one of these links. Notice that the SMExt argument may be hidden using URL rewriting (SEO friendly URLs), transforming those complex URLs to simpler and prettier URLs.

Extensions that do no execute privileged usually define place holders and repeating blocks if they need to add content to the website on every page load. The Menu extension is a good example - all templates define place holders and repeating blocks for this particular extension, allowing it to add navigation links even when not executing privileged.

Another way for an extension to add content is to manipulate the raw output (HTML) of the templating system, before it is sent to the client (browser). Adding e.g. JavaScript to the <head> section or additional content to the <body> section (or modify the existing content) is fairly easy thanks to the powerful templating system.

The life cycle

Much like Controls and WebParts within ASP.NET, extensions within Sitemagic CMS executes as part of the life cycle. The life cycle begins when a page is requested, and ends when the page has been served to the client. The life cycle allow extensions to interact with the system and other extensions at different stages.

Life cycle stages

Initialization
- PreInit
- Init
- InitComplete

Rendering
- PreRender
- Render (privileged only)
- RenderComplete

Template updates
- PreTemplateUpdate
- TemplateUpdateComplete

Sending response to client
- PreOutput
- OutputComplete

Finalizing execution
- Unload
- Finalize

Life cycle stages explained

The Initialization stages are used by extensions to prepare and expose data and functionality, as well as consume it. If Extension X prepares data during Init, Extension Y may use it during InitComplete.

Only the privileged extension is allowed to render content to the content area (it will have the Render stage executed). PreRender and RenderComplete executes for all extensions before and after the Render stage.

These stages are executed before and after Sitemagic CMS updates (populates) the template with the result of the Render stage of the privileged extension (the {[Extension]} place holder is replaced).

These stages are executed before and after the populated template is sent to the client (browser).

These stages are used to do some final cleanup if necessary (e.g. remove temporary data and files).

The table above explains the different stages of the life cycle. Most often extensions use the Initialization stages and the Rendering stages to add functionality to Sitemagic CMS.

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.