====== 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. [[http://get-simple.info/data/uploads/hello-world.txt|Download Example Plugin]]

<code php>
<?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>';
}
?>
</code>

===== Variable Setup =====

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

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

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.

<code 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
	'hello_world_show'  //main function
);
</code>

**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.

<code php>
# activate filter
add_action( 'theme-footer', 'hello_world', array() );
</code>

**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//):

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

**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:
<code php>
# 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' ) );
</code>
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 [[plugins:hooks_filters|hook or a filter]].

<code php>
# 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>';
}
</code>

===== 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 [[plugins:i18n|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
<code>
Allow from all
</code>

Thus a sample plugin structure for a plugin ''my_plugin'' with additional php files and images that supports multiple languages might be:
<code>
- 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
</code>

==== 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:

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

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

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

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

<code php>
i18n_merge($plugin_id);
</code>

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''.

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

Or the clearer:

<code php>
i18n_merge($plugin_id) || i18n_merge($plugin_id, 'en_US');
</code>

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:

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

For more information, go to [[plugins:i18n|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.

<code php>
// 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);
}
</code>

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 [[http://code.google.com/p/get-simple-cms/source/browse/trunk/admin/inc/common.php|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. 

<code php>
// 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);
</code>

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: 

<code php>
// 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); 
</code>

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

To register a script from your plugin folder use 

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

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. 

<code php>
// 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');
</code>


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: 

<code php>
// 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); 
</code>