North Central Washington

Web Development

Downloadable PHP scripts

Showroom

Showroom is the name for a set of php scripts that create links to files within subfolders. The script can be used as the basis for creating an image gallery. Showroom was written by George Wooten of Twisp Webworks.

Click here to see the Showroom demo.

Download Showroom here. Download Showroom as a zipped set of PHP scripts and folders used to create the above showrooms and galleries.

The download contains a zipped set of PHP scripts along with the files and folder structure used by Showroom to create the sample gallery linked to below. The download is free software distributed under the GNU General Public License contained in the download files. Commercial applications may be licensed and further developed by Twisp Webworks (509-997-6010). By downloading this file, you agree to terms of the GNU Public license contained in the download.

The minimal directory structure for Showroom is as follows:


  /showroom/
    index.php - Script 1. Creates a list of linked subfolders in index.htm
    /showroom_files/ optional folder to hold stylesheets, images and included files
    /user-named-subfolder/ This is where uploaded files should go
      index.php - Script 3. Redirects browser to the files subfolder
      /files/ 
        index.php - Script 2. Creates a list of linked files in dirlisting.htm

This 3-tier directory structure separates code, folders and files for better organization, and helps keep code modularized.

Php script no. 1 is the first in a set of 3 scripts that work together. Script no. 1 creates a list of linked user-named subfolders that is output to index.htm and loaded into a browser. Linking to the subfolder then calls script 2, that creates a linked list of files in dirlisting.htm in the /files/ sub-subfolder, which is then loaded into the browser. The list of files used in script 2 is generated by reading the filenames in the user-named folder where the target files are contained.

When the user clicks on one of the linked filenames in the browser window, it opens the file. For use as an image gallery, generation of image thumbnails was done with a companion script called phpThumb() by James Heinrich (info@silisoftware.com) available at sourceforge.net. These routines are not included in this download. The use of phpThumb involves calling the phpThumb() function to generate a thumbnail, which is then included within the link as a thumbnail above the name of the file, using the img src= tag.

For use on a live site, several security measures should be implemented. The phpThumb() script and other functions and css files are contained in a folder located outside the root of the /showroom/ folder structure, where they are safe from meddling. The linked images can be password protected by concatenating the link string with an MD5 hash. For custom css headers and footers, care should be taken to protect the site from potential exploits of the include directive.

The output is designed to wrap at the edge of the browser window, so that the links display in neat rows within fluid containers. Each link encloses the thumbnail and filename within div tags that are styled using classes in an external stylesheet. The style specifies that links and their enclosing div be floated left. Links that would be beyond the right window margin will then be bumped down a row before floating to the far left window edge.

The width of each link is set to auto so that a border can fit snugly around the thumbnails. But the height of the link is fixed to allow extra room for long filenames to be enclosed within the div. This extra space is needed to ensure that the div at the right window edge will be bumped far enough down the screen to allow it to float left below the row above. Floated divs will not float all the way to the left window edge if they are not completely below the previous row.

This is a peculiarity of how floats work. Therefore, the text of the filename was styled as much as possible to fit within the fixed height. Controls on the text style included rendering the text in a small font and allowing for filenames to include spaces or dashes that would wrap in line with the image. If the filename is too long, the text will protrude below the containing div, making it ugly, but at least not breaking the float. Note that in order to use the space character in a name, these have to be encoded into %20 character strings by the scripts. Also, the use of underscores in filenames should be avoided as they prevent the text from wrapping at the edge of the link div.

The css looks like this:


  div.img { margin:2px 2px 20px 10px; border:1px solid #0000ff;
    height:160px; width:auto; float:left; text-align:center; }
  div.img img { display:inline; margin:3px; border:1px solid #ffffff; }
  div.img a:hover img { border:1px solid #0000ff; }
  div.desc  { text-align:center; font-weight:normal; 
    font-size: 0.6em; width:120px; margin:2px; }

And the html should look something like this:


  <div class="img">
    <a href="../02-aspen-catkins.JPG">
    <img src="../02-aspen.JPG" alt="image" /></a>
    <div class="desc">02-aspen.JPG</div>
  </div>

Most of the php code is documented with comments well enough for someone with moderate familiarity to use the scripts.

Steps to create a version of Showroom on your own website.

1. Download the zip file containing the self-contained sample directory with all necessary PHP scripts, stylesheet and identical folder structure to the example.

2. Extract the zip file.

3. Upload the extracted contents of the zip file to a PHP5-capable website and point your browser to the gallery-album folder. That's it.

4. To customize folders and their contents, just replace the example images with images of your choice and rename the folders appropriately.

The scripts can be modified to accept different types of files, images, PDF, etc. types of files or folders that you may wish to link to. The default filters can be placed in for-loops within in the index.php files. A future modification is underway that will allow descriptive image labeling using a textarea input field.

- Copyright 2008+ granted to the Public Domain by Twisp Webworks under the GNU General Public License

- Not responsible for any damages. Always backup files before tinkering!

Happy button-clicking!