Difference between revisions of "VideoTools mkgallery"

Revision as of 14:56, 27 October 2007

The mkgallery program makes galleries of still and video images.

Short explanation:

Create a 'my_gallery.gal' file that looks like this:

  title "My First Photo Gallery"
  intro "This is an explanation of this gallery page"
  base_url "../support_files"

  group "First Group title"
  {
    image1.jpg    "Description of image1"
    image2.jpg    "Description of image2"
  }

  group "Second Group title"
  {
    image3.jpg    "Description of image3"
    movie.flv     "Description of movie"
  }

  group "Third Group title"
  {
  # All of the files in the "images" subdirectory:
    all images
  }

  ....

Then, run:

  /u/videotools/gallery/mkgallery  my_gallery.gal

...it will generate an 'index.php' file and a bunch of new '.jpg' files. Copy all of those plus all of the files in /u/videotools/gallery/support_files onto the server and you should have a working gallery.

Now customise your copies of the support files however you like.

Long Explanation:

The mkgallery command takes a list of 'gallery' files (they are all concatenated together if there is more than one).

The gallery files can contain:

• Comments that begin with a '#'.
• An optional 'title' for the entire gallery. If you leave it out, you get "Photo Gallery":

     title  "This is the title"

• An optional 'intro' for the entire gallery. If you leave it out, then some simple instructions for using the gallery will be displayed:

     intro  "This is an introductory text for the gallery"

• An optional 'base_url' where all of the support files (css, php, js, etc) are to be found. If you leave it out, then the support files must be in the same directory as the images:

     base_url  "../support_files"

• An 'include' of another gallery file:

     include mygallery.gallery

• A 'group' command that groups a bunch of photos together with an optional description next to each one. eg:

     group "group title"
     {
       image1_filename.jpg  "Description of image 1"
       image3_filename.jpg  "Description of image 3"
     }

A missing description is the same as an empty description.

     group "group title"
     {
       image2_filename.jpg
     }

• The 'all' command (inside a group) followed by a directory name causes all of the '.jpg', '.jpeg' '.png' in that directory to be added to the group. Note that files that end "_video.jpg", "_100,jpg", "_400.jpg" and "_1024.jpg" are likely to have been made by mkgallery - so these are NOT added to the gallery. Additionally, there is no way to provide a description with this approach. eg:

     group "group title"
     {
       all subdirectory
       all .
     }

• Video files (in ".flv" format) are supported - but you must provide a parallel file - preferably at the same resolution - with the same name but with _video.jpg rather than .flv (eg myMovie.flv must come with myMovie_video.jpg). Generally the _video.jpg file should be a frame from the video - but it can be anything representative of the video clip.

     group "group title"
     {
       myMovie.flv       "This was my first movie"
       myOtherMovie.flv  "This was my second movie"
     }

• Please note that the title, intro and base_url commands MUST all come before the first group command.

Mkgallery then produces:

1. An 'index.php' file that displays the images.
2. An 'update_list.dat' file that lists the names of the images that changed - and should therefore be re-uploaded to the server.
3. A set of resized images to send to the server. The way the sizes of these images are calculated is complicated:
   • The 'thumbnail' image is always exactly 100 pixels high unless the source image is less than 100 pixels high, in which case it will be the same size as the source image. The width of the image automatically adjusts and can be as wide or as narrow as necessary to make it 100 pixels high.
   • The 'navigational' image is at most 400x300. If the original image does not have a normal 4:3 aspect ratio, it will be scaled to fit within a 400x300 pixel box. If the source image is smaller than 400x300 then the navigational image will simply be the source image.
   • The 'large' image is at most 1024x800 and follows the same scaling rules as the navigational image. This image is not generated for movies.
   • The 'original' image is the size of the original photo.
   • In all cases, if the original image is smaller than the required size then it will not be expanded - the largest available version will simply be passed in that slot.
   • If the source image is older than the resized ones already in this directory - then to save time, the image resizing operations are skipped.

In any event, the actual size of each version of the image will be passed as the 'ww' and 'hh' parameters so that the PHP code may choose whether to expand it for display or not.

Support Files.

Right now, all of the support files are expected to be in the same directory as the images on the server. There are examples of all of these in the subdirectory 'support_files'. All of them are needed but all could (in principle) be modified to change the way things look.

The PHP Code.

The 'gallery.php' code is called by 'index.php'. It generates all of the HTML for the gallery page. It pulls in 'gallery.css' and 'gallery.js' to contain the customised CSS and JavaScript code for this page. 'gallery.js' must include a function called 'swapPic' to swap the navigational picture over when you click on a thumbnail. I would strongly suggest you don't mess with that!

When you click on a navigational image, a second PHP script (either 'image.php' or 'video.php') is run to generate a custom HTML file for that specific image. It in turn references 'image.css' and 'image.js' (or 'video.css' and 'video.js') so that you may customise the look of the thing.

In order to allow a fully customised menu structure, the gallery, image and video pages all include 'menu.php' and call the function 'menu()' passing the URL, the document title and the description:

   menu ( "http://www.sjbaker.org/gallery", "Image Gallery", "A description of my image gallery" ) ;

The HTML output.

The resulting HTML goes straight from the file server to the browser - the only way to see it is to do a 'Show as source' in the browser. Both gallery and image HTML outputs have 'class' tags on every single structure that you might want to customise. The names are fairly logical:

gallery.css may define:

  .gallery_table {}
  .group_td {}
  .group_table {}
  .group_title_th {}
  .navigation_td {}
  .navigation_a {}
  .navigation_img {}
  .thumbnail_td {}
  .thumbnail_p {}
  .thumbnail_img {}

image.css may define:

  .image_body {}
  .image_header {}
  .image_description_p {}
  .image_img {}

The '.thumbnail_p' class is very important to the way things work because it contains all of the scrolling mechanism.

The default 'menu.php' (which you'll probably replace) uses two CSS classes:

  .menu_body {}
  .menu_header {}

...which (if you need to override them using CSS) will need to be set up in gallery.css, image.css and video.css.