In this tutorial you will learn more about the basics of plugin development for Piwigo. This tutorial is a follow up on Tutorial: Hello World!. The entire plugin can be installed from the extension gallery under the name 'Copyrights'. Note that this tutorial follows the v1.0 revision of this plugin.

First of all, download the source code of the Skeleton plugin. We will use that as basis for this plugin.

With this plugin we want to achieve the following:

1. Somewhere we want to manage our copyrights.
2. Somehow copyrights must be added to photos.
3. Somehow the copyright must be displayed when visitors view a photo.

Therefore, we will write code for:

1. An administration panel, where the admin can create and edit plugins
2. An extension to the Batch manager (using events) so that copyrights can be added to photos.
3. Another event-hook that will display the copyright when a photo is viewed.

For the admin panel we need to do two things. First add a link to the plugins menu, second create an admin page.

To add a link to the menu of plugins we put the following code in main.inc.php

// In main.inc.php

/* +-----------------------------------------------------------------------+
 * | Plugin admin                                                          |
 * +-----------------------------------------------------------------------+ */

// Add an entry to the plugins menu
add_event_handler('get_admin_plugin_menu_links', 'copyrights_admin_menu');
function copyrights_admin_menu($menu) {
  array_push(
    $menu,
    array(
      'NAME'  => 'Copyrights',
      'URL'   => get_admin_plugin_menu_link(dirname(__FILE__)).'/admin.php'
    )
  );
  return $menu;
}

This add an event handler to the event 'get_admin_plugin_menu_links'. The added handler is the function 'copyrights_admin_menu' that we define right below it. It consists of a simple array_push() to add our link to the plugins menu.

Lets move on to the content of admin.php, since that is what we are linking to.

We would like to do several things on the admin page. First of all, we want to be able to create plugins. Next we should be able to view them, and lastly, we want to be able to edit existing copyrights.

Firstly, however, we load the language file and perform a security check.

load_language('plugin.lang', COPYRIGHTS_PATH);

// Check access and exit when user status is not ok
check_status(ACCESS_ADMINISTRATOR);

Next we set some default values for several variables. All the variables beginning with '$CR' will be overwritten in case of an edit.

// Default is to create a copyright, if changed to 1, show the edit page
$edit = 0;

// The values for the form fields
$CRid = 0;
$CRname = '';
$CRurl = '';
$CRdescr = '';
$CRvisible = 0;

We make use of the special variable '$tab' which Piwigo uses.

// Do managing of copyrights
if (isset($_GET['tab'])) {
  // Create a new copyright
  if ($_GET['tab'] == 'create') {
    // Fetch the values from the form
    $name = pwg_db_real_escape_string($_REQUEST['name']);
    $url = pwg_db_real_escape_string($_REQUEST['url']);
    $descr = pwg_db_real_escape_string($_REQUEST['descr']);
    $visible = (isset($_REQUEST['visible']) ? 1 : 0);

    // Check whether a copyright with such a name exists
    // Therefore count the number of copyrights with that name
    $query = sprintf(
      'SELECT COUNT(*)
      FROM %s
      WHERE `name` = \'%s\'
      ;',
      COPYRIGHTS_ADMIN, $name);
    list($counter) = pwg_db_fetch_row(pwg_query($query));

    if ($counter != 0) { // The copyright exists already
      array_push($page['errors'], l10n('This copyright already exists.'));
    } else { // The copyright did not yet exist
      // Compose a query to insert the copyright
      $query = sprintf(
        'INSERT INTO %s
        (`name`,`url`,`descr`,`visible`) VALUES
        ("%s","%s","%s",%d)
        ;',
        COPYRIGHTS_ADMIN, $name, $url, $descr, $visible);
      pwg_query($query); // Execute the query
    }
  }

Next we put here all the code for editing, updating and deleting copyrights.

  // Edit an existing copyright
  if ($_GET['tab'] == 'edit') {
    $edit = 1; // Show the edit page
    $CRid = $_REQUEST['id']; // Fetch the id of the copyright to be edited

    // Fetch the current attributes to the copyright
    $query = sprintf(
      'SELECT *
      FROM %s
      WHERE `cr_id`=%d
      ;',
      COPYRIGHTS_ADMIN, $CRid);
    $result = pwg_query($query);
    $row = pwg_db_fetch_assoc($result);

    // Save the attributes in convenient variables
    $CRname = $row['name'];
    $CRurl = $row['url'];
    $CRdescr = $row['descr'];
    $CRvisible = $row['visible'];
  }

  // Update an existing copyright
  if ($_GET['tab'] == 'update') {
    // Fetch the values from the edit form
    $id = pwg_db_real_escape_string($_REQUEST['id']);
    $name = pwg_db_real_escape_string($_REQUEST['name']);
    $url = pwg_db_real_escape_string($_REQUEST['url']);
    $descr= pwg_db_real_escape_string($_REQUEST['descr']);
    $visible = (isset($_REQUEST['visible']) ? 1 : 0);

    // Compose a query to update the copyright
    $query = sprintf(
      'UPDATE %s
      SET `name`="%s", `url`="%s", `descr`="%s", `visible`=%d
      WHERE `cr_id`=%d
      ;',
      COPYRIGHTS_ADMIN, $name, $url, $descr, $visible, $id);
    pwg_query($query); // Execute the query
  }

  // Delete an existing copyright
  if ($_GET['tab'] == 'delete') {
    $id = $_REQUEST['id']; // Fetch the id of the copyright to be deleted

    // Compose a query to delete the copyright
    $query = sprintf(
      'DELETE FROM %s
      WHERE `cr_id`=%d
      ;',
      COPYRIGHTS_ADMIN, $id);
    pwg_query($query); // Execute the query
  }
}

For the viewing of copyrights we use the following Smarty code.

The Batch manager comes with two modes, so we will have to write extensions to both.