Files Gallery 0.13.0

May 27, 2025 · 9 min read

Creator

Files Gallery 0.13.0 includes a much-improved modal file viewer, markdown editor with live preview, custom thumbnails, automated cache file management and much more.

See demo

The modal file viewer design has been improved, with wider view for file types that include previews, improved navigation UI and persistent fullscreen mode during navigation.

Wide, consistent layout for all file types that include a preview.
File info is now hidden for types that include a preview, allowing more space for the preview.
Improved navigation buttons UI with persistent positions and autohide on mouse idle.
Navigation buttons now also display on small screens and will autohide on touch tap toggle.
Fullscreen button is visible for all file types, and you can remain in fullscreen when navigating.
New useful line-wrap toggle button for the code editor.
Transitions between modal items when the width changes.
New Javascript config modal_types allows you to control modal features per type.
Improved Google docs loading on random failure.

Markdown Live Preview

Since you asked, I have now included a new markdown editor with live preview mode. You can now write markdown while previewing html in real-time, or use the toggle button in the topbar to toggle between Edit, Preview and Split modes. The markdown preview will render image paths relative to the current dir, so it's easy to add and preview images. You can find new config options for markdown and marked in the Javascript config.

Markdown Demo

Custom Preview Images

As a requested feature, I have now added the ability to create custom thumbnails for any file or folder, simply by dropping an image with corresponding file name into the same dir as the original.

Custom Previews Demo

Example usage:

Video thumbnails (if you can't use FFMpeg).
PDF thumbnails (if you can't use ImageMagick).
Custom preview images for external website links.
Custom folder icons for special folders.
Thumbnails for huge panorama images (if they can't be generated automatically).
Artist or track image for audio files.
Zip file with preview image.
Custom thumbnails for special images.
Animated GIF thumbnails.
Programmatically create and maintain your own thumbnails.

Instructions

To create a custom preview image for any file or folder, simply create an image with corresponding file name, and drop it into the same dir as the original. For example, if you have the following:

foldername
image.png
document.pdf

Corresponding file names can be in any image format jpg png or gif:

_files_foldername.png
_files_image.png.jpg
_files_document.pdf.jpg

Custom preview images don't have a specific size requirement, but it's a good idea to target 480 px (long side or square), as this is what we use by default for large previews in Files Gallery.

Limitations

Custom preview images aren't automatically managed by Files Gallery. If you rename, move or delete originals, custom previews won't get updated, moved or deleted automatically. You are required to entirely self-manage your custom thumbnails.

Global custom preview images

You can also create global custom preview images for different file types. Simply create a storage dir _files/previews and include preview images for any extension or mime type. You can target specific extensions jpg.jpg or specific file types image.jpg.

_files
└── previews
    └── video.png
    └── folder.jpg
    └── text.jpg
    └── pdf.jpg
    └── jpg.jpg

Custom Previews Documentation

Image resize cache use dir

New image_resize_cache_use_dir config option allows you to store resized image cache files directly in the same dir as the original. There are several potential advantages:

Stores all resized images inside the same dir as the original.

{dir}/image.jpg
{dir}/_files/image.jpg.jpg

Cache remains valid when moving, copying, duplicating and renaming dirs.
Cache files are automatically managed whenever the dir changes.
Single cache file simply named filename.jpg.jpg
Portable cache, in case you want to migrate cache between servers.

Directory "pollution"

The main disadvantage with this option, is that it "pollutes" your own directories with cache files and folders. This option is therefore disabled by default.

Automatic Cache Cleaning

Previously, the amount of cache files in _files/cache would keep incrementing, without deleting expired cache files (see this post for further details). This of course was a small problem, so I have implemented a "cache cleaner" that occasionally cleans out expired, invalid and stale cache files.

Cleans menu/*.json folders/*.json and images/*.jpg in the _files/cache dir.
Cleans cache at specific intervals through option 'clean_cache_interval' => 7 days.
New 'image_cache_file' => 'cache.txt' tracks cache files and the path to the original.
New allow_manual_clean_cache option allows cleaning cache manually.
Cleans image cache files that have not been accessed for more than 'image_cache_max_last_access_time' => 90 days.
Expired menu and folders cache is automatically cleaned when loading menu or folders.

Manually clean cache

If you want to disable automated cleaning and/or trigger the cleaning process manually, you can use config option 'allow_manual_clean_cache' => true. Trigger the process from browser, with optional &test=1 parameter to simulate cthe process before actually deleting cache files.

index.php?action=clean_cache[&test=1]

More Features

Added on_click custom function in Javascript options to intercept clicks on files and folders.
Added support for HTTP_RANGE header, so we can "stream" large video or PDF files [Github]
Improved urlpath() now checks if paths are relative to application or document root.
On small screens, filter input will now scale to full width on focus.
Improved file caching for folder, video and PDF previews, so they match general image caching.
Fixed so that cursor: not-allowed does not incorrectly apply for input:read-only [forum]
Added support for non-standard ways of images storing EXIF GPS [forum]
Fixed so that custom.css loads on Windows servers [forum]
Fixed filter input to work also when UPPERCASE characters are used [forum]

New Config Options

The following new PHP config options have been added.

_files/config/config.php
// save resize image cache directly in dir/_files/filename.jpg.jpg for improved portability
'image_resize_cache_use_dir' => false,

// attempt to clean up cache every 7 days (0 to disable automated cache cleaning) / It doesn't really matter how often this process runs, as long as it runs once in a while. Set 0 to disable automated cache cleaning.
'clean_cache_interval' => 7,

// allow cleaning cache manually from browser ?action=clean_cache[&test=1]
'clean_cache_allow_manual' => false,

// name of the cache index file that stores image cache entries for cache management. You can disable image cache file indexing by assigning value false. Since this file contains absolute server paths, you might want to rename it to hide it from public view.
'image_cache_file' => 'cache.txt',

// delete image cache files that have not been accessed in 90 days (0 to disable) / This is useful for deleting cache files that were created before the image_cache_file option existed, or if image_cache_file is disabled. It's also useful for deleting image cache files that seem like they are almost never accessed.
'image_cache_max_last_access_time' => 90,

// make sure that image resize cache files are newer than the original they were created for, in case the original image gets updated or replaced. This should normally always be enabled, unless you are using image_resize_cache_use_dir and plan on migrating cache between servers, in which case file dates may change.
'image_cache_validate_time' => true,

New Javascript Options

The following new Javascript options have been added.

_files/js/custom.js
// custom folder preview ratio (unless assigned from {ext}_preview_ratio or {mime}_preview_ratio)
file_preview_ratio: 1,

// custom folder preview ratio (when custom thumbnail assigned)
folder_preview_ratio: 1,

// Google docs viewer extensions regex (when _c.use_google_docs is enabled)
google_docs_extensions: /(doc|ppt|pages)x?$/,

// modal markdown editor config
// https://demo.files.gallery/?files#markdown.md
markdown: {
  enabled: true, // markdown editor with split screen and preview enabled
  extensions: ['md', 'markdown', 'mdown', 'mkdn', 'mkd', 'mdwn', 'mkdown', 'ron'], // extensions to apply markdown editor on
  // modes array and order / default first mode is 'split' on large screens and 'edit' on small screens
  modes: matchMedia('(min-width: 576px)').matches ? ['split', 'edit', 'preview'] : ['edit', 'preview', 'split'],
  remember_mode: true, // remember current markdown mode when navigating and re-opening / if false, will always reset
  scroll_sync: true, // sync scroll in split mode
  html: (html) => html, // custom preview html parser in if someone wants to (html) => DOMPurify.sanitize(html)
  link_target: '_blank', // open markdown preview links in _blank window on click
  // markdown insert shortcuts (you can also toggle between markdown modes with cmd/ctrl-P)
  shortcuts: {
    'B': ['**', '**'],				// Ctrl-B bold
    'I': ['_', '_'],					// Ctrl-I italic
    'K': ['[', '](https://)'],// Ctrl-K link
    'Alt-I': ['![', ']()']		// Ctrl-Alt-I image
  }
},

// pass through options for marked.js markdown renderer
// https://marked.js.org/using_advanced#options
marked: {},

// custom click handler for files, includes e (event) and clicked item object properties
on_click: (e, item) => {
  if(item.is_dir) return; // return falsy value to continue with default click functionality
  console.log('item', item); // contains all properties for the clicked item
  e.preventDefault(); // preventDefault() if you intend to return true and want to block default browser <a> link click
  my_function(item); // do your own thing using the item properties object
  return true; // return truthy value to exit and prevent further  click functionality
},

// modal types configuration
modal_types: {
  dir: {
    anchor: true,					// surround preview image with clickable <a> anchor tag
    info: true,						// show info in footer
    // spinner: false,		// spinner load indicator
    // fullscreen: false,	// open type in fullscreen
  },
  file: {
    info: true
  },
  code: {},
  image: {
    anchor: true, // open image in popup or new window
    info: true		// because image meta data, and photo would by default open in popup anyway
  },
  video: {},
  audio: {},
  embed: {
    spinner: true // Youtube/Vimeo needs spinner class
  },
  pdf: {},
  document: {
    spinner: true	// Google docs iframe can be slow and might repeat so use spinner class
  },
  'custom-preview': {
    info: true
  },
  'video-thumb': {
    info: true
  },
  'pdf-thumb': {
    anchor: true, // open PDF in new window / this scenario is unlikely
    info: true
  },
}

How to update?

Simply download latest Files Gallery index.php or see the update docs.

Improved Modal File Viewer​

Markdown Live Preview​

Custom Preview Images​

Example usage:​

Instructions​

Global custom preview images​

Image resize cache use dir​

Automatic Cache Cleaning​

Manually clean cache​

More Features​

New Config Options​

New Javascript Options​

How to update?​

Improved Modal File Viewer