Creating Plugins/4.x

From Sit

This is a draft article (or section) and is a work-in-progress. Please help us and our readers by clicking the edit link above and expanding/improving this text.

The information in this article (or section) relates to SiT! v3.90 and later. Earlier versions may not have this functionality.

SiT! v4 branch (actually versions 3.90 and later) introduce an improved plugin layout. For your plugin to be compatible with SiT! 3.90 and later it must follow these guidelines.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119

Plugin name

• Your plugin name should be chosen to be unique and descriptive must not clash with any plugin that has already been published.
• Your plugin name should not contain the word 'plugin'.
• Your plugin name must not be longer than 50 characters or contain characters other than A-Z, 0-9 or underscore _.

File layout

• All the files that make up your plugin must be contained with a folder that has your plugin name, (e.g. A plugin named 'myplugin' must reside in a folder named 'myplugin')
• A text file named README must be placed inside the plugin folder. (e.g. 'myplugin/README') and should contain at least basic documentation for the plugin
• A text file named LICENSE or COPYING must be placed inside the plugin folder. (e.g. 'myplugin/README') and contain the full text of your chosen licence.
• A main file named myplugin.php must be placed inside the plugin folder (Where myplugin is the name of your plugin and matches the name of your plugin folder).

Plugin info code block

Your main file (e.g. myplugin.php) must have a block like the one shown below as the first lines in the file.

<?php
$PLUGININFO['myplugin']['version'] = 0.01;
$PLUGININFO['myplugin']['description'] = 'MyPlugin created widgets for maximum foobar control';
$PLUGININFO['myplugin']['author'] = 'Joe Public';
$PLUGININFO['myplugin']['legal'] = 'Copyright (C) 2010 Widgets Inc. GPL v2 Licenced.';
$PLUGININFO['myplugin']['sitminversion'] = 3.90;
$PLUGININFO['myplugin']['sitmaxversion'] = 3.99;

// Your code goes here ...

• version - Must have a version number for your plugin (a PHP float), each publication of your plugin must increment this number
• description - Must be a short (less than 255 characters) friendly name/description/summary of your plugin
• author - Should be the name or names of the plugin author/authors (less than 255 characters)
• legal - Must indicate the copyright owner and licence of the plugin (less than 255 characters) (e.g. "Copyright (C) 2010 Widgets Inc. GPL v2 Licenced")
• sitminversion - Should indicate the earliest SiT! version that the plugin is compatible with (a PHP float)
• sitmaxversion - Should indicate the latest SiT! version that the plugin is compatible with (a PHP float)

Your main file may also define the following plugin info lines:

$PLUGININFO['myplugin']['url'] = 'http://www.example.com/myplugin/about.html';

• url - May be a URL to a web page that has more information about your plugin (Your plugin homepage).

Plugin Variable/Function naming

• Variables internal to your function but of global scope (e.g. language strings) must be uniquely named, the recommended way to do this is by including the plugin name as part of the variable name.
• Functions, classes, global variables etc. must be uniquely named, the recommended way to do this is by including the plugin name at the start of the name. (e.g. mplugin_foobar())

Plugin installation

• Your plugin must install without errors or warnings and must not require changes to SiT! core code.
• Your plugin must not require it's own plugin files to be outside the plugin folder.
• Your plugin may require another plugin to be installed in order to function but if this is the case it should be clearly documented and your plugin must check for the presence of the other plugin before attempting to use it's features.
• Your plugin must not make changes to any SiT! database tables.
• Your plugin may add additional tables to the SiT! database schema but must ensure the names are unique and don't clash with any existing or planned table or with a table used by another plugin, the recommended way to do this is by including the plugin name as part of the table name.

Logging / Debug output

• Your plugin must use the SiT! function debug_log() for any debug output to avoid messages cluttering the SiT! interface.
• Your plugin should include the plugin name in any debug log output.