🌍
English
Differences
This shows you the differences between two versions of the page.
|
dev:extensions:plugin_tutorial1 [2011/09/13 13:52] plg recreated from backup |
— (current) | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== 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 [[http://piwigo.org/ext/extension_view.php?eid=543|'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 [[http://www.w3schools.org|W3Schools]] and [[http://www.php.net|PHP.net]]. | ||
| - | |||
| - | Besides that, it is assumed that you know how to create and manipulate files and folders on your Piwigo install. (Presumably via [[http://en.wikipedia.org/wiki/FTP|FTP]] or [[http://en.wikipedia.org/wiki/Secure_Shell|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 | ||
| - | <code php> | ||
| - | if (!defined('PHPWG_ROOT_PATH')) die('Hacking attempt!'); | ||
| - | </code> | ||
| - | 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 | ||
| - | <code php> | ||
| - | $url = '../'; | ||
| - | header( 'Request-URI: '.$url ); | ||
| - | header( 'Content-Location: '.$url ); | ||
| - | header( 'Location: '.$url ); | ||
| - | exit(); | ||
| - | </code> | ||
| - | |||
| - | Lastly, when using databases, you should be aware of the risk of | ||
| - | [[http://en.wikipedia.org/wiki/SQL_injection|SQL-injections]]. Piwigo provides a database layer abstraction, and one very | ||
| - | useful function from it is | ||
| - | <code php> | ||
| - | pwg_db_real_escape_string($string); | ||
| - | </code> | ||
| - | 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. | ||
| - | <code bash> | ||
| - | 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. | ||
| - | </code> | ||
| - | |||
| - | ===== 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. | ||
| - | <code php> | ||
| - | <?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!'. | ||
| - | */ | ||
| - | </code> | ||
| - | |||
| - | 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' :-). | ||
| - | <code php> | ||
| - | // 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__)).'/'); | ||
| - | </code> | ||
| - | |||
| - | 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)'. | ||
| - | <code php> | ||
| - | // Hook on to an event to show the administration page. | ||
| - | add_event_handler('get_admin_plugin_menu_links', 'skeleton_admin_menu'); | ||
| - | </code> | ||
| - | |||
| - | 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'. | ||
| - | <code php> | ||
| - | // 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; | ||
| - | } | ||
| - | ?> | ||
| - | </code> | ||
| - | |||
| - | 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. | ||
| - | <code php> | ||
| - | <?php | ||
| - | // Chech whether we are indeed included by Piwigo. | ||
| - | if (!defined('PHPWG_ROOT_PATH')) die('Hacking attempt!'); | ||
| - | </code> | ||
| - | |||
| - | 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 [[http://www.smarty.net/crash_course|Smarty crash course]].)The entire layout is is managed by the global variable '$template'. | ||
| - | <code php> | ||
| - | // Fetch the template. | ||
| - | global $template; | ||
| - | </code> | ||
| - | |||
| - | After globalizing the '$template' variable, we can add our 'admin.tpl' template to it. (We will write 'admin.tpl' below.) | ||
| - | <code php> | ||
| - | // 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'); | ||
| - | ?> | ||
| - | </code> | ||
| - | |||
| - | 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. | ||
| - | <code smarty> | ||
| - | <!-- 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> | ||
| - | </code> | ||
| - | |||
| - | ===== 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 [[http://piwigo.org/ext/extension_add.php|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 [[http://piwigo.org/ext/extension_view.php?eid=288|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 | ||
| - | * [[http://piwigo.org/ext/extension_view.php?eid=303|Community]] (by plg) though it is quite large | ||
| - | * [[http://piwigo.org/ext/extension_view.php?eid=531|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 [[http://www.catb.org/~esr/faqs/smart-questions.html|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 [[http://en.wikipedia.org/wiki/Patch_%28computing%29#In_software_development|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 [[http://www.smarty.net/|Smarty.net]]. | ||
| - | * There is another tutorial that about plugin writing, that is slightly more advanced. You can read it here [[en:dev:tutorial2|Tutorial: Copyrights]]. | ||