Plugin Creation

GetSimple plugins allow easy modification, customization, and enhancement to a GetSimple website. Instead of changing the core programming of GetSimple, you can add functionality with our plugin system.

Anatomy of a Plugin

This section describes the different parts of a plugin. For this example, lets use this basic plugin that echos “Hello World” at the bottom of every front-end page. Download Example Plugin

<?php
/*
Plugin Name: Hello World
Description: Echos "Hello World" in footer of theme
Version: 1.0
Author: Chris Cagle
Author URI: http://www.cagintranet.com/
*/
 
# get correct id for plugin
$thisfile=basename(__FILE__, ".php");
 
# register plugin
register_plugin(
	$thisfile, //Plugin id
	'Hello World', 	//Plugin name
	'1.0', 		//Plugin version
	'Chris Cagle',  //Plugin author
	'http://www.cagintranet.com/', //author website
	'Finds email addresses in content and components and "hides" them', //Plugin description
	'theme', //page type - on which admin tab to display
	'hello_world_show'  //main function (administration)
);
 
# activate filter 
add_action('theme-footer','hello_world'); 
 
# add a link in the admin tab 'theme'
add_action('theme-sidebar','createSideMenu',array($thisfile,'Hello World description'));
 
# functions
function hello_world() {
	echo '<p>Hello World</p>';
}
 
function hello_world_show() {
	echo '<p>I like to echo "Hello World" in the footers of all themes.</p>';
}
?>

Variable Setup

This code could always be hardcoded, but it's best if you define the below code right after your registration.

# get correct id for plugin
$thisfile=basename(__FILE__, ".php");

This code is what is used to display your plugin on the “Plugins” tab of the control panel. It also allows you to set the type of page your plugin should be shown as.

# register plugin
register_plugin(
	$thisfile, //Plugin id
	'Hello World', 	//Plugin name
	'1.0', 		//Plugin version
	'Chris Cagle',  //Plugin author
	'http://www.cagintranet.com/', //author website
	'Finds email addresses in content and components and "hides" them', //Plugin description
	'theme', //page type
	'hello_world_show'  //main function
);

Note: $thisfile will not work within hook functions like hello_world or hello_world_show, rather it will be the name of the plugin last loaded.

Hooks & Filters

This code is what attaches your custom function to a particular hook or filter.

# activate filter
add_action( 'theme-footer', 'hello_world', array() );

Syntax: add_action( 'hook name', 'function to call', Array of Args );

This code displays a link to a plugin specific page in the administration (it is a special case of add_action):

# add a link in the admin tab 'theme'
add_action( 'theme-sidebar', 'createSideMenu', array( $thisfile, 'Hello World description' ) );

Syntax: add_action( 'tab-name-sidebar', 'createSideMenu', array( $thisfile, 'link text' ) );

Note: When this link is clicked, it will display the page type tab and call the main function (both specified in the register_plugin call), thus in general the action (here theme-sidebar) and the page type (here theme) should match.

Note: As of version 3.1 you can include multiple menu items on the sidebar by adding an action parameter to the add_action() function:

# add a link in the admin tab 'theme'
add_action( 'theme-sidebar', 'createSideMenu', array( $thisfile, 'Hello World description', 'action1' ) );
add_action( 'theme-sidebar', 'createSideMenu', array( $thisfile, 'Hello World description 2', 'action2' ) );

This will display 2 menu items on the Theme sidebar, you must check for each action (action1 and action2 above) in your code and display pages accordingly.

Custom Functions

The functions in this section would be the functions that are called as part of the registration, a hook or a filter.

# functions
function hello_world() {
	echo '<p>Hello World</p>';
}
 
function hello_world_show() {
	echo '<p>I like to echo "Hello World" in the footers of all themes.</p>';
}

Standard for File & Folder Creation

Additional plugin files

A simple plugin will consist of only one file, e.g. my_plugin.php. But if your plugin consists of more than this main my_plugin.php file you should put them into a directory my_plugin.

If your plugin supports multiple languages, you should put the language files into a sub folder lang. For more information see Languages (I18N).

Similarly you can have subfolders for javascript files, images, etc. For all directories whose files need to be directly accessed by the browser, add a .htaccess file for Apache with the line

Allow from all

Thus a sample plugin structure for a plugin my_plugin with additional php files and images that supports multiple languages might be:

- my_plugin.php
- my_plugin (directory)
   - .htaccess (with one line: Deny from all)
   - common_functions.php
   - lang (directory) 
      - .htaccess (with one line: Deny from all)
      - en_US.php
      - de_DE.php
      - it_IT.php
   - img (directory)
      - .htaccess (with one line: Allow from all)
      - add.png
      - delete.png
      - edit.png

Internationalization (I18N)

If your plugin displays messages to your user/administrator, you will want to allow those messages to be localised to the language of the installation. You do this by having a /lang folder, which has PHP files for each language:

 - lang (directory)
    - .htaccess (with one line: Deny from all)
    - en_US.php
    - de_DE.php
    - it_IT.php

Each file should have one variable: an $i18n array, which has key ⇒ value mappings for the various messages:

<?php
// en_US.php
$i18n = array();
$i18n['PLUGIN_TITLE'] = 'My Plugin';
...

To register your i18n array, call i18n_merge with the ID of your plugin (before register_plugin is called):

i18n_merge($plugin_id);

This registers $i18n for your plugin with the installation's language, but you might not have such a language file created. In order to set up a default language, you can register a fixed language if i18n_merge returns false.

// Sets the default to English
if (!i18n_merge($plugin_id)) i18n_merge($plugin_id, 'en_US');

Or the clearer:

i18n_merge($plugin_id) || i18n_merge($plugin_id, 'en_US');

Once that is done, you can call a localised string by using i18n_r (to return the string) or i18n (to echo it). You do this by prefixing your key with your plugin's ID:

// Prints "My Plugin" if the language is English
i18n($plugin_id . '/PLUGIN_TITLE');

For more information, go to Plugins & Languages (I18N).

Data & Settings

If you need to save your data to a file on the server, we recommend saving it to a new folder within the GSDATAOTHERPATH path. For example: If your plugin needs to save the Google Analytics's UA-XXXXX id for the site, it would be best if you saved it within the folder /path/to/getsimple/data/other/my_plugin_folder/ua-data.txt, where /my_plugin_folder/ is the folder you create and ua-data.txt is the file that holds your data.

// Set up the data
$data = '<Your Data Here>';
 
// Set up the folder name and its permissions
// Note the constant GSDATAOTHERPATH, which points to /path/to/getsimple/data/other/
$folder        = GSDATAOTHERPATH . '/' . $plugin_id . '/';
$filename      = $folder . 'ua-data.txt';
$chmod_mode    = 0755;
$folder_exists = file_exists($folder) || mkdir($folder, $chmod_mode);
 
// Save the file (assuming that the folder indeed exists)
if ($folder_exists) {
  file_put_contents($filename, $data);
}

When saving or accessing files and folders within a GetSimple installation, it is always best to use the defined constants set by the system (as illustrated above). You can get the list of contents from the /admin/inc/common.php file, or by looking at our svn copy of it.

Scripts & Styles

As of GetSimple 3.1 plugin writers have the ability to queue and load scripts and styles on your theme or the back end admin. This allows you to ensure that libraries are loaded only once. It also means that you can easily include your own scripts and styles in separate files as part of your plugin distribution.

We recommend that if you are including your own scripts and styles that you store them in a seperate folder in your plugin folder, /my_plugin_folder/js for your javascript files /my_plugin_folder/css for your stylesheets

Default Scripts & Styles

GetSimple 3.1 comes preconfigured with the following scripts and styles preconfigured ready for queuing on your pages.

Scripts

  • jquery - CDN version of Jquery
  • jquery-ui - CDN version of JQuery UI
  • fancybox - Fancybox lighbox script
  • getsimple - GetSimple site Javascript

Styles

  • getsimple - Getsimple Site CSS

Note: Jquery, Fancybox & Getsimple are loaded automatically on every page of the Admin back-end.

Register & Queue Your Script

To use your script you must first register it with the system.

// register_script($handle, $src, $ver, $in_footer=FALSE)
// $handle name for the script, must be unique for each script loaded
// $src location of the src for loading
// $ver script version
// $in_footer load the script in the footer if true
register_script('jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js', '1.7.1', FALSE);

The above code registers the CDN version of Jquery but it will not be loaded until queued on the system.

To queue and load a registered script use:

// queue_script($name,$where);  
// $name name of the script to load
// $where GSFRONT for theme frontend, GSBACK for backend Admin, GSBOTH to load on both. 
queue_script('jquery',GSBOTH); 

The above code will load Jquery on your theme as well as the Admin backend.

To register a script from your plugin folder use

register_script('pluginscriptname', $SITEURL.'plugins/my_plugin_folder/your.script.js', '0.1', FALSE);

In production if your plugin requires Jquery to be loaded on the frontend theme just queue it using GSFRONT and it will be loaded once regardless of how many plugins have set it to load.

Register & Queue Your Styles

To use your own stylesheets you must first register them with the system.

// register_sstyle($handle, $src, $ver)
// $handle name for the style, must be unique for each style loaded
// $src location of the src for loading
// $ver style version
// $media Media type for the CSS file
register_style('getsimple', $SITEURL.$GSADMIN.'/template/style.php', GSVERSION, 'screen');

The above code registers the GetSimple CSS files but will not be loaded until queued on the system.

To queue and load a registered style use:

// queue_style($name,$where);  
// $name name of the style to load
// $where GSFRONT for theme frontend, GSBACK for backend Admin, GSBOTH to load on both. 
queue_style('getsimple',GSBOTH);