Best practices developing for Sitemagic CMS

To get the best result when developing for Sitemagic CMS, please consider the following constraints and recommendations.

File encoding
Sitemagic CMS uses the ISO-8859-1 encoding (Latin1 / Western Europe) which is default in PHP on which Sitemagic CMS is based. PHP does have support for UTF-8, but it wasn't designed with UTF-8 support to begin with - it was gradually introduced over time. When the first lines of code was written for Sitemagic CMS, not all functions had equivalent multibyte functions. Adding UTF-8 support today would require serious code refactoring as well as new security measures to protect agains "Invalid Encoding Attacks" in custom extensions. Since Sitemagic CMS is mostly used by European and English speaking contries, converting to UTF-8 would not add any real value to the project. It was therefore decided to wait for PHP to introduce native and proper support for UTF-8.
Sitemagic CMS will work as expected for most European and English speaking contries, while it is not considered very suitable for e.g. Asian contries.
Make sure to save all file types using the appropriate character encoding (ISO-8859-1 or compatible).

Avoiding conflicts
In order to avoid conflicts with other extensions, it is recommended to use unique names and IDs for the following elements.
  • PHP class names (OOP)
  • URL paramenters
  • Sessions and cookies
  • JavaScript functions and variables
  • ID attributes for HTML elements and GUI controls
  • CSS classes
  • Data Sources
  • Attributes in the global attribute collection
  • Place holders and repeating blocks in design templates
In general it is good practice to simply prefix the elements above with the name of the extension (the extension folder) or "TPL" for elements within design templates.
Examples (to be used with an extension named MyExtension):
Bad class name: class Person
Good class name: class MyExtensionPerson
Bad URL parameter: index.php?Username=Test
Good URL parameter: index.php?MyExtensionUsername=Test
Bad HTML element ID: <input type="text" id="Username">
Good HTML element ID: <input type="text" id="MyExtensionUsername">

The <form> element
Be aware that you may not render (print) a <form ..> element from an extension or design template. Sitemagic CMS creates the <form> element automatically. It is used by Sitemagic CMS to retain the state of the system. Rendering <input> controls and other HTML elements will work just fine.
If you need to upload binary data (e.g. using <input type="file">, you will need to change the form encoding. This can be achieved from an extension using the following code:
From an extension or page extension (before or during the PreTemplateUpdate stage of the life cycle)
<?php

$this->context->GetForm()->SetContentType(SMFormContentType::$MultiPart);

?>
From a Pure PHP extension
<?php

$cfg["Settings"]["FormType"] = "MultiPart";

?>
From a Pure PHP page extension
<?php

$cfg["FormType"] = "MultiPart";

?>
 
Type juggling
PHP is a loosly typed language. This has advantages but certainly also disadvantages. Sitemagic CMS uses strict comparison and implements strict type checking throughout the entire framework to prevent type errors. Read more on type checking in Sitemagic CMS if you are curious.