adam/Piwigo
1
0
Fork 0
mirror of https://github.com/Piwigo/Piwigo.git synced 2026-08-08 09:43:01 +02:00
Code Issues Packages Projects Releases Wiki Activity

copy from DokuWiki

Pierrick Le Gall
2023-04-29 17:27:57 +02:00
parent ea6d989c5f
commit 22f48e9304
1 changed files with 283 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Plugin-Tutorial:-Hello-world!.md
+283
@@ -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
<?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' :-).
``` 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__)).'/');
```
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)'.
``` php
// 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'.
``` 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;
}
?>
```
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
<?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](http://www.smarty.net/crash_course).)The entire layout is
is managed by the global variable '$template'.
``` php
// 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.)
``` 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');
?>
```
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
<!-- 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](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/).