diff --git a/Plugin-Tutorial:-Hello-world!.md b/Plugin-Tutorial:-Hello-world!.md new file mode 100644 index 0000000..cace55d --- /dev/null +++ b/Plugin-Tutorial:-Hello-world!.md @@ -0,0 +1,283 @@ +# 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'](http://piwigo.org/ext/extension_view.php?eid=543), 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](http://www.w3schools.org) and [PHP.net](http://www.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](http://en.wikipedia.org/wiki/FTP) or +[SSH](http://en.wikipedia.org/wiki/Secure_Shell).) + +## 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 + +``` php +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 + +``` php +$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](http://en.wikipedia.org/wiki/SQL_injection). Piwigo +provides a database layer abstraction, and one very useful function from +it is + +``` php +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. + +``` 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. +``` + +## 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 + '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 +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. + +``` smarty + +
+

{'Skeleton plugin'|@translate}

+
+ + +
+ {'A minimal plugin'|@translate} + + {'Hello world!'|@translate} +
+``` + +## 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](http://piwigo.org/ext/extension_add.php) 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](http://piwigo.org/ext/extension_view.php?eid=288) (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](http://piwigo.org/ext/extension_view.php?eid=303) (by plg) though it is quite large +* [Add Info Users](http://piwigo.org/ext/extension_view.php?eid=531) (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](http://www.catb.org/~esr/faqs/smart-questions.html) 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 create a pull-request on the Piwigo repository. Chance they might merge it, 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](http://www.smarty.net/). \ No newline at end of file