|
(this file is also available in the distribution as a text file called "INSTALL".)
Installing and Using LiveFrame Gallery
(Many thanks to Wayne Bremser (wb@harlem.org) who wrote the original
LiveFrame Installation Guide, much of which appears below. many of
0.94's changes were inspired by problems Wayne documented (most of
which are have now been fixed and removed from the documentation).)
Contents
A. GETTING THE DISTRIBUTION
B. REQUIREMENTS
C. QUICK START INSTALLATION
D. INSTALLATION
E. CONFIGURATION
F. CREATING GALLERIES
G. MODIFYING TEMPLATES
A. GETTING THE DISTRIBUTION
the latest LiveFrame tarball can be downloaded from:
http://www.liveframe.org/pub/liveframe-current.tar.gz
B. REQUIREMENTS
LiveFrame should run on any system that has perl5 installed. it has
not been tested in non-UNIX environments or with older versions of
perl. I'd love to hear about successful (or unsuccessful) installs on
unusual systems.
C. QUICK START INSTALL/CONFIG
(if LiveFrame seems a little complicated, continue along to step D.)
1. untar the tarball.
2. edit the configuration options. only the first three (paths to
different parts of the software) must be edited, the other four are
optional and documented below.
3. templates are stored in lfdir/templates. all UI changes can be
made by editing these template files. details are documented below.
4. galleries are stored in lfdir/galleries. upload your own content by
using the sample galleries as examples. note that there are several
different ways you can configure galleries; if you don't read any other
documentation, read Section F: CREATING GALLERIES, below.
5. send URLs to your photos to jim@liveframe.org and to all of your
favorite mailing lists.
D. INSTALLATION
find a comfortable directory to untar the tarball in. inside the
resulting directory, you should find a file called liveframe.cgi and
two directories: /docs and /lfdir. move liveframe.cgi and /lfdir to a
location your web server can access. if you want to rename either the
script of the lfdir directory, now is the time to do so. don't rename
the directories inside /lfdir (/galleries and /templates), or
LiveFrame won't work.
the distribution includes three sample galleries (there are three
because previous/next gallery interface doesn't appear on start pages
if there are fewer than three galleries). the easiest way to get
started with LiveFrame is to get things up and running with these
three sample directories. once you've got things working, you can
replace the sample galleries with your own content.
E. CONFIGURATION
open liveframe.cgi in your favorite text editor. the first line
specifies the path to the perl binary on your server; make sure it's
correct.
scroll down to the CONFIGURATION section of liveframe.cgi.
Required Configuration
the first three variables must be edited to point to the location
you moved liveframe.cgi and /lfdir to.
$lfdir is path from the root of the unix filesystem (not the URL) to
the /lfdir directory. if you renamed the directory, be sure you
change it's name here in addition to entering the correct path.
$lfcgiurl is the URL (not the filesystem path) to liveframe.cgi. if
you renamed liveframe.cgi, be sure you change it's name here in
addition to entering the correct URL.
$lfdirurl is the URL (not the filesystem path) to /lfdir. if you
renamed lfdir, be sure you change it's name here in addition to
entering the correct URL.
example: in the filesystem, the web root for liveframe.org is
/www/liveframe/. inside there is a directory called /demo, inside
which is the /lfdir for the demo. you access the demo at:
http://www.liveframe.org/demo/liveframe.cgi
so
$lfdir = /www/liveframe/demo/lfdir
$lfcgiurl = http://www.liveframe.org/demo/liveframe.cgi
$lfdirurl = http://www.liveframe.org/demo/lfdir
Optional Configuration
$sitename
valid options: any
default: "LiveFrame"
specifies what LiveFrame calls itself in various places
$startscreen
valid options: "yes", "no"
default: "yes"
controls whether or not each gallery has a start screen to allow users
to set viewing options or scroll from gallery to gallery. for most
uses leave this set to yes; many LiveFrame features cannot be accessed
if this is disabled.
$sepchar
valid options: any
default: "}"
defines which character or characters to use to seperate image names
from captions in individual gallery configuration files. "}" is the
default because it's a character rarely used in captions. to use old
LiveFrame configuration files with newer versions of the cgi, this
should be changed to ":" (if you make this change, you can't use
colons in captions).
$orderon
valid options: "yes", "no"
default: "no"
controls whether or not a file is used to order galleries in the
index.
if this is set to "no", galleries appear in random order in the
Gallery Index. to prevent galleries from being displayed in the
Gallery Index, add them to the hidden.conf file in the /galleries
directory.
if this is set to "yes", LiveFrame looks for a file called order.conf
in the /galleries directory to define which order the galleries appear
in. if galleries aren't listed in order.conf, they do not appear in
the Gallery Index, or in the previous/next gallery links on the start
page.
save your changes to liveframe.cgi, and test it out by going to the
URL you specified for $lfcgiurl. check out the sample galleries and
make sure they seem to be working correctly. if everything is
working, you're ready to replace the sample galleries with your own
content. good luck!
if everything isn't working, double check your pathnames. make sure
that the scripts and directories are named correctly. be sure your
path to perl is right. make sure your permissions are set
appropriately.
F. CREATING GALLERIES
The easiest way to learn how to add your own galleries is to look at
the sample galleries included with the distribution. inside the
/lfdir/galleries directory, you will find three directories: sample1,
sample2 and sample3.
The Basics
inside /lfdir/galleries/sample1 you will see the three components of a
basic LiveFrame gallery:
1. a preview directory, called "preview". thumbnail images go in
this directory.
2. one or more display directories, called "display" if you are only
presenting one image size, or some combination of "xsmall", "small",
"medium", "large" or "xlarge" if you are presenting multiple image
sizes (more on multiple sizes below). full size images go in these
directories.
thumbnails and display images MUST have the exact same name.
using an image editor with batch image processing will speed up the
creation of LiveFrame galleries considerably. Adobe Photoshop,
Equilibrium Deababelizer, and Macromedia Fireworks all have fast batch
processing; there are also several shareware batch processors
available. I have a Debabelizer script that I run on images that I've
downloaded directly from my camera that creates thumbnails and small
and large versions of my photos for use with LiveFrame.
keep checking liveframe.org for information regarding the release of
LiveFrame Lab, a batch processor designed specifically for use with
LiveFrame Gallery.
3. a config file, called "config".
every gallery must have a config file. open the config file for the
sample1 gallery:
/lfdir/galleries/sample1/config
the first line of each config file is the title of the gallery, and
the description of the gallery seperated by the "}" character (or
whatever you set $sepchar to in the CONFIGURATION section of
liveframe.cgi). the rest of the file is a list of image filenames and
their corresponding captions, seperated the same way. the gallery
title and image names are mandatory; the description and captions are
all optional. the order images appear in the config file are the
order they will appear on your LiveFrame site.
create your own gallery by adding a new directory under
/lfdir/galleries containing a config file and display and preview
directories. once you upload the config file, it will appear in your
LiveFrame Gallery Index.
Showing, Hiding and Arranging Galleries in the Gallery Index
if you set $orderon to "yes", you must also add the new gallery's
directory name to the order.conf file if you want it to appear in the
Gallery Index. the order gallery directory names appear in order.conf
are the order they will appear in your Gallery Index.
if $orderon is set to "no" (the default), and you want to hide a
gallery from the Gallery Index, add it to the hidden.conf file.
galleries will appear in random order in your Gallery Index.
note that directories that are hidden by adding them to hidden.conf or
ommitting them from order.conf aren't really securely concealed;
anyone familiar with how LiveFrame is set up or manages to guess the
name of your gallery will be able to access it. if you need real
security, you should set up a password protected instance of LiveFrame
using your web server's built in security features.
Allowing the User to Choose From Multiple Sizes
if you only want to use one set of images, as the sample1 gallery
does, store your display images in a directory called /display. you
can, however, upload up to five different sizes of display images.
if you want to use multiple sizes, choose any combination of the
following five directories to store your display images in:
/xsmall
/small
/medium
/large
/xlarge
LiveFrame will automatically detect any of the five directories above,
and display the corresponding resize interface on display pages. be
sure you DON'T include a /display directory if you want to use
multiple sizes. if a /display directory is present, only images in
that directory will appear in LiveFrame and the resize interface will
not appear.
if you look at the /sample2 directory, you can see the proper
directory structure for a gallery with small and large images.
for whatever sizes you choose to make available, make sure you upload
a complete set of images for each size, and make sure they are named
consistently. otherwise, LiveFrame will not display them properly.
G. MODIFYING TEMPLATES
LiveFrame is entirely template based, which means that all of the html
(aside from the meta tag that controls the slideshow and the resize
selection options) is seperate from the script itself. this lets you
edit the layout of your LiveFrame system without having to edit perl
code.
one set of templates controls the look for all of your galleries
(future LiveFrame versions may support the ability to modify templates
on a gallery by gallery basis).
each template contains substitution variables that look like this:
%%variable%%
these variables are how the script communicates with the templates.
as you make changes, take care not to change these unless you are sure
you know what you are doing.
there are 18 templates and one cascading stylesheet. they are:
display.tmpl
the innermost of two frameset pages, this one draws the display image
page and the grey navigation bar along the top.
error.tmpl
the universal error page.
frameset.tmpl
the outermost of two frameset pages, this one draws the content page
and the preview pane. if you want a wider or narrower preview pane,
this is the template to edit.
galleryindexbottom.tmpl
the bottom part of the Gallery Index page.
galleryindexitem.tmpl
the middle part of the Gallery Index page. each time the Gallery
Index loads, this template is repeated until thumbnails and links for
each gallery are displayed.
galleryindextop.tmpl
the top part of the Gallery Index page.
lfstyles.css
the global stylesheet defines typefaces for the entire system.
navleft.tmpl
the left side of the navigation bar, which displays the start again
link.
navright.tmpl
the right side of the navigation bar, which displays the hide
navigation link.
navsize.tmpl
the center-right side of the navigation bar, which displays the resize
interface if the gallery has multiple image sizes.
navslide.tmpl
the center-left side of the navigation bar, which displays the
pause/resume slideshow interface if there is a slideshow in progress.
photo.tmpl
the photo display page, which includes the previous/next arrows, the
display image itself, and the caption.
photononav.tmpl
the photo display page if hide navigation has been selected. in
addition to the previous/next arrows, the display image itself, and
the caption, it also includes a show navigation icon in the top right
corner.
previewbottom.tmpl
the bottom part of the preview pane.
previewmiddle.tmpl
the middle part of the preview pane. each time the preview pane
loads, this template is repeated until thumbnails for each image in
the gallery are displayed. this is the most popular template to
customize, because this is where you can change or remove the
hardcoded thumbnail sizes.
previewtop.tmpl
the top part of the preview pane.
startbottom.tmpl
the bottom part of the start page.
startmiddle.tmpl
the middle part of the start page. each time the start page loads,
this template is repeated until thumbnails and links for the previous
and next galleries are displayed.
starttop.tmpl
the top part of the start page.
that's LiveFrame, in 2500 words or less. send ideas for new features,
bug reports, and URLs to strangely customized LiveFrame
implementations to jim@liveframe.org.
have fun!
- J.
James Home
November 02000 |
