- PHOTOLIB - --========-- Sections --========-- 1. About 2. Installation 3. Administration 4. Maintenance 5. Reporting Bugs 6. Using the Library 1. About --==-=====-- Photolib is a program to automatically and seamlessly create a web photo album for you. Although, unlike other photo album programs, Photolib is in a library format, allowing the user to have complete control over the layout and the ability to integrate it into their script-based websites. Other programs require you to work around their own theming functions, which can often be complicated and limited in the depth of control. Photolib is designed for people who already know a little Perl and want control of their layout at all levels. 2. Installation --==-============-- Before you can install and use Photolib, a few pieces of software must be on your system, including: * Perl's DBI module * Perl's DBD::mysql * Perl's Getopt::Long * ImageMagick (v5.3.5 recommended) * PerlMagick (available with the ImageMagick source) * Perl's Image::Size You can get ImageMagick and PerlMagick from http://www.imagemagick.org/. For the other Perl modules, you can use CPAN to install them. Run "perl -MCPAN -e shell" and at the prompt, type "install DBI", "install DBD::mysql", "install Image::Size", "install Getopt::Long", and you're set! To install Photolib, you must first extract and create the database, then you edit the configuration file, and finally, you have it load the contents of your photo galleries. Follow these simple commands: $ tar xzvf photolib-0.2.tar.gz $ cd photolib-0.2 $ ./install $ vi htdocs/config.plib (use whatever editor you want) $ mkdir 777 /your/cache/directory $ chmod 777 /your/cache/directory $ ./scripts/refresh -c htdocs/config.plib $ cp htdocs/* my_website_directory/ $ cp examples/* my_website_directory/ You should be all set now. It is recommended that you edit your directory and file scripts, since after all the point of Photolib is so you can customize your album. In the future, the install script will take care of everything else for you, simplifying it a lot. Until then, the process is slightly more complicated. Also, the shell scripts will be moved to a better location. 3. Administration --==-==============-- To administrate Photolib, go to the admin.pl file through your web browser. From here, you can set the directory and file short/long descriptions. To use it, select the file or directory to want to set them for, then enter it in the text boxes near the top of the screen, and click Update. It is recommended that you place admin.pl in a secure or out-of-the-way location, then upadate the config_file variable at the top of it to point to your Photolib configuration file. Future versions on the Web Administration Interface will have built in authentication, as well as the option to refresh directories, scale the original image, rotate images, and delete images/directories. Right now, it is for the barebone basics. 4. Maintenance --==-===========-- Every so often, you should run the cache cleaning script to remove scaled images that haven't been accessed in a while. Run it like such: $ scripts/cleancache -c your_config_file -d 14 That would clean all cached images that haven't been accessed in 14 days or more. You could run a weekly cron job to take car of them. Put this in your crontab: 0 0 * * 0 /path/to/cleancache -c your_config_file -d 14 5. Reporting Bugs --==-==============-- Since Photolib is still in the early stages, it is probable that you could run into a bug in the system when using the software. If you do, please report it to me at ken@qgyen.net so that I can continue to make Photolib better. When reporting a bug, please give a detailed description of what is happening. Scan through the end of your web server's error logs and send me that output of anything related to Photolib. Also, it would be helpful to have a mysql dump of that portion of your database, and possibly even the source you are using the gallery in. The more you can send, the easier for me to recreate your scenario. I do ask that before you report bugs, to make sure that the bug is not related to your configuration or your usage of the library. I can't be fixing everybody's gallery scripts. 6. Using the Library --==-=================-- Here you will find a brief description of the library functions. To see them in action, look at the included examples in the examples/ directory. &photolib::start; This function is what gets Photolib setup and ready for use. It loads the configuration file and connects to the database. It is pretty straight forward, takes no input and returns no values. If it cannot connect to the database or load the configuration file, it will exit the program. This must be called before doing anything else with Photolib. By default, it looks for the config file in the current directory. If it isn't there, then you need to assign it like so: $photolib::config->{'config_file'} = "/path/to/config.lib"; &photolib::stop; This function closes off Photolib. Specifically, all it does is disconnect from the database, which is not required but is a good idea. &photolib::info(entryid); The info() function requests all the available data on a specified entry id. Entry ids are in the form of an integer, and are provided either by the browser in the query string (ie, they clicked a link for a file), or are assumed to be 1 if none is given. An entry id of 1 is always the / directory in the albums. The function returns a hashref with all the data. The fields for directories include: entryid, type ('D' for directory), typeid (aka dirid), dirid, name, short_desc, long_desc, fullpath, numcontents, parentid Files have the following fields: entryid, type ('F' for file), typeid (aka fileid), fileid, name, short_desc, long_desc, dirid, directory (the dirid's fullpath), mimetype ('jpeg', 'gif', 'png'), size, width, height, modified (the date it was modified/created) This would be used as so: $info = &photolib::info(1); print "You are in directory: $info->{'fullpath'}"; &photolib::contents(entryinfo, "main::dir_sub", "main::file_sub", offset); contents() is the function used to print out the directories contents. It handles the majority of the formatting for you, while leaving the specifics very customizable. To use it, you must pass it the entry info (output from info()), the name of a function to call to print a directory entry, the name of a function to print a file entry, and the current offset. If no offset is provided, it will assume it to be 0. The names of functions for directory and file printing refer to functions within your program that handle how you want the the contents to physically look. Refer to directory.pl in the examples/ directory for working examples. Basically, the contents are always printed in a table. Before you call contents() you must have the tag with any settings you want. contents() handles the and tags based on yout specified number of columns in the config file. Your directory and file functions must have the
tag and set it up however you want it. The functions will be passed the entry info (same type of entry info from info()) and must return the cell data as a string. No print() calls, everything must be returned as a string to be included in with everything else. Additionally, you must give the function names as "main::my_function" so that Photolib knows the functions are in the main package and not within its own package. Look at how directory.pl works to get a clear and complete picture. Overall, all the output from contents() is returned as a string. It doesn't include the
call. &photolib::link(entryinfo, offset); link() will return a string containing the URL to link to the specified entry. To use it, you must pass the entry info (the stuff returned from info()) as well as the offset, or which entry to start with. If you are linking to a file, then no offset is needed. If it is a directory, you can leave out the offset and it will be assumed to be 0, or the start of the directory. &photolib::imagetag(entryinfo, size, border); imagetag() returns a string containing the whole tag to display an image. It needs the entry info (output from info() call), the desired width of the image (aka size), and the border to be placed around the image. If no size is specified, it will use the default size from the config file. And if no border is given, it will not specify anything and leave it up to the browser's default (normally none, unless it is in a link). &photolib::offsetlinks(entryinfo, offset); Directories will often have more than one page to them if there are more files than you max rows and columns can hold. A call to offsetlinks() will return an array containing the URL to the next and previous pages. If one of them is not necessary, it will just be null. In the array, the prev link is in position 0 and the next link is in position 1. The inputs to offsetlinks() are tbe entry info (output of info()) and the current offset. If there is no offset, it will default to 0.