add GPL header and many comments to phpfspot.js

Signed-off-by: Andreas Unterkircher <unki@netshadow.at>

1 files changed, 261 insertions, 35 deletions

diff --git a/phpfspot.js b/phpfspot.js
index f9f9703..b5f6e98 100644
--- a/phpfspot.js
+++ b/phpfspot.js
@@ -1,5 +1,35 @@
+/***************************************************************************
+ *
+ * Copyright (c) by Andreas Unterkircher, unki@netshadow.at
+ * All rights reserved
+ *
+ *  This program is free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation; either version 2 of the License, or
+ *  any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program; if not, write to the Free Software
+ *  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ *
+ ***************************************************************************/
+
+/**
+ * display image
+ *
+ * this function will be called by client and fetches
+ * the single-photo view via AJAX from the server.
+ * Furthermore it will scrollup the browser to the top
+ * position so the image become visibile immediatley.
+ */
 function showImage(id, scrollup)
 {
+   /* is phpfspot skeleton really displayed? */
    if(!document.getElementById('content'))
       return;
 
@@ -10,6 +40,7 @@ function showImage(id, scrollup)
       content.innerHTML = "";
    }
 
+   /* fetch single-photo view from server */
    HTML_AJAX.replace(content, encodeURI('rpc.php?action=showphoto&id=' + id));
 
    /* scroll the window up to the top */
@@ -21,8 +52,16 @@ function showImage(id, scrollup)
    delete(origHeight); origHeight = undefined;
    delete(origWidth); origWidth = undefined;
    delete(photo_details_pos); photo_details_pos = undefined;
-}
 
+} // showImage()
+
+/**
+ * scroll browser to the last shown photo
+ *
+ * this function will be called when user returns from single-photo
+ * to the photo index. It will scroll down the window (if possible)
+ * to the position of the last shown photo.
+ */
 function moveToThumb(thumb_id)
 {
    if(thumb_id == undefined)
@@ -34,6 +73,13 @@ function moveToThumb(thumb_id)
 
 } // moveToThumb()
 
+/**
+ * return position of object
+ *
+ * this function returns the position of an object.
+ * depending on the parameter 'direction' it will either
+ * return the X or Y position.
+ */
 function findPos(obj, direction) {
    var cur = 0;
    if (obj.offsetParent) {
@@ -45,14 +91,30 @@ function findPos(obj, direction) {
       } while (obj = obj.offsetParent);
    }
    return [cur];
-}
 
+} // findPos()
+
+/**
+ * opens the credits page
+ */
 function showCredits()
 {
    var credits = document.getElementById("content");
    credits.innerHTML = HTML_AJAX.grab(encodeURI('rpc.php?action=showcredits'));
-}
 
+} // showCredits()
+
+/**
+ * tag-selection handling
+ *
+ * this function is getting called by client to either
+ * - add
+ ∗ - delete
+ * - modify tag-match condition
+ *
+ * It will then fetch the result from the server via AJAX
+ * and updates the tag-selection.
+ */
 function Tags(mode, id)
 {
    var objTemp = new Object();
@@ -85,22 +147,44 @@ function Tags(mode, id)
 
 } // Tags()
 
+/**
+ * update available-tags tag-cloud
+ *
+ * this function queries an actual version of the tag-cloud
+ * for the available (not-selected) tags from the server via
+ * AJAX.
+ */
 function refreshAvailableTags()
 {
    // update available tags
    var avail_tags = document.getElementById('available_tags');
    avail_tags.innerHTML = "Loading...";
    avail_tags.innerHTML = HTML_AJAX.grab(encodeURI('rpc.php?action=show_available_tags'));
-}
 
+} // refreshAvailableTags()
+
+/**
+ * update selected-tags list
+ *
+ * this function queries an actual version of the tag-list
+ * for the selected tags from the server via AJAX.
+ */
 function refreshSelectedTags()
 {
    // update selected tags
    var selected_tags = document.getElementById("selected_tags");
    selected_tags.innerHTML = "Loading...";
    selected_tags.innerHTML = HTML_AJAX.grab(encodeURI('rpc.php?action=show_selected_tags'));
-}
 
+} // refreshSelectedTags()
+
+/**
+ * show photo index
+ *
+ * this function will fetch the photo-index view from
+ * the server via AJAX. It's also used to browse through
+ * the photo-index pages
+ */
 function showPhotoIndex(begin_with, last_photo)
 {
    var url = "rpc.php?action=show_photo_index";
@@ -113,26 +197,45 @@ function showPhotoIndex(begin_with, last_photo)
 
 } // showPhotoIndex()
 
-// if photo index is currently shown, refresh it
+/**
+ * update photo index
+ *
+ * this function will be called, to request a refresh of the
+ * photo index. this, for example, can be caused, when changing
+ * the tag-selection.
+ */
 function refreshPhotoIndex()
 {
+   /* only invoke showPhotoIndex(), if photo-index is really shown */
    if(document.getElementById("index") != undefined || startup == 1) {
       showPhotoIndex();
       startup = 0;
    }
-}
 
+} // refreshPhotoIndex()
+
+/**
+ * blur cursor focus
+ *
+ * this function removes the focus-rectangle which may appear
+ * when click on a link. Not always beautiful.
+ */
 function click(object)
 {
    if(object.blur)
       object.blur();
 
-}
-
-// set the radio button with the given value as being checked
-// do nothing if there are no radio buttons
-// if the given value does not exist, all the radio buttons
-// are reset to unchecked
+} // click()
+
+/**
+ * change current radio-button setting
+ *
+ * This function will check the radio-button with the given value.
+ * If no radio-button is currently displayed, this function will do
+ * nothing.
+ * If the given value does not exist, the existing radio buttons will
+ * be reseted.
+ */
 function setCheckedValue(condition, value) {
 
    var count = condition.length;
@@ -146,8 +249,15 @@ function setCheckedValue(condition, value) {
          condition[i].checked = true;
       }
    }
-}
 
+} // setCheckedValue()
+
+/**
+ * Invoke a search
+ *
+ * This function will be invoked by starting
+ * any kind of search (tag-name, photo-name, date, ...).
+ */
 function startSearch()
 {
    from_year = document.getElementById('fromyear').value;
@@ -185,6 +295,12 @@ function startSearch()
 
 } // startSearch()
 
+/**
+ * enable/disable date search
+ *
+ * this function will either enable or disable the
+ * input fields for the date-search
+ */
 function datesearch()
 {
    var mode = true;
@@ -200,15 +316,25 @@ function datesearch()
    document.getElementById('tomonth').disabled = mode;
    document.getElementById('today').disabled = mode;
  
-}
-
+} // datesearch()
+
+/**
+ * set view mode
+ *
+ * called for photo-index export. will return the
+ * selected mode via AJAX from the server.
+ */
 function setViewMode(mode)
 {
    var exprt = document.getElementById('output');
    exprt.innerHTML = "Loading...";
    exprt.innerHTML = HTML_AJAX.grab(encodeURI('rpc.php?action=get_export&mode=' + mode));
-}
 
+} // setViewMode()
+
+/**
+ * reset all search-fields
+ */
 function clearSearch()
 {
    document.getElementsByName('searchfor_tag')[0].value = '';
@@ -218,13 +344,26 @@ function clearSearch()
       document.getElementsByName('consider_date')[0].checked = false;
       datesearch();
    }  
-}
 
+} // clearSearch()
+
+/**
+ * if the client is planless, ask the server what to do
+ * next.
+ */
 function AskServerWhatToDo()
 {
    return HTML_AJAX.grab(encodeURI('rpc.php?action=what_to_do'));
-}
-
+} // AskServerWhatToDo()
+
+/**
+ * init phpfspot
+ *
+ * this function will be called when the browser opens phpfspot
+ * the first time. It will fetch the tag-lists and will then
+ * switch to the right view, which the browser got told from
+ * the server (maybe someone hit the refresh button...).
+ */
 function init_phpfspot(mode)
 {
    /* always load list of available tags */
@@ -246,8 +385,12 @@ function init_phpfspot(mode)
          refreshSelectedTags();
       }
    }
+
 } // init_phpfspot()
 
+/**
+ * change background-color on mouse-over
+ */
 function setBackGrdColor(item, color)
 {
    if(color == 'mouseover')
@@ -256,11 +399,19 @@ function setBackGrdColor(item, color)
       item.style.backgroundColor='#eeeeee';
    if(color == 'mouseclick')
       item.style.backgroundColor='#93A8CA';
-}
 
+} // setBackGrdColor()
+
+/**
+ * ask server, which photo needs to be shown
+ *
+ * when user press the refresh-button in a single-photo
+ * view or maybe enters the link via an external URL, the
+ * client does not know, what photo will be shown (dimensions...).
+ * But the server can tell this the browser.
+ */
 function getPhotoToShow()
 {
-   // update selected tags
    var photo_to_show = HTML_AJAX.grab(encodeURI('rpc.php?action=get_photo_to_show'));
 
    // if no image needs to be shown, return false from here
@@ -268,8 +419,15 @@ function getPhotoToShow()
       return false;
    
    return photo_to_show;
-}
 
+} // getPhotoToShow()
+
+/**
+ * a fake-zoom for photo
+ *
+ * a quick to let the browser do some zooming on
+ * photos.
+ */
 function zoom(mod)
 {
    var photo;
@@ -318,6 +476,12 @@ function zoom(mod)
 
 } // zoom()
 
+/**
+ * hides the photo details layin
+ *
+ * if the photo is getting zoomed quiet large, this will
+ * auto-hide (and also restore) the photo-details-box.
+ */
 function hidePhotoDetails(mode)
 {
    var photo_details;
@@ -334,6 +498,9 @@ function hidePhotoDetails(mode)
    }
 } // hidePhotoDetails()
 
+/**
+ * show calendar
+ */
 function showCalendar(date_box, click_obj)
 {
    var calendar = document.getElementById('calendar');
@@ -361,8 +528,12 @@ function showCalendar(date_box, click_obj)
    else {
       hideCalendar();
    }
-}
 
+} // showCalendar()
+
+/**
+ * hide calendar
+ */
 function hideCalendar()
 {
    var calendar = document.getElementById('calendar');
@@ -370,8 +541,11 @@ function hideCalendar()
       calendar.style.visibility = 'hidden';
       calendar_shown = 0;
    }
-}
+} // hideCalendar()
 
+/**
+ * switch month in calendar
+ */
 function setMonth(year, month, day)
 {
    var calendar = document.getElementById('calendar');
@@ -379,14 +553,22 @@ function setMonth(year, month, day)
    calendar.innerHTML = HTML_AJAX.grab(encodeURI('rpc.php?action=get_calendar_matrix&year='+ year +'&month='+ month +'&day='+ day));
 }
 
+/**
+ * get the user-selected date from the calendar and
+ * put it into the date-search boxes
+ */
 function setCalendarDate(year, month, day)
 {
    document.getElementById(calendar_mode+'year').value = year;
    document.getElementById(calendar_mode+'month').value = month;
    document.getElementById(calendar_mode+'day').value = day;
    hideCalendar();
-}
 
+} // setCalendarDate()
+
+/**
+ * reset phpfspot complelely and move to the begining
+ */
 function resetAll()
 {
    HTML_AJAX.grab(encodeURI('rpc.php?action=reset'));
@@ -394,8 +576,12 @@ function resetAll()
    refreshAvailableTags();
    refreshSelectedTags();
    refreshPhotoIndex();
-}
 
+} // resetAll()
+
+/**
+ * find objects with their class-name
+ */
 function WSR_getElementsByClassName(oElm, strTagName, oClassNames){
    var arrElements = (strTagName == "*" && oElm.all)? oElm.all : oElm.getElementsByTagName(strTagName);
    var arrReturnElements = new Array();
@@ -424,9 +610,12 @@ function WSR_getElementsByClassName(oElm, strTagName, oClassNames){
       }
    }
    return (arrReturnElements)
-}
 
+} // WSR_getElementsByClassName()
 
+/**
+ * javascript based photo preloading
+ */
 function preloadPhotos(image_url) {
 
    var i;
@@ -448,11 +637,15 @@ function preloadPhotos(image_url) {
          }
       }
    }
-}
+
+} // preloadPhotos()
 
 /* a function that does nothing */
 function noop() {}
 
+/**
+ * start slideshow
+ */
 function startSlideShow()
 {
    if(!sliding) {
@@ -466,20 +659,32 @@ function startSlideShow()
       sliding = 0;
       document.getElementById('stop_ico').src = "resources/32_play.png";
    }
-}
 
+} // startSlideShow()
+
+/**
+ * switch to next slide
+ */
 function nextSlide()
 {
    var next_img = HTML_AJAX.grab(encodeURI('rpc.php?action=get_next_slideshow_img'));
    document.getElementById('slide_img').src = next_img;
-}
 
+} // nextSlide()
+
+/**
+ * switch to previous slide
+ */
 function prevSlide()
 {
    var prev_img = HTML_AJAX.grab(encodeURI('rpc.php?action=get_prev_slideshow_img'));
    document.getElementById('slide_img').src = prev_img;
-}
 
+} // prevSlide()
+
+/**
+ * interrupt slide show
+ */
 function pauseSlideShow()
 {
    if(!sliding_paused) {
@@ -492,8 +697,12 @@ function pauseSlideShow()
       sliding = setInterval("nextSlide()", sliding_time*1000);
       document.getElementById('pause_ico').src = "resources/32_pause.png";
    }
-} 
 
+} // pauseSlideShow()
+
+/**
+ * start auto-browse
+ */
 function startAutoBrowse()
 {
    if(!autobrowse) {
@@ -508,6 +717,9 @@ function startAutoBrowse()
 
 } // startAutoBrowser()
 
+/**
+ * auto-browsing
+ */
 function autoBrowse()
 {
    if(document.getElementById('next_link')) {
@@ -524,6 +736,9 @@ function autoBrowse()
 
 } // autoBrowse()
 
+/**
+ * initiate slider to modify slide-switching-speed
+ */
 function initSlider()
 {
    var sliderEl = document.getElementById ? document.getElementById("slider-1") : null;
@@ -545,8 +760,12 @@ function initSlider()
       s.recalculate();
    };
 
-}
+} // initSlider()
 
+/**
+ * if the sort-order (photo-name, date, ...) has been
+ * changed, update the photo-index view.
+ */
 function update_sort_order(obj)
 {  
    var objTemp = new Object();
@@ -563,7 +782,9 @@ function update_sort_order(obj)
 
 } // update_sort_order()
 
-
+/**
+ * handle key events
+ */
 function keyDown(e) {
    var evt = (e) ? e:(window.event) ? window.event:null;
 
@@ -604,13 +825,18 @@ if(document.layers) {
    document.captureEvents(Event.KEYDOWN);
 }
 
+// will be reseted by first viewing photo-index
 var startup = 1;
+// calendar specific
 var calendar_shown = 0;
 var calendar_mode = '';
+// auto-browsing & sliding
 var autobrowse = 0;
 var sliding = 0;
 var sliding_paused = 0;
 var sliding_time = 3;
+// zooming
 var origHeight;
 var origWidth;
+// position of the last shown photo in photo-index
 var photo_details_pos;