Simple Folder Gallery

Simple Folder Gallery is a lightweight, flat-file photo gallery plugin for WordPress. It is designed for developers and site administrators who prefer to keep their media assets completely decoupled from the WordPress database and the heavy wp-content/uploads directory structure.

By utilizing a predictable, structured file system layout on your server and automating the processing of thumbnails on a local machine, this plugin delivers a high-performance, responsive photo grid paired with a fluid, touch-friendly, modern light-box experience via GLightbox.

This is a completely refactored work which began as Mount Olive Pictures which was used for a long time on our church website.

Features

  • Zero Database Bloat: No attachments or metadata are written to the WordPress database. The filesystem is the single source of truth.
  • Decoupled Architecture: Galleries sit completely outside of standard WordPress media folders, making them highly portable and independent of site backups.
  • Automated Reverse Chronological Index: Galleries are automatically sorted in reverse chronological order based on folder name naming conventions (YYYY-MM-description).
  • Modern Overlay Viewer: Completely replaces legacy, rigid pop-up windows with a responsive, swipe-friendly GLightbox engine supporting pinch-to-zoom and keyboard navigation.
  • Smart Fallback Cover Images: Automatically detects a specific cover photo via a pointer file, or intelligently falls back to the first chronological image in the gallery.

Server Directory Structure

To use the plugin, your photos must be uploaded to a dedicated photos/ directory residing within your WordPress installation root (e.g., /public_html/wp/photos/).

Each individual gallery is a folder inside that directory. The system scans and maps your files using the following architecture:

wp/
└── photos/
├── 2014-02-tulips-at-pier-39/ <-- Event Slug (Folder Name)
│ ├── date.txt     <-- Contains YYYYMMDD string (e.g., 20140215)
│ ├── title.txt    <-- Optional: Plain text title override
│ ├── key.txt      <-- Optional: Filename of the album cover image
│ ├── images/      <-- Directory containing full-resolution JPEGs
│ │ ├── IMG_0001.jpg
│ │ └── IMG_0002.jpg
│ └── thumbnails/  <-- Directory containing pre-scaled thumbnails
│ ├── IMG_0001.jpg <-- Scaled down to 90x67px
│ └── IMG_0002.jpg <-- Scaled down to 90x67px
└── 2012-01-sharks_game/

File Specifications & Generation

To maintain snappy page loads and exceptional server performance, thumbnails and structural text variables should be pre-processed on a local staging or development host before being uploaded via FTP or SSH. In my case, this is a Linux host and I have an accessory shell script which creates the thumbnails and images directories and all the necessary .txt files.

Automation Tool: sfg_prep

To streamline the creation of the required folder architecture, date.txt, title.txt, and companion thumbnails on your local Linux machine, you can use the sfg_prep shell utility script. You can download the script directly to your local /usr/local/bin/ or project directory via the terminal:
curl -O http://rinaldo.net/sfg_prep
Alternatively, you can copy the script logic below into a local file named sfg_prep and make it executable (chmod +x sfg_prep) in order to run it directly.

!/bin/sh

# Helper script for Simple Folder Gallery plugin. This accepts one or more directory names and processes the
# images and thumbnails for proper sizing and also generates the title.txt, date.txt & hd.txt files that the
# plugin expects. The user can also create a key.txt file containing the filename of the "album cover" otherwise
# the plugin will simply use the first file found.

# CHANGE obase TO THE DIRECTORY WHERE YOUR TOP LEVEL photos DIRECTORY IS. THAT MIGHT BE SOMETHING LIKE:
# /home1/c430947/public_html/wp/photos OR /home3/c212725/public_html/photos DEPENDING ON YOUR SERVER SETTINGS

obase="/storage/web/bery/wp/photos"

sdir=`pwd`

while [ "$1" != "" ] ; do
  if [ -d "$1" ] ; then
    echo Processing $1
    title="$1"
    dname=`echo $1 | sed 's/ /_/g' | tr '[A-Z]' '[a-z]'`
    target=$obase/$dname
    uniq=0
    while [ -d $target ] ; do
      uniq=`expr $uniq + 1`
      echo -n $target already exists,
      target=$obase/${dname}_${uniq}
      echo try $target ...
    done
    mkdir -p "$target/images" "$target/thumbnails"
    cd "$1"
    hasJPG=`ls *.JPG 2> /dev/null`
    if [ "$hasJPG" != "" ] ; then
      for i in *.JPG ; do
        echo -n .
        oname=`basename "$i" .JPG`.jpg
        djpeg "$i" | pnmscale -xysize 120 67 | cjpeg -optimize -quality 80 > "$target/thumbnails/$oname"
        djpeg "$i" | pnmscale -xysize 1920 1080 | cjpeg -optimize -quality 90 > "$target/images/$oname"
      done
    fi
    hasjpg=`ls *.jpg 2> /dev/null`
    if [ "$hasjpg" != "" ] ; then
      for i in *.jpg ; do
        echo -n .
        oname=`basename "$i" .jpg`.jpg
        djpeg "$i" | pnmscale -xysize 120 67 | cjpeg -optimize -quality 80 > "$target/thumbnails/$oname"
        djpeg "$i" | pnmscale -xysize 1920 1080 | cjpeg -optimize -quality 90 > "$target/images/$oname"
      done
    fi
    day=`/bin/ls -l --time-style=+%Y%m%d "$i" | awk '{ print $6 }'`
    echo $title > "$target/title.txt"
    echo $day > "$target/date.txt"
    echo "hd" > "$target/hd.txt"
    ddate=`echo $1 | grep "^2[0-9][0-9][0-9]-[0-9][0-9]"`
    if [ "$ddate" != "" ]; then
      echo $ddate | awk '{ printf("%s%s01\n",substr($1,1,4),substr($1,6,2)); }' > "$target/date.txt"
      #echo $ddate | awk '{ printf("%s\n",substr($1,9)); }' > "$target/title.txt"
    fi
    echo .
    cd "$sdir"
  else 
    echo "Error: $1 is not a directory"
  fi
  shift
done

Plugin Deployment & Usage

  1. Download the ZIP file from: http://rinaldo.net/simple-folder-gallery.zip
  2. Save the plugin class code into your WordPress plugins directory under wp-content/plugins/simple-folder-gallery/simple-folder-gallery.php.
  3. Activate Simple Folder Gallery through your WordPress admin dashboard.
  4. Create a standard WordPress page (such as /photos/) and embed the simple shortcode layout handler:
[folder_gallery]

The shortcode automatically serves dual-state operations: without parameters, it queries your photos/ tree and renders the master gallery matrix list; when an event parameter is appended to the query string by clicking an item (e.g., ?event=2014-02-tulips-at-pier-39), it seamlessly transitions to the responsive grid display where individual thumbnails launch the smooth GLightbox engine overlay.