Dokumentations- und Codestylearbeiten sowie Funktionserweiterung

* Die Funktion getGalleryLinks() in includes/galleryfunctions.php
   liefert die Menüeinträge und in index.php werden diese gerendert
   (fixes #16)
 * Der PHP-Code wurde so formatiert, dass phpcs --standard=Zend keine
   Fehler mehr findet (fixes #3)
 * Der PHP-Code wurde vollständig mit Doxygen dokumentiert und eine
   Doxygen-Konfiguration in doc/doxygen.conf hinterlegt (fixes #27)

ajaxrequest.php

@@ -1,6 +1,10 @@
 <?php
   /**
- * Diese Datei behandelt AJAX-Requests.
+   * @file
+   * Behandlung von AJAX-Requests.
+   *
+   * @author Jan Dittberner <jan@dittberner.info>
+   * @version \$Id$
    *
    * Copyright (c) 2007, 2008 Jan Dittberner <jan@dittberner.info>
    * Jan Dittberner IT-Consulting & -Solutions,
@@ -10,22 +14,24 @@
    * gnuviech-server.de Websitetools
    *
    * ScrollingJQueryGallery is free software: you can redistribute it
- * and/or modify it under the terms of the GNU General Public License as
+   * and/or modify it under the terms of the GNU General Public
- * published by the Free Software Foundation, either version 3 of the
+   * License as published by the Free Software Foundation, either
- * License, or (at your option) any later version.
+   * version 3 of the License, or (at your option) any later version.
    *
    * ScrollingJQueryGallery is distributed in the hope that it will be
- * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+   * useful, but WITHOUT ANY WARRANTY; without even the implied
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+   * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- * General Public License for more details.
+   * See the GNU General Public License for more details.
    *
    * You should have received a copy of the GNU General Public License
    * along with ScrollingJQueryGallery.  If not, see
    * <http://www.gnu.org/licenses/>.
- *
- * Version: $Id$
    */
-include("includes/galleryfunctions.php");
+
+  /**
+   * Inkludiert die Funktionsbibliothek.
+   */
+require 'includes/galleryfunctions.php';
 
 if (isset($_GET["imagename"]) && isset($_GET["galleryname"]) &&
     preg_match('/^[\w\d _-]+\.jp(e|)g$/', $_GET["imagename"]) &&

bilder/example/galleryinfo.ini

@@ -1,3 +1,6 @@
+[gallery]
+title = Beispielbilder
+
 [images]
 cimg3033_Small.jpg = Kerze
 cimg3071_Small.jpg = Gerät

includes/galleryfunctions.php

@@ -1,7 +1,10 @@
 <?php
 /**
- * Diese Datei stellt die verschiedenen Funktionen für den Aufbau der
+ * @file
- * Bildergallerie zur Verfügung.
+ * Funktionen für den Aufbau der Bildergalerie.
+ *
+ * @author Jan Dittberner <jan@dittberner.info>
+ * @version \$Id$
  *
  * Copyright (c) 2007, 2008 Jan Dittberner <jan@dittberner.info>
  * Jan Dittberner IT-Consulting & -Solutions,
@@ -23,8 +26,6 @@
  * You should have received a copy of the GNU General Public License
  * along with ScrollingJQueryGallery.  If not, see
  * <http://www.gnu.org/licenses/>.
- *
- * Version: $Id$
  */
 
 define(GALLERYPREFIX, "bilder");
@@ -33,14 +34,42 @@ define(IMAGESEC, "images");
 define(GALLERYSEC, "gallery");
 define(GALLERY_RE, '/^[\w\d _-]+$/');
 
+/**
+ * Breite der Vorschaubilder.
+ */
 $previewwidth = 311;
+
+/**
+ * Höhe der Thumbnailbilder.
+ */
 $thumbheight = 67;
 
+/**
+ * Prüft, ob eine Galerie mit dem übergebenen Namen existiert.
+ *
+ * @param $galleryname Galeriename
+ *
+ * @return @c true, wenn die Galerie existiert und einen erlaubten
+ * Verzeichnisnamen hat, sonst @c false
+ */
 function galleryExists($galleryname) {
   return preg_match(GALLERY_RE, $galleryname) &&
     realpath(GALLERYPREFIX . DIRECTORY_SEPARATOR . $galleryname);
 }
 
+/**
+ * Liefert geparste Konfigurationsinformationen zu einer Galerie oder
+ * die globale Konfiguration. Die Konfigurationsdaten einer Galerie
+ * stehen in der Datei @c galleryinfo.ini in dem Verzeichnis der
+ * Galerie. Die globale Konfiguration liegt in der gleichnamigen Datei
+ * im Elternverzeichnis der Galerien.
+ *
+ * @param $galleryname Galeriename oder @c null, wenn die globale
+ * Konfiguration geparst werden soll
+ *
+ * @return Ergebnis von @c parse_ini_file() oder ein leeres Array,
+ * wenn keine Konfigurationsdatei vorhanden ist
+ */
 function getGalleryConfig($galleryname = null) {
   if ($galleryname) {
     $filepath = realpath(GALLERYPREFIX . DIRECTORY_SEPARATOR .
@@ -55,11 +84,19 @@ function getGalleryConfig($galleryname = null) {
 }
 
 /**
- * Holt die Bildinformationen zu einem Bild aus der Datei
+ * Holt die Bildinformationen zu einem Bild.
- * bilder/imginfo.txt und gibt diese zurueck.
  *
  * @param $imagename Bildname
+ *
  * @param $galleryname Galleriename
+ *
+ * @return assoziatives Array mit folgenden Feldern
+ * @li @a name Bildname
+ * @li @a data Label des Bildes
+ * @li @a preview relative URL des Vorschaubildes
+ * @li @a full relative URL des Vollbildes
+ *
+ * @bug @a data sollte @a label heißen
  */
 function getImgInfo($galleryname, $imagename) {
   return array("name" => $imagename,
@@ -72,6 +109,18 @@ function getImgInfo($galleryname, $imagename) {
                );
 }
 
+/**
+ * Liefert das Label zu einem Bild. Wenn es in der @a images-Sektion
+ * der Datei @c galleryinfo.ini der angegebenen Galerie einen Eintrag
+ * mit dem übergebenen Bildnamen gibt, wird dieser zurückgegeben,
+ * ansonsten der Bildname selbst.
+ *
+ * @param $galleryname Galeriename
+ *
+ * @param $imagename Bildname
+ *
+ * @return Label zu dem Bild
+ */
 function getImageLabel($galleryname, $imagename) {
   $gallerypath = realpath(GALLERYPREFIX . DIRECTORY_SEPARATOR . $galleryname);
   if (empty($gallerypath) || !is_dir($gallerypath)) {
@@ -91,9 +140,11 @@ function getImageLabel($galleryname, $imagename) {
 
 /**
  * Liefert die aktuelle Gallerie. Die Gallerie kann entweder im
- * GET-Parameter "galleryname" stehen, in der "gallery"-Sektion der
+ * GET-Parameter @c galleryname stehen, als Wert @a default in der @a
- * zentralen galleryinfo.ini angegeben werden oder es wird das erste
+ * gallery-Sektion der zentralen galleryinfo.ini angegeben werden oder
- * Unterverzeichnis von GALLERYPREFIX verwendet.
+ * es wird das erste Unterverzeichnis von GALLERYPREFIX verwendet.
+ *
+ * @return Galeriename
  */
 function getCurrentGallery() {
   if (galleryExists($_GET["galleryname"])) {
@@ -116,6 +167,23 @@ function getCurrentGallery() {
   return null;
 }
 
+/**
+ * Liefert eine skalierte Version zu dem übergebenen Bild der
+ * übergebenen Galerie und generiert dieses bei Bedarf.
+ *
+ * @param $galleryname Galeriename
+ *
+ * @param $basename Bildname
+ *
+ * @param $maxdim maximale Breite oder Höhe des skalierten Bildes in
+ * Pixeln
+ *
+ * @param $scaleheight Angabe ob die Höhe oder die Breite für den
+ * Maximalwert beachtet werden soll, wenn dieser Parameter @c true
+ * ist, wird die Höhe auf @a $maxdim skaliert, ansonsten die Breite
+ *
+ * @return Pfad des skalierten Bildes relativ zu @a GALLERYPREFIX
+ */
 function getScaledImage($galleryname, $basename, $maxdim, $scaleheight=true) {
   if ($maxdim == 0) {
     debug_print_backtrace();
@@ -164,10 +232,13 @@ function getScaledImage($galleryname, $basename, $maxdim, $scaleheight=true) {
 /**
  * Gibt die Informationen über Vorschaubilder zurück.
  *
- * @return array das erste Element ist die aufsummierte Breite der
+ * @param $galleryname Galeriename
- * Einzelbilder und das zweite Element ist ein assoziatives Array mit
+ *
- * den Bildnamen als Keys und dem Ergebnis von getimagesize() als
+ * @return Array mit drei Elementen, dessen erstes Element die
- * Werten
+ * aufsummierte Breite der Einzelbilder, dessen zweites Element der
+ * Galeriename und dessen drittes Element ein assoziatives Array mit
+ * den Bildnamen als Keys und Arrays mit dem Pfadnamen das Thumbnails
+ * und dem Ergebnis von getimagesize() als Werten ist.
  */
 function getThumbNailInfo($galleryname) {
   $thumbsizes = array();
@@ -188,9 +259,50 @@ function getThumbNailInfo($galleryname) {
   return array($thumbwidthsum, $galleryname, $thumbsizes);
 }
 
+/**
+ * Gibt die Links zu den existierenden Galerien zurück.
+ *
+ * @return Array, welches je Gallerie ein assoziatives Array mit den
+ * Keys @a gallery, @a label und @a url enthält. Die Labels für die
+ * Galerien werden aus dem @a title-Feld der @a gallery-Sektion der @c
+ * galleryinfo.ini ausgelesen. Wenn diese Feld nicht gesetzt ist, wird
+ * der Galeriename verwendet.
+ *
+ * @see galleryExists()
+ * @see getGalleryConfig()
+ */
 function getGalleryLinks() {
+  $retval = array();
+  foreach (glob(realpath(GALLERYPREFIX) . DIRECTORY_SEPARATOR . '*',
+                GLOB_ONLYDIR) as $directory) {
+    $basename = basename($directory);
+    if (galleryExists($basename)) {
+      $inidata = getGalleryConfig($basename);
+      if ($inidata[GALLERYSEC]['title']) {
+        $label = $inidata[GALLERYSEC]['title'];
+      } else {
+        $label = $basename;
+      }
+      $url = sprintf('index.php?galleryname=%s', urlencode($basename));
+    }
+    $retval[] = array('gallery' => $basename,
+                      'label' => $label,
+                      'url' => $url);
+  }
+  return $retval;
 }
 
+/**
+ * Gibt die Thumbnail-Bilder die in @a $thumbinfo definiert sind aus.
+ *
+ * @param &$thumbinfo Referenz auf ein Array, wie es von
+ * getThumbNailInfo() zurückgegeben wird
+ *
+ * @bug die HTML-Ausgabe sollte in die Ausgabeseite verschoben werden
+ * und diese Funktion nur noch die Daten entsprechend aufbereiten
+ *
+ * @see getThumbNailInfo()
+ */
 function showThumbnails(&$thumbinfo) {
   foreach ($thumbinfo[2] as $basename => $data) {
     printf("<div class=\"thumbnail\"><img src=\"%s\" alt=\"\" \"%s\" /></div>",
@@ -199,6 +311,17 @@ function showThumbnails(&$thumbinfo) {
   }
 }
 
+/**
+ * Gibt das erste Vorschaubild aus @a $thumbinfo aus.
+ *
+ * @param &$thumbinfo Referenz auf ein Array, wie es von
+ * getThumbNailInfo() zurückgegeben wird
+ *
+ * @bug die HTML-Ausgabe sollte in die Ausgabeseite verschoben werden
+ * und diese Funktion nur noch die Daten entsprechend aufbereiten
+ *
+ * @see getThumbNailInfo()
+ */
 function showPreview(&$thumbinfo) {
   foreach ($thumbinfo[2] as $basename => $data) {
     $galleryname = $thumbinfo[1];
@@ -210,13 +333,25 @@ function showPreview(&$thumbinfo) {
                                              DIRECTORY_SEPARATOR .
                                              $scaledimage));
     $label = getImageLabel($galleryname, $basename);
-    printf("<a  class=\"lightbox\" title=\"%s\" href=\"%s\" rel=\"lightbox\"><img id=\"contentimg\" src=\"%s%s%s\" alt=\"%s\" %s /></a>",
+    printf('<a  class="lightbox" title="%s" href="%s" rel="lightbox">' .
+           '<img id="contentimg" src="%s%s%s" alt="%s" %s /></a>',
            $label, $fullname, GALLERYPREFIX, DIRECTORY_SEPARATOR,
            $scaledimage, $label, $scaledimagesize[3]);
     break;
   }
 }
 
+/**
+ * Gibt die Beschreibung des ersten Bildes aus @a $thumbinfo aus.
+ *
+ * @param &$thumbinfo Referenz auf ein Array, wie es von
+ * getThumbNailInfo() zurückgegeben wird
+ *
+ * @bug die HTML-Ausgabe sollte in die Ausgabeseite verschoben werden
+ * und diese Funktion nur noch die Daten entsprechend aufbereiten
+ *
+ * @see getThumbNailInfo()
+ */
 function renderDescription(&$thumbinfo) {
   foreach ($thumbinfo[2] as $basename => $data) {
     print htmlentities(getImageLabel($thumbinfo[1], $basename));

index.php

@@ -1,53 +1,55 @@
 <?php
-/*
+  /**
- * Copyright (c) 2008 Jan Dittberner <jan@dittberner.info>
+   * @file
+   * Startseite für ScrollingJQueryGallery. Diese Datei erledigt die
+   * Ausgabe im Browser.
+   *
+   * @author Jan Dittberner <jan@dittberner.info>, Jeremias Arnstadt
+   * <douth024@googlemail.com>
+   * @version \$Id$
+   *
+   * Copyright (c) 2008 Jan Dittberner
    * Jan Dittberner IT-Consulting & -Solutions
    * Cottbuser Str. 1, D-01129 Dresden
    *
- * Copyright (c) 2008 Jeremias Arnstadt <douth024@googlemail.com>
+   * Copyright (c) 2008 Jeremias Arnstadt
    *
    * This file is part of the ScrollingJQueryGallery component of the
    * gnuviech-server.de Websitetools
    *
    * ScrollingJQueryGallery is free software: you can redistribute it
- * and/or modify it under the terms of the GNU General Public License as
+   * and/or modify it under the terms of the GNU General Public
- * published by the Free Software Foundation, either version 3 of the
+   * License as published by the Free Software Foundation, either
- * License, or (at your option) any later version.
+   * version 3 of the License, or (at your option) any later version.
    *
    * ScrollingJQueryGallery is distributed in the hope that it will be
- * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+   * useful, but WITHOUT ANY WARRANTY; without even the implied
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+   * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- * General Public License for more details.
+   * See the GNU General Public License for more details.
    *
    * You should have received a copy of the GNU General Public License
    * along with ScrollingJQueryGallery.  If not, see
    * <http://www.gnu.org/licenses/>.
- *
- * Version: $Id$
    */
 
-// Name des Menüpunktes
+  /**
-$menupunkt = "Beispielbilder 1";
+   * Inkludiert die Funktionsbibliothek.
-
+   */
-// greift auf die Funktionen der ausgelagerten Datei um die Thumbnails
+require 'includes/galleryfunctions.php';
-// einzulesen
-include ("includes/galleryfunctions.php");
 
+/**
+ * Name der aktuellen Galerie.
+ */
 $gallery   = getCurrentGallery();
+
+/**
+ * Informationen zu den Thumbnail-Bildern der aktuellen Galerie.
+ */
 $thumbinfo = getThumbNailInfo($gallery);
 
-// bezieht sich auf die Hauptmenükategorie (für Anzeige von aktivem
-// Link notwendig)
-$kategorie = ($bilder_kat = 1);
-
-// bezieht sich auf die Submenükategorie (für Anzeige von aktivem Link
-// notwendig)
-$nav_auswahl = ($bilder_kat_sub = 1);
-
-// bezieht sich auf das Auswahlmenü
-$aquarelle = ($menu = 14);
 ?>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN http://www.w3.org/TR/html4/loose.dtd">
+<!DOCTYPE HTML PUBLIC
+ "-//W3C//DTD HTML 4.01 Transitional//EN http://www.w3.org/TR/html4/loose.dtd">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
 <title>Bilderframework</title>
@@ -83,15 +85,23 @@ a:active {
 <!-- container -->
 <div id="container">
   <div id="content">
-   <div id="menu"><? getGalleryLinks(); ?></div>
+   <div id="menu"><?php
+ foreach (getGalleryLinks() as $data) {
+   if ($data['gallery'] == $gallery) {
+     $active = ' class="active"';
+   }
+   printf('<a href="%s"%s>%s</a>', $data['url'], $active, $data['label']);
+ } ?></div>
    <div id="content_container">
      <div id="slider">
-       <div id="arrleft"><img src="css/grafiken/aro-lft.png" alt="nach links" width="10" height="65" /></div>
+       <div id="arrleft"><img src="css/grafiken/aro-lft.png" alt="nach links"
+        width="10" height="65" /></div>
        <div id="imgscroller"><div id="scrollable"><?php
          // zeigt die eingelesenen Thumnails an
          showThumbNails($thumbinfo);
        ?></div></div>
-       <div id="arrright"><img src="css/grafiken/aro-rt.png" alt="nach rechts" width="10" height="65" /></div>
+       <div id="arrright"><img src="css/grafiken/aro-rt.png" alt="nach rechts"
+        width="10" height="65" /></div>
      </div>
    </div>
    <div id="content_sub">
@@ -102,7 +112,10 @@ a:active {
         ?></div>
       </div>
       <div id="content_nav">
-        <img id="backbtn" src="css/grafiken/back.jpg" alt="back" class="back" width="10" height="10" top="0"><img id="fwdbtn" src="css/grafiken/next.jpg" alt="next" class="next" width="10" height="10" top="0">
+        <img id="backbtn" src="css/grafiken/back.jpg" alt="back" class="back"
+         width="10" height="10" top="0"><img id="fwdbtn"
+         src="css/grafiken/next.jpg" alt="next" class="next" width="10"
+         height="10" top="0">
       </div>
       <div class="imgdescription" id="imagedescription"><?php
         // liest die Bildbeschreibung für das jeweilige Bild (wenn definiert)