GuppY Help Center, help online, documentation and tutorials

GuppY 5.02


You are here :   Welcome » Plugins tutorial
Preview  Print...  Print this page...
Preview  Print...  Print this section...
FAQ GuppY <= 4.6.xx

In this menu you will find all the FAQs on earlier versions of GuppY.

FAQ GuppY v 5.01.xx

Here you will find FAQs on Guppy version 5.01.xx.

FAQ system

These FAQs address issues related to hosting and the system in general.


In this box you will find documentation and tutorials


Here you will find important information regarding regulations and copyright

rss This article is available in the standard RSS format for publication on your website :

            Types and Structure
            Admin Part
            Public part
            Going further


In computing, the term plugin (or plug-in) is used to describe a program that interacts with a main software, called a host program to provide it with new features.
To match Guppy, a plugin must:

            be bilingual
            bear skins
            be valid for HTML 5
            preferably use a "flat file" database

This tutorial is intended as an introduction to creating plugins for Guppy 5.0 manual.
In this document, we will give you the must know basics to create a plugin. To this purpose, we'll start with some very important reminders about safety.
Then we will see the different possible types of plugins.
Then we will study the case of a simple Hello_All plugin.
We conclude with some tips and tricks to go further.
Before you start, you need to know PHP programming, HTML 5 and CSS 3 languages.
The security of your plugin must be your priority.

            Never believe that a variable from a form or url parameter contains what you think you have put in it.

            Check the values ​​from the url (GET) or form (POST) before use.

            Especially those serving in functions include, require ... Initialise variables before use $toto =''; or $toto =
            array(); for a table, do
            not rely on the default PHP should have given them.
            Use constants for constant values ​​(path config ...).

            Put an index.php file linking to the top directory in every directory of the plugin to prevent indexing plugin files.

(This document contains the basics and example written for version 4.6 document and translates Hspam).
Types of plugins

Three types of plugins are available:

        Boxes plugins : they display data in one or more boxes Guppy, they can define header boxes, side, side plants
        and footer.

        Plugins for main display: they display data in Guppy main display area.

        Those reserved for the administration: They are meant only for the administrator and are not accessible to the public. A plugin can be in one, two or the three cases at a time.


With the Guppy system, there are four places where you need to store plugin files. One for administrative tasks, one for the public part of the plugin, one for storing data and the latter, often omitted but nevertheless useful.


        plugins / my-plugin /




First here's an overview of all the files that we create for our hello_world plugin.
The administration part
The public part
The documentation part
Too often neglected, it must be integrated into your plugin.
The first documents to be included: the classic readme.txt and readme.txt. Do not put them in the main directory Guppy, they would inevitably be crushed by the other file plugins.
Then of course one or more documents explaining the installation (chmods) and running of your plugin. These documents, preferably in html, will be displayed in the administration area of the plugin.
Documentation in both languages ​​(or more) is always appreciated.
The administration part
Create a hello_world sub-directory in the directory admin/plugins/.
We will put some files in this directory admin/plugins/hello_world/ .
1 / start with the index.php file. Its contents are:
<?php header ('location: / index.php..'); ?>
2 / The second file is The contents of this file consists of the initialisation of several variables. Its contents are:
// Security
if (stristr ($ _SERVER ['SCRIPT_NAME'], '')) {
    header ('location: /index.php..');
    die ();
// Include the language file
if (is_file (CHEMIN. 'plugins/hello_world/lang/. $ lng.' ')) {
    . include PATH 'plugins/hello_world/lang/' $ lng ';
} else {
    . include PATH 'plugins/hello_world/lang/';
// Plugin name
$ Plugin_admin_name = 'hello_world';
// Plugin administration Part
$ Plugin_admin_url = 'hello_world/hello_world_admin';
// Icon in the plugin administration area
$ Plugin_admin_icon = 'hello_world/hello_world.png';
// Structure for clean plugin uninstall
$ Plugin_datas_uninstall = array (
    'Dirs' => array ('plugins/hello_world'
    Admin/plugins/hello_world ')
    'Files' => array (),
    'Include' => 'admin/plugins/hello_world/'
    'Function' => 'hw_uninstall');
// Add the side box (a function that will add the box to the list)
AddPluginBox ($ world [1], 'plugins/hello_world/hello_world_user', 'fbox_hello_word' BOX_LEFT.BOX_RIGHT); // Side box plugin
See the detail of this file:
- Security Block blocks the direct call of the script, it must be present at the beginning of all files 'inc.'
- The link to the language file uses the PATH constant, allowing to use a path relative to the site root for inclusion. It also uses the variable $lng that contains the current language. Note that the plugin must be bilingual, presence of the file must be tested and if needed, the english language file will be loaded.
- $plugin_admin_name contains the plugin name that will be displayed in the administration console.
- $plugin_admin_url contains the relative path to the plugin administration from the /admin/plugins/without extension 'inc.'.
- $plugin_admin_icon contains the relative path from the directory/admin/plugins/ to the plugin icon that will be displayed in the administration console.
- $plugin_datas_uninstall is a structure for uninstalling the plugin. Uninstalling is the responsibility of the designer who is the most qualified person to perform a clean uninstall. This structure is not mandatory but strongly recommended. It contains the following items:
    dirs: a table of directories to be removed
    files: a table of files to be deleted which are not stored in directories to uninstall
    include: the name of the file that contains the function de d"sinstallation
    function: the name of the function that will run the uninstall
- AddPluginBox() adds the side box through the fbox_hello_world() function, declared in the script. The variable $world[1] is the title of the side box .
In variables, Guppy automatically considers both URLs are references to a *.inc file, you must curb your desire to add the file extension.
3/ With the third file, you can configure the plugin via the GuppY admin area .
In Hello_world plugin, that comes with this article, we show you how you can add an icon in the navigation bar used by visitors to activate the plugin. This example is not the easiest part of of hello_world plugin code, but can be very useful if you want to use an icon in the navigation bar to your plugin. It's just a matter of copy/paste and change a bit of code.
In the second file, you have seen that the URL for the administration is pointing at hello_world/hello_world_admin. As explained above, Guppy automatically considers that the extension of this file is. inc. And the name of the third file is
For the full contents of this file, refer to the plugin Hello_World attached.
The minimum content of a file to configure the plugin through the admin area is:
// Security
if (stristr ($ _SERVER ['SCRIPT_NAME'], '')) {
    header ('location: / index.php..');
    die ();
// Include the language file
. include PATH 'plugins/hello_world /' $ lng ';
// Always start with the following 4 lines
include PATH 'inc /';
// Top of page
htable($world [0], '100% '); // central box header with the name of the plugin
// Include the header file of the admin page on its rights
if ($wri == 'admin') include PATH 'admin/administrateur.php.;
. if ($wri == $userprefs[1]) include PATH 'admin / adminredac.php';
/ / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / /
// Your PHP and/or HTML code ... //
/ / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / /
// Always end the file with the following lines
// No need to references to the admin page, under the new structure, tabs
// Linear dropdown menu is always at your disposal
btable(); // End admin box
. include CHEMIN.'inc/'; // Right column and footer
Note variables $world that come from the language file.
More information about the language file at the end of this article!
4 / Finally there is a fourth file that you also find in This is the icon used in the admin area for this plugin.
Called in this case hello_world.png. The icons are 42 * 42 pixels.
The public part
This section of the plugin Hello_World treats the part that visitors to your website will see.
Create a hello_world subdirectory in the /plugins/ directory
/ We start again with the index.php file. Its contents are:
<?php header ('location: /index.php..'); ?>
2 / The second file is The contents of this file consists of several variables. Its contents are:
// Safety
if (stristr($_SERVER['SCRIPT_NAME'], '')) {
    header ('location: /index.php..');
define (CHEMIN', '../ ../ ');
/ / Include the language file
if (is_file(CHEMIN.'plugins/hello_world/lang/'.$lng.'')) {
    include CHEMIN.'plugins/hello_world/lang/'.$lng.'';
} else {
      include CHEMIN.'plugins/hello_world/lang/';
// Plugin name
  include CHEMIN.'plugins/hello_world/lang/';
// The next two lines are references to files in the plugin directory/hello_world /
// The url to activate when you click the icon
$plugin_bar_url = 'hello_world.php';
// Icon
$plugin_bar_icon = 'img/hello_world.png';
You do not need this file if you do not use an icon in the navigation bar!
See the detail of this file:
– define("CHEMIN", "../... / ") Defines the relative path to return to the site root.
- $plugin_bar_name contains the name that will be displayed in the menu bar.
- $plugin_bar_url contains the url relative to the plugin directory of the php file containing the public home page of the plugin, which will be called when clicking on the menu bar.
- $plugin_bar_icon contains the url relative to the plugin directory of the icon that will be displayed in the menu bar.
3/ The third file called already mentioned in the file admin/plugins/
This file contains a function that creates the side box.
For the full contents of this file, refer to the plugin Hello_World joint.
The minimum content for a side box is:
// Security
if (stristr($_SERVER['SCRIPT_NAME'], '')) {
function fbox_hello_world($pos, $args) {
    // Declare the necessary system variables
       global $lng, $lang, $site, $serviz, $userprefs, $drtuser, $page, $tconfig, $reptheme, $web;
    // Include the language file
    include CHEMIN.'plugins/hello_world/lang/'.$lng.'';
    // Include configuration file plugin
    include CHEMIN.DATAREP.'plugins/hello_world/';
    // La variable $out contient le code HTML de votre boîte
    $out = '
      <div style="text-align: center;padding: 12px;">
        <A href = "'.CHEMIN.'plugins/hello_world/hello_world.php?lng='.$lng.'" title="hello_world" />Hello !</a></a>
    // Set the quick administration icon
    if (($serviz[32] == 'on' && !empty($serviz[31]) && ($serviz[31] == $userprefs[1]) || $serviz[32] == 'on' && $drtuser['hello_world'] == 'on')) {
        $out .='
          <div class="f-right">'.displayQuickConfig($pos).'
            <a href="'.CHEMIN.'admin/admin.php?lng='.$lng.'&pg=plugin&plug=hello_world/hello_world_config" title="">
              <img alt="'.$web[308].'" src="'.$reptheme.'/edit.png" style="border:0;" title="'.$web[308].'" />
          </div><div class="c-right"></div>';
    // End function for a side box by this line
    return boxthin($pos, $world[1], $out, ' H_W'.$tconfig, $hwdynabox);
} // End of function
The side box must be enabled in Admin>Settings>Config boxes!
Let's see the detail of this file:
– function fbox_hello_world($pos, $args), the execution of this function will display hello_world side box, the parameters of the function, $pos gives the position of the box in the structure of the page, $args contains the arguments passed to function, they are transmitted by the function of execution of the GuppY engine .
- global: inside a function global variables are not visible, so it should be reported. For example, $lng that contains the language used must be visible to load the language file of the plugin.
- $out is the variable that contains the HTML 5 code shown in box. It will be sent to boxthin() function that takes care of displaying the entire box, title and content.
- If (($serviz [32] == .... This code has the function to display at the bottom right of the box small icons of quick administration
- return boxthin(), returns the whole box formatted using the parameters supplied, $pos is the position of the box, $world[1] is the title of the box, $out is the contents of the box, 'H_W is the name of a pseudo class that can be used to customise the box, $tconfig is a global variable that defines the number of the display page and eventually $hwdynabox a configuration parameter that defines the status of the box (open, closed, static). This last parameter is defined in the admin plugin configuration
4 / The fourth file is hello_world.php that will be activated by the plugin icon in the navigation bar (if present). This file will also be activated by a link in the side box.
The aim is that the output of this file is shown in the central portion of a page.
The content looks like this:
/* Security
* This time no security code (4 lines)
* you've seen in any other file. Php and. Inc.
* because this file. Php is called by a direct link.
// Start with the following lines to display the output in a central box
header('Pragma: no-cache');
define('CHEMIN', '../../');
include CHEMIN.'inc/';
include CHEMIN.'inc/';
// Include the language file
include CHEMIN.'plugins/hello_world/lang/'.$lng.'';
// Header of box
htable($world[1], '100%');
// Your PHP code and/or HTML
echo '<h3>Hello World</h3>';
// Always end with the following lines
include $CHEMIN.'inc/';
Let's see the detail of this file:
– header('Pragma: no-cache') not to cache the page, if a dynamic page.
– include CHEMIN.'inc/'  loading GuppY engine
- The other elements have been seen before.
5 / One of the nice features Guppy is to be able to go bilingual. This means it is important to make your plugins easily translatable and easy to use bilingual. To make it bilingual, we've added the following line in the code we talked about earlier:
// Including the language file
include CHEMIN.'plugins/hello_world/lang/'.$lng.'';
$lng variable contains the language code. For example: if your site is in French the name of the file is The language file contains variables. These variables are used in the plugin code. To make the plugin used in other languages, we only need to rename the language file and translate the contents of variables.
For example: to translate plugin into Spanish, we duplicate and rename the file and and translate the contents of variables.
The language file of the plugin Hello_World contains :
// Safety
if (stristr($_SERVER['SCRIPT_NAME'], '')) {
/ / Variables of  language used by the plugin Hello_World
$world[0] = 'Admin - Plugin Hello World'
$world[1] = 'Hello World';
$world[2] = 'Set the icon' Hello World 'in the navigation bar'
$world[3] = 'Put here the code for administration tasks (if necessary)
$world[4] = 'Put here the code for the visitors section (if necessary)';
$world[5] = 'Click here';
$world[6] =  'Uninstall plugin';

It is advisable to make a subdirectory lang/to separate these files from others and ease their identification by the translators.
On large plugins, you can split the language file in 2 parts, a postfix 'admin' and another postfix 'web' respectively for Administration and Public parts of the plugin.
6/ Finally there is a sixth file that you also find in The icons are 42 * 36 pixels. This icon may be the same as that used in the admin area. You do not need this file if you do not use this plugin icon in the navigation bar or in the central box!
7/ Points to consider.
For each file. Inc. and. Php of your plugin, start directly after the first <?php with comment lines indicating the name of the plugin, the distribution licence, author, your website.
   / *
    Plugin: Plugin name
    Licence: CeCILL
    Name: your name or username
    Website: Your website (for support)
    Do not add your email address to avoid spam!
    Helpful comments about the changes to the file

    Add a clear documentation about the purpose of the plugin, how to install it (CHMOD) and how to configure it.
    Once completed, submit your plugin to beta testers. Nothing beats user reviews.
    Once validated and verified, announce it on FreeGuppY and submit it on GuppYLand.
Going further
Browsing a multi-page plugin
Access the administration page of a plugin always means going through admin.php (which manages access rights), with two parameters:
- "pg" that contains the value 'plugin', to say that a plugin is accessed.
- "plugin" that contains the relative path to the plugin admin page from the /admin/plugins / without extension 'inc.'.
If we take the example of the plugin "hello_world", address of the administration page of the plugin is the following html:
echo CHEMIN.'admin/admin.php?lng='.$lng.'&pg=plugin&plug=hello_world/hello_world_admin';
Defining several lateral and central boxes
To do this, you will have to modify the file admin/plugins/my-plugin/
Create a file .inc. in plugins/my-plugin/ per box, for example,, etc ...
Each will contain the corresponding function, fbox_my_first_box ($pos, $args) for the first file, fbox_my_second_box ($pos, $args), and so on.
Support these boxes will be done in the file admin/plugins/mon_plugin/ with the following statements:
AddPluginBox($box_name[1], 'plugins/mon_plugin/my_first_box', 'fbox_my_first_box', BOX_LEFT.BOX_RIGHT);
AddPluginBox($box_name[2], 'plugins/mon_plugin/my_second_box', 'fbox_my_second_box', BOX_LEFT.BOX_RIGHT);
Note that BOX_LEFT.BOX_RIGHT indicates that the use of the box will be possible only in the left and right columns. It is possible to write it like this: 'LR'.
To make the box available in all locations of a page 'LRAEUTB' should be indicated, or the predefined constants used.
Add the plugin in the menu bar
The example of Hello_world plugin
// necessary functions integration
include 'plugins/';
// This part saves the state of the plugin in the menu bar
// The three occurrences of "hello_world" match the name of the plugin directory
$regits = import ('regit');
if ($regits == 1) {
    $hello_world = import('hello_world');
    if ($hello_world == 'on') {
        if (!PluginRegistered('hello_world')) RegisterPlugin('hello_world');
    else UnregisterPlugin('hello_world');
// Form to (un)register plugin
echo '
<form name="hello_world" action="admin.php?lng='.$lng.'&pg=plugin&plug=hello_world/hello_world_admin" method="post">
  <input type="hidden" name="regit" value="1" />
  <p>'.$world[2].'&nbsp;&nbsp;<input type="checkbox" name="hello_world"'.Checked(PluginRegistered('hello_world')).' /></p>
  <p style="text-align:center;">. <p style="text-align:center;">'.SubmitButton($admin[66]).'</p>
</form> ';
Let's see the details of this code:
– include 'plugins/' permet d'avoir accès aux fonctions PluginRegistered(), RegisterPlugin() et UnregisterPlugin()
– si le formulaire est validé ($regit == 1) on lit le contenu de $hello_world
- If the box is checked ($ hello_world == 'on') then if the plugin is not already registered(!PluginRegistered('hello_world'))
we register it : registerPlugin('hello_world');
- Otherwise you unregister it : unregisterPlugin('hello_world');
- Note the use of the form function Checked() which will display if needed checked = "checked", likewise the SubmitButton() function that displays the form button.
Insert text editors
We will see how to integrate the plugin administration of the basic or advanced editors of Guppy compared to the configuration in Admin>Settings>Config Services.
Showing editors in a form
1 / To begin with, insert the necessary functions and store reusable flags left of the form fields.
require CHEMIN.'admin/editors/editors_functions.php';
$flag1 = '<img src="'.CHEMIN.INCREP.'lang/'.$lang[0].'.gif" style="vertical-align:middle;border:0;" alt="'.$lang[0].'" />'; alt="'.$lang[0].'" />';
$flag2 = '<img src="'.CHEMIN.INCREP.'lang/'.$lang[1].'.gif" style="vertical-align:middle;border:0;" alt="'.$lang[1].'" />'; $wysiwyg = $serviz[49] == 'on' ? true : false;
$wysiwyg = $serviz[49] == 'on' ? true : false;
2 / Then we display the form with the editor in one or two languages ​​depending on the configuration of Guppy.
echo '
<form name="adminsend" action="admin.php?lng='.$lng.'" method="post">
  <input type="hidden" name="pg" value="plugin" />
  <input type="hidden" name="plug" value="mon-plugin/monplugin" />
  <input type="hidden" name="regit" value="1" />';
// Primary Language
echo '
  <div style="text-align: center; margin: auto; width: 560px;">
    <label for="contenu1">. $ flag1. ' <label for="contenu1">'.$flag1.' Texte en langue principale</label><br />
    '.display_admin_editor('contenu1', '540px', '400px', $contenu1, $wysiwyg).'
    <p style="text-align: centre;">.<p style="text-align: center;">'.SubmitButton($admin[66]).'</p>
if ($lang[1] != '') {
// Secondary Language
   echo '
  <div style="text-align: center; margin: auto; width: 560px;">
    <label for="contenu1">. $ flag2. ' <label for="contenu1">'.$flag2.' Texte en langue secondaire</label><br />
    '.display_admin_editor('contenu2', '540px', '400px', $contenu2, $wysiwyg).'
    <p style="text-align: centre;">.<p style="text-align: center;">'.SubmitButton($admin[66]).'</p>
echo '
</form> ';
Lets' see the details of this code:
- require : the Seller is loaded that contains all the necessary functions of editors
- $flag1 $flag2, these two variables contain images of the site lanquage
- $wysiwyg gets the Editor's Choice in Config services, the variable will be passed to the function that handles editors
- The form is classic in admin, it displays the flag of language associated with a label, followed by the function call
- So display_admin_editor() is the function to display the editor, whether WYSIWYG or not.
    'Content1 is the name of the variable data returned
    Then come the width and height of the editor in pixels
    $Content1 contains the text to edit
    and finally $wysiwyg will determine the editor to use: CKEditor or minieditortextarea
- If ($lang[1]!='') this tests if a secondary language is present, then it displays the editor a second time with the corresponding values.
Processing form data
With CKeditor we transform relative paths into absolute ones.. But before storing the data, you must do the opposite.
if ($regit == 1) {
    $text1 = import('contenu1');
    $text2 = import('contenu2');
    $text1 = PathAbsoluteRelative($text1);
    $text2 = PathAbsoluteRelative($text2);
    $txt   = "<?php
$contenu1 = stripslashes("$text1");
$contenu2 = stripslashes("$text2");
    WriteFullDB(CHEMIN.DATAREP.'plugins/mon_plugin/', $txt);
Let's see the details of this code:
– if ($regit == 1) $regit is treated by the form
- $text1, $text2, values are recovered and formated.
- PathAbsoluteRelative converts absolute paths to relative ones.
Showing the texts
The texts are saved with paths relative to the site root. So the images and links do not work when the page where the text is displayed is plugins/my-plugin/monplugin.php.
No worries, Guppy has a function to correctly restore the relative paths. Just do:
echo PathToImage($contenu1);
Uninstalling the plugin
For hello_world plugin, we'll achieve unsinstallation in the script admin/plugins/hello_world/
Let's add a small form to begin the uninstallation:
if (isset($plugin_datas_uninstall)) {
    echo '
<hr />
<div style="width:480px;text-align:center;margin:auto;">
  <form name="uninstall" action="admin.php?lng='.$lng.'&pg=plugin&plug=hello_world/hello_world_admin" method="post">
  <input type="hidden" name="regit" value="unplug" />
  <p style="text-align:center;">'.SubmitButton($world[6]).'</p>
Let'see the details of this code:
- If (isset($plugin_datas_uninstall)), we test the existence of the structure uninstall declared in admin/plugins/hello_world /
- It displays the form that contains only the submit button
Then you must meet the request:
if ($regit == 'unplug') {
    $dirs  = $plugin_datas_uninstall['dirs'];
    $files = $plugin_datas_uninstall['files']
    foreach ($dirs as $dir) RecursiveRemoteDir(CHEMIN.$dir);
    foreach ($files as $file) @unlink(CHEMIN.$file);
    echo BeginJavascript().'
'.EndJavascript();EndJavascript ();
You have reached the end of this tutorial on a very simple example. You have the key elements that will allow you to create your own plugin for Guppy version 5.0.
When your plugin is developed, it is time to create a .zip archive with the Manifest file that will allow users of Guppy Version 5.0.x to install it directly in line with the admin function>General Administration>Install.
The MKZip utility, created by JeanMi to create your .zip archive is available at the end of this article. Install it on your hard drive. Suffice it to launch the script mkzip.php and complete the necessary fields.
Where to find plugins?
GuppYLand is the site worth visiting:
CeCILL licence
The full manual is subject to the CeCILL Licence, which means:
    that everyone has the right to freely use the manual.
    that any person is authorised to distribute the manual.
Guppy software is subject to the CeCILL licence. You can find more details about it here:
Link to download the plugin Hello World: hello_world.png
Link for downloading the utility MKZip: zip.gif

Creation date : 02/03/2015 @ 16:39
Last update : 17/06/2016 @ 10:41
Category : - Docs and Tutorials-Plugins tutorial
Page read 21553 times

You are here :   Welcome » Plugins tutorial
Preview  Print...  Print this page...
Preview  Print...  Print this section...

 1516734 visitors

 3 visitors online

Webmaster - Infos

On each page in admin, if you click on this icon, you get the online help page.

Site registered in the CNIL under agrément 1040387.
You have a right of access, modification, rectification and deletion
of the data according to the Computer law and Freedom (article 34) of January 6th, 1978.


The hosting is provided by our partner