This is an old revision of the document!


Plugin Tutorial: Hello world!

In this tutorial you will learn how to write a tiny plugin, showing an admin page with the traditional “Hello world!” text in it. The entire plugin can be installed from the extension gallery under the name 'Skeleton', so that you can use it as a basis for later plugins.

Assumed knowledge

In this tutorial it is assumed that you have good knowledge of PHP and HTML. If not, recommended manuals are W3Schools and PHP.net.

Besides that, it is assumed that you know how to create and manipulate files and folders on your Piwigo install. (Presumably via FTP or SSH.)

General recommendations

It is in general a good idea to think of security when writing plugins. And it is good practice to do it from the start. Piwigo provides several ways of doing this. For example, when writing PHP files for a plugin, you can prevent unintended use of those files by putting the line

if (!defined('PHPWG_ROOT_PATH')) die('Hacking attempt!');

at the top of you files.

To stop the webserver of showing directory contents of certain directories, one can put a file 'index.php' in it, with as contents

$url = '../';
header( 'Request-URI: '.$url );
header( 'Content-Location: '.$url );
header( 'Location: '.$url );
exit();

Lastly, when using databases, you should be aware of the risk of SQL-injections. Piwigo provides a database layer abstraction, and one very useful function from it is

pwg_db_real_escape_string($string);

which escapes strings, to make them ready for insertion in a database. It is not the intention of this article to teach about SQL-injections. If you do not know what SQL-injections are, make sure you read more about them. They are nasty and dangerous!

The bare minimum contents of a plugin

There are a number of files that you will see in nearly each plugin of Piwigo. Here follows a list, with a small description of what the files are meant for.

index.php         # With contents as above.
main.inc.php      # The central file of the plugin, which Piwigo includes.
maintain.inc.php  # File containing functions for install and activation of the
                  # plugin.
admin.php         # An administration page for the plugin.
admin.tpl         # The layout for admin.php
language/         # Directory containing all language files, translations of
                  # the plugin.
include/          # Directory containing miscellaneous files to be included by
                  # others.

Starting the writing

In this tutorial we will focus on 'main.inc.php', 'admin.php' and 'admin.tpl'. For an example of 'maintain.inc.php' and internationalization via 'language/' see the next tutorial on the 'Copyrights plugin'.

Preparations

Go to the 'plugins/' folder of your Piwigo install, and create a folder named 'skeleton/'. In this folder we will save all the files for our plugin.

main.inc.php

So let us start with the contents of 'main.inc.php'. We first give some general information to Piwigo, about the plugin, its author and its use.

<?php
/*
Version: 1.0
Plugin Name: Skeleton
Plugin URI: // Here comes a link to the Piwigo extension gallery, after
            // publication of your plugin. For auto-updates of the plugin.
Author: // Good practice to put your forum username here.
Description: The skeleton for a Piwigo plugin, providing 'Hello world!'.
*/

Next, we check whether the plugin is indeed being used by Piwigo. If not, we could not assume the availability of lots of functions and definitions. Afterwards we define the path to our plugin. (Note that we immediately make use of the assumption that 'PHPWG_PLUGINS_PATH' is defined and available.) Make sure your 'define()'s are unique, since they should not mess up with Piwigo or other plugins. E.g. do not just define 'PATH' :-).

// Chech whether we are indeed included by Piwigo.
if (!defined('PHPWG_ROOT_PATH')) die('Hacking attempt!');
 
// Define the path to our plugin.
define('SKELETON_PATH', PHPWG_PLUGINS_PATH.basename(dirname(__FILE__)).'/');

Now comes the most important and difficult part of plugin writing: Piwigo's events and actions. More on Piwigo's events and actions is covered at the end of this tutorial, and in the next tutorial on the Copyrights plugin. The idea is that all over the Piwigo core events are placed, and when one is triggered, all functions hooked on to it are executed.

In this tutorial we hook on to an event named 'get_admin_plugin_menu_links', which is triggered when one clicks on 'Plugins' in the Administration area of the Piwigo install. Hooking on to an event is done with the function 'add_event_handler($event, $function)'.

// Hook on to an event to show the administration page.
add_event_handler('get_admin_plugin_menu_links', 'skeleton_admin_menu');

This means that a function 'skeleton_admin_menu' should be written. We better do that right now. A property of the 'get_admin_plugin_menu_links' event is that it calls all functions hooked to it with an argument '$menu'. This variable contains the menu that you see when you go to the Plugins section of the Administration area. So with our function we will add our own entry to it. Such an entry should consist of an associative array that contains a 'NAME' and an 'URL'.

// Add an entry to the 'Plugins' menu.
function skeleton_admin_menu($menu) {
  array_push(
    $menu,
    array(
      'NAME'  => 'Skeleton',
      'URL'   => get_admin_plugin_menu_link(dirname(__FILE__)).'/admin.php'
    ) 
  );
  return $menu;
}
?>

As you might have noticed by the '?>' on the last row of this code part, this is indeed the end of our file 'main.inc.php'.

Intermezzo

If you would save this file in your 'skeleton/' folder, you can go to the 'Plugins' section in the Administration area of your Piwigo install and notice that at the bottom of you Plugins list there will be an uninstalled plugin 'Skeleton'. You can install and activate this plugin, and will then indeed see an entry of our plugin in the Plugins menu.

Problem: If you click the link, it reports you there is no 'admin.php' found. But we expect that, since we did not write it yet :-). Let's do that right now.

admin.php

We start of again with the check if this file is included by Piwigo.

<?php
// Chech whether we are indeed included by Piwigo.
if (!defined('PHPWG_ROOT_PATH')) die('Hacking attempt!');

Now comes again a new thing to learn: Smarty and its templates. Piwigo uses Smarty and templates to generate and layout its pages. If you do not know Smarty, that does not matter for this tutorial. But it is recommended that you read a tutorial on Smarty. (For example the Smarty crash course.)The entire layout is is managed by the global variable '$template'.

// Fetch the template.
global $template;

After globalizing the '$template' variable, we can add our 'admin.tpl' template to it. (We will write 'admin.tpl' below.)

// Add our template to the global template
$template->set_filenames(
  array(
    'plugin_admin_content' => dirname(__FILE__).'/admin.tpl'
  )         
);
 
// Assign the template contents to ADMIN_CONTENT
$template->assign_var_from_handle('ADMIN_CONTENT', 'plugin_admin_content');
?>

Normally all sorts of SQL-queries, and binding of variables to Smarty take place in files like these. But that goes beyond the scope and intention of this tutorial.

admin.tpl

We will lastly write the template for admin.php. Since we only want to show the traditional “Hello world!” string, this will not be very difficult. The most important thing to notice is that, apart from well-known HTML tags, one can put translation tags around text. The code below explains itself.

<!-- Show the title of the plugin -->
<div class="titlePage">
  <h2>{'Skeleton plugin'|@translate}</h2>
</div>
 
<!-- Show content in a nice box -->
<fieldset>
  <legend>{'A minimal plugin'|@translate}</legend>
 
  {'Hello world!'|@translate}
</fieldset>

Conclusion

Congratulations! You have just written your first Piwigo plugin. Below you can read about what to do now.

Publishing your plugin

After you have written a plugin, you possibly want to share it with others of the Piwigo community. Publishing a plugin is not very difficult. Go to the extension gallery, after you have logged in, and click the link Add an extension in the left menu. Fill out the form, and go on to the next page. You will conme in the administration area of you plugin. Here you can upload revisions and manage the authors of the plugin. Happy sharing!

Actions and events

Actions and events in Piwigo are not easy to learn. It requires experience to know which plugins should be used when. But there are ways to make it easier. First off all, install the Event tracer plugin (by rvelices); it will really help you in finding which events are triggered when you view part of your Piwigo gallery.

Furthermore you can browse the source code of other plugins, to see how they solve the problems that you encounter. Good examples are

  • Community (by plg) though it is quite large
  • Add Info Users (by ddtddt)
  • Several plugins developed by the Piwigo team.

It is also a good idea to ask questions about your problems on the forum. Please do a search first, to see whether anyone else asked that question before. If you have not yet, read How To Ask Questions The Smart Way by esr.

Lastly you can always browse the source code of Piwigo core. And if an event does not exist where there really should, you can always develop it yourself and send a patch of the code to the Piwigo team. Chance they might merge your patch, and you will have helped the community a step forward!

Further reading

  • If you do not know Smarty very well, it is a good idea to read the tutorials and manuals on Smarty.net.
  • There is another tutorial that about plugin writing, that is slightly more advanced. You can read it here Tutorial: Copyrights.
 
Back to top
plugin/plugin_tutorial1.1315921264.txt.gz · Last modified: 2011/09/13 13:41 by plg
 
 
github twitter newsletter Donate Piwigo.org © 2002-2024 · Contact