Please visit the Support Forums for online support, installation instructions, file formats, tips and more.

NAME

album.pl - A dynamically generated web based photo album.

SYNOPSIS

There are many ways to invoke album.pl:

Normal: http://perl.Bobbitt.ca/cgi-bin/album.pl

Go to a specific album: http://perl.Bobbitt.ca/cgi-bin/album.pl?album=albumname

Go to a specific photo: http://perl.Bobbitt.ca/cgi-bin/album.pl?photo=photoname

Go to the Configuration Management screen: http://perl.Bobbitt.ca/cgi-bin/album.pl?function=config

Update titles and descriptions: http://perl.Bobbitt.ca/cgi-bin/album.pl?function=enter_desc

Upload photos or movies: http://perl.Bobbitt.ca/cgi-bin/album.pl?function=upload

Add the Administration Menu: http://perl.Bobbitt.ca/cgi-bin/album.pl?function=admin

View photos as part of a slideshow (5 second delay): http://perl.Bobbitt.ca/cgi-bin/album.pl?slideshow=5

View photos as a full screen slideshow: http://perl.Bobbitt.ca/cgi-bin/album.pl?slideshow=5;fullscreen=1

Turn on debugging (highest level): http://perl.Bobbitt.ca/cgi-bin/album.pl?debug=4

Generate static HTML files for each album and photo: http://perl.Bobbitt.ca/cgi-bin/album.pl?static=1

View recent uploads: http://perl.Bobbitt.ca/cgi-bin/album.pl?album=:recent

View the last 10 recent uploads, formatted for inclusion in other pages: http://perl.Bobbitt.ca/cgi-bin/album.pl?album=:recent;ssi=10

View a randomly selected photo from the album: http://perl.Bobbitt.ca/cgi-bin/album.pl?random=1

View the thumbnail of a randomly selected photo, formatted for inclusion in other pages: http://perl.Bobbitt.ca/cgi-bin/album.pl?random=1;ssi=1

View the thumbnails of randomly selected photos in a slideshow (5 second delay), formatted for inclusion in other pages: http://perl.Bobbitt.ca/cgi-bin/album.pl?random=1;ssi=1;slideshow=5

View a specific photo, formatted for inclusion in other pages: http://perl.Bobbitt.ca/cgi-bin/album.pl?photo=photoname;ssi=1

View photos in a slideshow (5 second delay), formatted for inclusion in other pages: http://perl.Bobbitt.ca/cgi-bin/album.pl?photo=photoname;slideshow=5;ssi=1

View most popular photos: http://perl.Bobbitt.ca/cgi-bin/album.pl?popular=1

View most popular albums: http://perl.Bobbitt.ca/cgi-bin/album.pl?popular=2

View 10 most popular photos, formatted for inclusion in other pages: http://perl.Bobbitt.ca/cgi-bin/album.pl?popular=1;ssi=10

View 10 most popular albums, formatted for inclusion in other pages: http://perl.Bobbitt.ca/cgi-bin/album.pl?popular=2;ssi=10

Use an alternate configuration file: http://perl.Bobbitt.ca/cgi-bin/album.pl?configfile=/home/user/www/album.cfg

Give them a try, some are undocumented features! :)

DESCRIPTION

album.pl is a simple web based program that allows you to simply drop new photo files into a directory, and they will automatically be accessible via the web. It does this by building the photo album on the fly. album.pl uses a simple administration menu to allow you to move or delete photos and albums, as well as adding titles and long descriptions.

Users may upload photos directly into your album, if you permit it.

It can also be used to create static HTML files for certain situations. (This mode is not updated automatically, but is useful for creating a photo CD or viewing pictures without a web server.

To get a feel for all the features and functions, you should see CHANGES.txt.

INFORMATION

Author: Mike Bobbitt (Mike@Bobbitt.ca), Cipher Logic Canada Inc.

For updates, instructions and examples see http://perl.Bobbitt.ca/album on the web.

SUPPORT

There is a support forum set up for discussion of album.pl matters. I would recommend that anyone with a support question try searching the forums first. Your question may have already been answered! Otherwise, try posting your question to the forums, where you have the best chance of having it answered. That way, if I am unable to respond right away, it's entirely likely that a peer user will be able to help out. The forums are located at:

http://perl.Bobbitt.ca/yabbse

Once registered with the forums, user are also invited to use the test album, located at http://perl.Bobbitt.ca/cgi-bin/album.pl to ``test drive'' the software. Support questions sent to me by e-mail tend to get a slower response.

Please also note that this is a personal project. I work on it in my spare time, on weekends and evenings, so I'm not always able to respond questions or comments in a timely manner.

FAQ

For an up to date list of Frequently Asked Questions and common problems, please see the FAQ section of the support forums:

http://perl.Bobbitt.ca/yabbse/index.php?board=3

TO DO

There are still bugs in this code, so please bear with me, and report any that you find. The complete list of all the things I still want to do with album.pl is located here:

http://perl.bobbitt.ca/yabbse/index.php?board=5;action=display;threadid=352

Any place in the code that I've started (but not finished) a feature, I tried to mark it with a ***.

LICENSE

This program is © 1999-2003 Cipher Logic Canada Inc. All Rights Reserved.

As long as you leave this POD section and my contact info above in tact, feel free to use this as you see fit. You can pretty much do anything with this script except resell it. :)

If you come up with any good modifications to it, please let me know. I'd love to fold your mod into the public version (with credit, of course).

Good luck!

APOLOGIES

Here goes:

SUBROUTINES

photoAlbum()

 photoAlbum($manual_override);
 $manual_override - Start in this album or with this photo (optional)

Does the majority of the processing for the photo album

error()

 error($line,$error_code,$extra_info);
 $line - Line number, where error occurred.
 $error_code - Pre-defined error code that prints a canned message.
 $extra_info - Additional information that can be passed in

Displayes the error message associated with $error_code along with the $extra_info. Then halts execution.

display()

 display($display_message);
 $display_message - String to print (to STDOUT or to static file)

Prints a message to the designated output steam

debug()

 debug($debug_message,$debug_level,$line);
 $debug_message - String to print if debugging is on
 $debug_level - Only pring string if current debug level is $debug_level or higher (current debug level is set by $debug)
 $line - The line number of the debug statement.

Prints a message, if $::debug has a value.

setDate()

 $datestr=setDate($convtime,$return_seconds);
 $datestr        - date and time
 $convtime       - unixtime value which is used to set $datestr (optional)
 $return_seconds - 1=YYYY/MM/DD HH:MM:SS, 0=YYYY/MM/DD HH:MM

Converts $convtime into a human readable format and returns it as $datestring. If $convtime is not provided, the current time is returned. If $return_seconds has a value, then the time includes seconds.

sanityTest()

 sanityTest();

Runs some basic tests to make sure the environment is clean and secure before the script starts.

readDirectory()

 @myfile_list=readDirectory($scan_directory);
 @myfile_list - Returned list of files in this directory
 $scan_directory - Directory to read all values from

Reads all entries in specified directory, returns as list

recursiveScan()

 recursiveScan($scan_directory,$already_scanned);
 $scan_directory - Directory to search recursively
 $already_scanned - Path of directories above this one (optional)

Walks the directory tree recursively

isAPhoto()

 isAPhoto($photo_name);
 $photo_name - name of picture file

Returns 1 if the filename passed in is that of a valid ``photo'', 0 otherwise.

isAMovie()

 isAMovie($movie_name);
 $movie_name - name of movie file

Returns 1 if the filename passed in is that of a valid ``movie'', 0 otherwise.

Authenticate()

 $authenticated=Authenticate($mode);
 $authenticated - Returns 1 if the user was successfully authenticated, otherwise zero.
 $mode - Alternate authentication mode. For UBB, this means Junior Members are not permitted, and will always return zero. (Used to prohibit junior members from uploading).

Authenticates the global variables $::username and $::password, using the specified method. Returns 1 for a successful authentication, otherwise 0.

checkPassword()

 $goodpass=checkPassword($mypassword,$storedpass);
 $goodpass - The password that matched, if found. (Otherwise, the stored password ($storedpass) is returned).
 $mypassword - The password that the user has entered.
 $storedpass - The password on file for that user.

Checks $mypassword against $storedpass using all known encryption methods, and returns a copy of the ``good'' (clear) password, if found

loginStatus()

 $login_html=loginStatus();
 $login_html = The user's login status, as HTML.

Returns the user's login status as either a URL to the login page (if the user is not logged in) or as as ``Welcome [username]'' message (if the user is logged in).

cookieLogin()

 $status=cookieLogin();
 $status - 1 if login info was found, otherwise 0

Retrieves login information from the cookie (if found) and passes it back as $::username, $::password, $::usernumber (UBB) and $::displayname.

showLogin()

 showLogin();

Returns the login form as HTML, to be inserted into a template.

showAdminMenu()

 $admin_menu=showAdminMenu($style);
 $style - 0 = Long menu (titles, all options - used at the top of photo/album pages); 1 = Short menu (no title, some options - used under thumbnails)
 $admin_menu - Variable to return completed Administration menu into.

Returns the Administration menu, so it can be substituted into the template.

openDescfile()

 openDescfile($descfilename);
 $descfilename - The full, filesystem path to the album you want to read descriptions from.

Opens up $descfilename so that photo/album titles/descriptions can be loaded.

getDescription()

 getDescription($desctoget,$mode);
 $desctoget - Photo or album to get description of
 $mode - 0 = Normal; 1 = Searching

Retrieves the title, description and owner of the provided object. Puts the title in $::shortdesc, the description in $::longdesc (if present) and the owner in $::owner (if present).

buildDescFooter()

 $add_desc_footer=buildDescFooter($status);
 $add_desc_footer - The HTML code for adding a description, which is returned.
 $status - 0 if building the whole form, 1 if building it as part of another form (like the create album form, for example).

Creates $directory in $basedir, and updates the description with $::shortdesc and $::longdesc.

updateDesc()

 updateDesc($myobject,$desc_file_loc,$title,$description,$myowner);
 $myobject - The object whose description is being updated
 $desc_file_loc - The location of the descfile to update
 $title - The new title to apply to the object
 $description - The new long description to apply to the object
 $myowner - The new owner of the object

Updates the $::descfile located in $desc_file_loc for the item $myobject, with the information passed in through the web form.

deleteDesc()

 deleteDesc($myobject,$desc_file_loc);
 $myobject - The object whose description is being deleted
 $desc_file_loc - The location of the descfile to modify

Deletes the entry for $myobject from the $::descfile located in $desc_file_loc.

uploadPhoto()

 uploadPhoto();

Called when a user wants to upload a photo. Shows the form and handles the file transfer.

showUploadForm()

 $upload_form=showUploadForm();
 $upload_form - Variable to return completed upload form into.

Returns the upload form, so it can be substituted into the template.

fileUpload()

 fileUpload($count);
 $count - The file number to process (must be between 1 and $::concurrent_uploads).

Handles the nitty gritty file upload stuff. Called once for each file to upload.

showFooter()

 $footer=showFooter($show);
 $show - If set to 0, the footer simply returned, if set to 1, it is displayed and returned.

Rerturns or displays the HTML footer for all pages.

buildTemplate()

 $template=buildTemplate();
 $template = variable to pass the template back into

Builds the object template, and returns it.

buildNavFooter()

 $nav_footer=buildNavFooter();

Builds the navigaction footer, and returns it. (The navigation footer is the buttons/links that allow you to visit the next/previous photo or album.)

passVars()

 $vars=passVars($format);
 $vars = variable to pass the formed variables back into
 $format = 0: pass in web URL format (&debug=1&configfile=file, etc); 1: pass in button format (<input type="hidden"...); 2: same as zero, but no function code

Sees which variables must be passed (configfile, debug, static, etc), builds the string containing the data, and passes the value back.

printHeader()

 $header=printHeader($mode);
 $header - The formed header, with style sheet or body colour tags, is returned.
 $mode - 0 = Return all header HTML; 1 = Return just style sheet tag

Prints out either the style sheet or a generic body tag.

trackView()

 $current_views=trackView($currentphoto);
 $current_views - Returns a string containing the number of views and the last viewed date.
 $currentphoto - Photo to update views for.
 $mode - 0 = Update views; 1 = Don't update views

Updates the number of views and the last viewed date for the current photo in $::viewfile.

substituteData()

 $output_data=substituteData($input_data);
 $input_data - Data that is passed in. Each of the "####TAGS####" tags are replaced with actual data. See the file format section of this document for details on the tags.
 $output_data - After substitutions, the data that is returned.

Replaces all the tags in the data passed in, and returns the updated string.

buildObject()

 $output_data=buildObject();
 $output_data - The HTML for displaying the object is build and returned.

Builds the ``object'' to be displayed. For a photo, it builds the HTML to display the photo, and for an album, it builts the list of objects in that album (photos and sub-albums).

sortObjects()

 @sorted=sortObjects($mode);
 @sorted - The @::file_list, sorted according to the configuration
 $mode - 0 = Sorting for album view; 1 = Sorting for navigation bar (cuts off photo filename)

Sorts @::file_list, according to configuration settings, and returns the sorted array.

buildAlbum()

 $return_html=buildAlbum($mode);
 $return_html - The built HTML for the current object
 $mode - 1 = Display this group on every page (albums); 0 = Display as per usual (photos and movies)

Builds the HTML for a photo, album or movie, as it appears in it's album (called when building an album page, for each ``thimbnail'' object on that page).

parseLinks()

 $template=parseLinks($template);
 $template - Data is passed in, made web safe, and passed out.

Checks the data passed and converts special characters within any links into web safe characters.

showThumb()

 $thumbnail_html=showThumb($myobject,$mode);
 $myobject - Path/filename to object to search for thumbnail of, relative to album_dir.
 $thumbnail_html - HTML for the thumbnail.
 $mode - 1 = special case for album thumbnails (built during nav_footer)

Returns the proper HTML for the thumbnail of the passed object, honouring all configfile settings. If configured to do so, will also call genThumb for photos that do not already have a thumbnail.

readConfig()

 readConfig($confile,$mode);
 $confile - path and filename of the config file
 $mode - 0 = Reading primary config; 1 = Reading local config (per album config)

Reads configuration information from the specified config file.

showConfig()

 showConfig();

Displays the configuration items from $::configfile in a web submittable form, then exits.

updateConfig()

 updateConfig();

Updates the settings in $configfile, when the form displayed in showConfig is submitted.

updateRating()

 updateRating($myobject,$rating_file_loc,$rating,$comments);
 $myobject - Object to add a rating to
 $rating_file_loc - Location of the ratings file
 $rating - The numerical rating
 $comments - Comments (optional)

Updates the ratings for the object supplied, using the rating and comments supplied.

getRatings()

 $ratings=getRatings($mode,$rating_file_loc);
 $ratings - The string of rating information to insert into the template.
 $mode - 0 = Add a link to submit a rating to the returned data; 1 = Do not return the link to add a rating; 2 = Perform search; 3 = Show rating only, not comments; 4 = It's a popularity contest! Populate @poplist with info on photo ratings.
 $rating_file_loc - Location of ratings file (optional, only used if mode=1).

Returns the ratings information for the current photo/movie.

webifyLinks()

 $output=webifyLinks($input);
 $input - The string to webify (make web safe).
 $output - Web safe version returned.

Returns the ``websafe'' version of the passed filename/path.

regConnect()

 $response=regConnect($email,$url);
 $response - The response from the registration server
 $email - E-mail to register (product update notices ONLY will be sent to this address - and maybe not even those!)
 $url - URL of the album itself

Connects to registration server.

deleteObject()

 $delete_form=deleteObject($some_object,$mode);
 $delete_form - The HTML of the confirmation form, returned if $mode=1.
 $some_object - Relative name (from album_dir on) of object to delete.
 $mode - 0 = do it; 1 = show confirmation

Deletes the selected object.

moveObject()

 $move_form=moveObject($some_object,$mode,$moveto);
 $move_form - The HTML of the confirmation form, returned if $mode=1.
 $some_object - Relative name (from album_dir on) of object to move.
 $mode - 0 = do it; 1 = show confirmation
 $moveto - The location to move the object to.

Moves the selected object.

createAlbumForm()

 $create_form=createAlbumForm($createalbum);
 $create_form - The HTML for the Create Album form.
 $createalbum - The filesystem directory to create the album in.

Displays the ``create album'' form.

createAlbum()

 $return_code=createAlbum($basedir,$directory,$newshortdesc,$newlongdesc,$newowner,$mode);
 $return_code - Non-zero only if directory could not be created.
 $basedir - The location to create the new album, as an absolute filesystem path.
 $directory - The actual directory name for the album.
 $newshortdesc - Short description for new album.
 $newlongdesc - Long description for new album.
 $newowner - The owner of the album.
 $mode - 0 = No change; 1 = Force album creation, even if not an admin (for uploads)

Creates $directory in $basedir, and updates the description with $newshortdesc and $newlongdesc.

getCookie()

 getCookie();

Gets cookie from browser, and puts it into %cookie hash.

delCookie()

 delCookie("name1","name2",...);

Deletes cookies of provided names. If more than one name is provided, multiple cookies are deleted. Deletion is handled by expiring the cookie immediately. Must be done before the content type header is sent to the browser.

splitCookie()

 splitCookie($param);
 $param = parameter to split

Splits a multi-valued chip into a list of parameters.

showCookie()

 showCookie();

Displays the contents of a cookie in debug level 2.

recentUploads()

 $recent_html=recentUploads();
 $recent_html - Contains the HTML for the recent uploads table.

Returns HTML for the last $::recent_uploads number of uploads, as read from $::upload_logfile.

javaAlert()

 $javastuff=javaAlert($message);
 $message - Message to display
 $javastuff - HTML/JavaScript code to display a popup.

Returns HTML/JavaScript code to display $message as a javascript ``alert'' popup.

genThumb()

 $status=genThumb($myobject,$image_thumb,$mode);
 $status - 0 = Success, 1 = Failure
 $myobject - The full file system path to the object to generate a thumbnail for
 $image_thumb - The full file system path to the thumbnail to create for this image
 $mode - 0 = Generate thumbnails for pictures; 1 = Resize pictures on upload

Generates a thumbnail for $object, according to the current rules for thumbnails. This subroutine requires ImageMagick to be installed in order to work.

isAdmin()

 $status=isAdmin();
 $status - 0 = Not an admin; 1 = Yep, they're an admin!; 2 = They're a user, but they own this album.

Checks to see if the current user is an authenticated admin.

isGuest()

 $status=isGuest();
 $status - 0 = Not a guest, 1 = Yep, they're a guest!

Checks to see if the current user is an authenticated guest.

showBreadCrumbs()

 $breadcrumbs=showBreadCrumbs();
 $breadcrumbs - The HTML for the breadcrumb trail.

Builds an HTML ``breadcrumb'' trail so the user can navigate upwards in their album. $::bread_style defines the format to be used:

 0 = Use folder heirarchy
 1 = use » single » line » breadcrumbs

checkUpdate()

 checkUpdate();

Checks to see if there is a newer version of album.pl available.

randomizer()

 $photo=randomizer();
 $photo - Returned path (from album root) to a random photo.

Returns the path to a random image in the album.

shroudPic()

 $imgcode=shroudPic($image);
 $imgcode - The actual content of the image, to display
 $image - The full file path to the image to display back

Displays the image pointed to by $image, even if it is not under the web root.

searchForm()

 $html=searchForm();
 $html - The search results, formatted in HTML.

Returns the search web form.

search()

 $html=search();
 $html - The search results, formatted in HTML.
 $searchstring - The search string to look for.
 $searchfilenames - Search photo filenames for a match, if non-zero.
 $searchdescriptions - Search descriptions.txt for a match, if non-zero.
 $searchcomments - Search ratings.txt (user comments for a match, if non-zero.
 $searchowners -Search descriptions.txt for matching users, if non-zero.

Searches for $newsearchstring in the locations defined by the combination of $searchxxx arguments, and returns all matching photos as formatted $html.

popular()

 $html=popular();
 $html - The "Most Popular" results, formatted in HTML.

Searches for the $::most_popular number of Most popular photos, and returns the HTML for them.

getPopularViews()

 getPopularViews($directory);
 $directory - Directory to check views information for.

Reads all views information from $directory, and populats @poplist (the list of popular files).

popularityContest()

 $score=popularityContest($num_ratings,$current_rating,$current_count);
 $html - The "Most Popular" results, formatted in HTML.
 $num_ratings - Number of ratings for this object.
 $current_rating - Object's current ratings.
 $current_count - Number of times this object has been viewed.

Takes as input the ratings and views info, and makes a popularity score out of it. The current formula is:

        (($current_rating-2.5) * $num_ratings) + ($current_count / 20)

If you don't like that formula, modify it here.

showObject()

 $html=showObject($myobject,$mode,$uploaduser,$uploadtime);
 $html - The object, as seen in "album view," including thumbnail, ratings, etc. Formatted in HTML.
 $myobject - The path to the object (relative to $::album_dir) to display.
 $mode - 0 = Display object normally; 1 = Display object for Recent Uploads; 2 = Display for Popular List
 $uploaduser - Username that uploaded this file (recent uploads only)
 $uploadtime - Time/date that the file was uploaded (recent uploads only)

Displays $object using the current settings of the album

updateComment()

 $retcode=updateComment($myobject,$comment);
 $retcode - Return value: 0 = Success; 1 = Failure.
 $myobject - The path to the photo, relative to album_dir.
 $comment - The comment to add to the photo.

Adds/Updates the comment in $myobject to be $comment. Uses jhead to actually insert the comments into the photo.

detectBrowser()

 $type=detectBrowser();
 $type - The browser type: 0 = IE variant; 1 = Mozilla (Opera, Netscape, Phoenix, etc) variant

Detects the browser type, and returns the appropriate value

printHTMLeader()

 printHTMLeader();

Prints the HTML header if it hasn't already been printed.

getUserList()

 getUserList();

Reads the entire userlist as defined in the config, and returns it in an ``HTML drop list'' format

DBICheck()

 $dbi_fail=DBICheck();
 $dbi_fail - 0 = DBI package was found, 1 = DBI package not found

Checks to see if the DBI Perl package was installed and returns a status accordingly.

showUserEdit()

 $html=showUserEdit();
 $html - HTML for displaying the "edit users" box

Returns the HTML used to display the ``Edit Users'' box

updateUserList()

 updateUserList($userlist);
 $userlist - The list of users|passwords (in flatfile format) to update with

Updates the auth_db with the provided list of users.