====== Create a plug-in for posh ======

===== For version >2.1 =====

We have added some changes in plug-in integration because admin is written in Ajax. Change concerns configuration datas.

To add configuration form for your plugin, you have to add a new function which opens your configuration form in an iframe.


Example in plug_display function:

<code php>

 register_hook("display_plugin","myplug_display",10,1);
 
 register_hook("iframe_plugin","iframe_myplug",10,1);

 function myplug_display($info)
 {
	if ($info['name'] == 'my plugin') {
        if ( isset($info["ajaxplug"]) && $info["ajaxplug"] == 1) {
            echo '<iframe frameborder="0" marginwidth="1%" height="250px" width="80%" '
                       . 'src="../admin/scr_plugin.php?plugname=iframe_myplug"></iframe>';
        } else {
            require_once("plugin_config.php");
        }
    }
 } 

 function iframe_myplug ($name) {
    if($name == "iframe_myplug" ) {
        if( isset($_POST['enregistrer']) ) {
            require_once("../includes/plugins/myplugin/scr_myplugin_config.php");
        }
        require_once("../includes/plugins/myplugin/myplugin_config.php");
    }
 }
</code>


===== For version >1.4 =====

A new plugin system based on hooks is proposed in this version. It allow more flexibility for posh developpers.
Take a look to the example file **plugin.php** to have more informations. \\

[[development:plugins:hooks|The list of the available hooks is here]]



==== Plugin root file ====

You will need a **plugin PHP root** file. If your plugin uses more than one file, you have to group them in a directory.
Place it (your unique file or folder) into /includes/plugins

A plugin root file is identified with its content : it have to **start** with a **commented section** in a specific format.

Here is an example :

<code php>
/*
 * name: Your plugin name
 * description: Empty plugin
 * dependencies: no
 * author: you
 * url: http://yourwebsite.com
 */
</code>

You just have to replace junk infos by yours. This header identifies a plugin root file. If your plugin is not detected, please verify that this header is present.




==== Coding rules ====

=== Naming functions ===

You will need to create functions in your PHP code. Please **add before each function a prefix** that identifies your plugin.

Example :
<code php>
function foo_myfunction(){
}
// Instead of
function myfunction(){
}
</code>

=== Database access ===

Please use the global object $DB which is loaded before your plugin.
  * Escape every parameter retrieved by $_POST, $_GET, $_COOKIE, $_REQUEST or from the Database with **$DB->escape()** for security reasons
  * When using string parameters, using $DB->quote($foo) avoid writing **'"'.$DB->escape($foo).'"'**








==== Plugin installation ====

If you plugin have to process some code when installing it, such as creating tables in the database, you will need this section.

Here is an example :

<code php>
/*
 * Your function to launch when the plugin is installed
 */
function foo_install()
{
  // Your code here
}

/*
 * Registers your function as the one to be launched
 */
register_hook('install_filePathWithoutPhp','foo_install');
</code>

Just replace **fileNameWithoutPhp** by the root file name without ".php". If your file name is "plugin.php" the hook will be **install_plugin**.

If your file is in a directory, you will use a hook name like **install_directory/filename**. 



==== Launch your actions when appropriate ====

  - Look for the instruction **launch_hook('name',parameters)** into the code where you want to add a behaviour.
  - **Create your function** in your plugin file that will be launched when the instruction launch_hook is called
  - **Register your function** with the line **register_hook('name','function',priority,parameters)**

Here is more informations about this function :
<code php>
/*
 * register_hook : registers a function for a specified hook
 * Input :
 *	$hookname (string) : hook for which you register the function
 *	$function (string) : function to call when calling this hook
 *	$priority (int) : lowest priority value => first to be called
 * 	$args (int) : number of arguments that the function accepts
 */ 
function register_hook($hookname,$function,$priority=10,$args=0)

</code>

==== Examples ====

** Add a tab in admin panel ** \\

<code>

register_admin_tab('myplug_tab','Your new tab','myplug_admin_display');
 
 function myplug_admin_display()
 {
    echo "<h2>Content of the new admin page</h2>";
 }

</code>
\\
**Add a feature in admin panel**

<code>

register_hook('install_new_admin_feature/plugin','new_admin_feature_install');
 register_hook('uninstall_new_admin_feature/plugin','new_admin_feature_uninstall');

function new_admin_feature_install(){

  add a feature in the adm_tabs_fct table (with $DB->execute(...))

}
function new_admin_feature_uninstall(){

  Remove feature from adm_tabs_fct table

}

</code>
\\
**Change the way the users are connecting to Posh** : see LDAP plugin
\\ \\ \\
**Add javascript in users interface**

<code>

<?php
/*
 * name: Enterprise main tools
 * description: Main enterprise features (social network, proxy & ldap, ..)
 * dependencies: no
 * author: Portaneo
 * url: http://www.portaneo.net
 */
 
register_hook('userinterface_header','loadEnterpriseJavascript',5,1);

function loadEnterpriseJavascript($version){
    echo "<script type='text/javascript' src='../includes/application.js?v=".$version."' ></script>";
}

</code>
\\
**Add new features in users interface**\\
To add new items to the menu of the header

<code>

register_hook('install_new_feature/plugin','new_feature_install');
 register_hook('uninstall_new_feature/plugin','new_feature_uninstall');

function new_feature_install(){

  Add new feature in the adm_headlinks table

}
function new_feature_uninstall(){

  Remove the feature from the adm_headlinks table

}

</code>

===== For version 1.3 =====

//__This is an ALPHA stage functionality. Do not hesitate to send us your remarks to improve it.__//

**__Attention, this feature is currently rebuild, and should be different for v1.4. Please wait for this version to create your plugin !__**

==== Files used ====
If the name of your plugin is "plugin test", the required files are : \\ \\

  plugin_test.info : Plugin configuration file
  plugin_test : Directory containing following plugins files (and the others plugin is using) :
    |-- plugin.php : file called by each posh PHP file
    |-- install.sql : SQL queries executed on plugin installation
    |-- uninstall.sql : SQL queries executed on plugin uninstallation
\\



==== Configuration files ====
The .info file is used to provide all the information related to the plugin to posh. This file must be placed under /includes/plugins/ . \\ \\
It contains following information (each element is required. The information between < and > signs must be replaced by the ones of your plugin) :
  name=<Name of the plugin (60 char. maxi). eg: test plugin>;
  description=<Description of the plugin.>;
  dependencies=<Name of the plugin to install to have this one worked 
    or //no// if no other plugin is required>;
  link=<link of the file that will be includes in posh PHP files. eg: test/plugin.php>;
  directory=<Directory containing plugin files. eg:test (if directory is /includes/plugins/test/)>;
  version=<plugin version>;



==== Installation files ====
These files are required and must be placed in the plugin folder (given by the .info file). \\
- install.sql : SQL queries that will be automatically executed on plugin installation. Do not forget the ; sign at the end of each query. \\ eg: UPDATE adm_config SET value="new message" WHERE parameter="bartexthtml";\\ \\
- uninstall.sql : SQL queries that will be automatically executed on plugin uninstallation. It is used to clean up objects/data created by the plugin. \\ eg: UPDATE adm_config SET value="" WHERE parameter="bartexthtml";



==== Insert your scripts in posh files ====

The file mentionned in the .info file (link parameter) is called in all PHP pages/scripts. \\
You can insert PHP code\\
- that will be executed in all PHP files \\
- that will be executed only in a file
  if ($pagename=="portal/mypage.php"){echo "message displayed only in the connected portal page";}
- that will be executed only in PHP files that generate HTML
  if (!$isScript){echo "message displayed in all posh pages";}
- that will be executed only in page displaying modules
  if ($isPortal){echo "this is a personalized portal";}
\\ \\
To insert javascript :
  if (!$isScript){
    echo "<script type=\"text/javascript\">alert(\"message displayed in all page thanks to javascript\");</script>";
  }
Do not hesitate to inspire from other plugins.