Tutorial: MODX and FileLister for Automatic Photo Publishing

Aug 24, 2011

Publish photos all the time? Manage a client's photos? Sick of adding them manually to web galleries? This MODX tutorial is for you!

Ok folks, this one is super fun. I've been waiting weeks to have the time to write about this...and now - well I don't have time but I'm doing it anyways :P

MODX, as you may already know, is the most advanced Content Management Framework in the world, making it easy to publish custom sites of any size without knowing any PHP.

FileLister is a MODX addon that was written to securely list the contents of a directory so a web user could browse a folder on your site without having scary access. BUT, as with most if not all MODX addons, the output is customizable! 

I thought: wouldn't it be cool if FileLister's output could automatically populate a web gallery? Previously I used the awesome getResources snippet for this, but I add photos so frequently, it was becoming inefficient to create a MODX Resource for each image. With the setup I'm about to share with you, I can FTP a bunch of photos to a folder online, and the gallery just displays them. SO EASY!!!!!!!!!!

We'll need: 3 Chunks, 2 MODX Template Variables (optional) and a Partridge in a Pear Tree. I'm assuming you've got MODX Revolution running your site and a gallery page with some kind of plug-in. Here's the official documentation for FileLister:http://rtfm.modx.com/display/ADDON/FileLister

The Snippet Call

I put this in a Chunk but you could just as easily call it directly from your gallery page:

[[!FileLister? &path=`[[*myPathTV]]` &showDirectories=`0` &fileTpl=`galleryItem` &fileLinkTpl=`galleryLink` &outputSeparator=`,` &sortby=`RAND()` &limit=`15` ]]

Break it down:

  • &path » This tells FileLister what folder to pull the image files from. I set it to a TV so that every gallery can have it's own folder - neat! You could just set it, but later you'll see why MODX TVs Rock...
  • &showDirectories » Set to `0` means I don't want Filelister to show any sub-folders in my directory.
  • &fileTpl » The output template to use - I'll go over this later...
  • &fileLinkTpl » Required for our purposes - will also review this below.
  • &outputSeparator » Depending on where your output is going, you might need this. The jQuery plug-in I'm using as a gallery in this example required a `,` separating each instance of FileLister's output - so here it is.
  • &sortby » Making it random. Check out this post about MODX Random sorting.
  • &limit » Limits how many image files to return. If you have a LOT of photos to manage, you might want to set a limit so your gallery doesn't take forever to load.

Because FileLister was made to offer secure file browsing, it's default output is all salted-hash links. Most gallery plug-ins don't like this. SO, here's my template for each gallery item - [[$galleryItem]]:

FileLister Template Chunk

{ image : '[[*myPathTV]][[+filename]]', alt : '[[*optionalAltText]] [[+filename]]' }

NOTE: This will look vastly different depending on the requirements of your gallery plug-in. The one I'm using wants the image file information listed within a script, which is where I have FileLister outputting to. The plug-in outputs that to HTML. The important parts are the placeholders, explained below.

Break it down:

  • [[+filename]] »This gives you....wait for it....the image's FILENAME. But unless your image files are in the site's root, you'll want to add...
  • [[*myPathTV]] » This is why MODX TVs Rock: When used in the snippet call, this same TV told FileLister what directory to list. NOW, it also directs the gallery plug-in. Enter the path once - everything works - change for each gallery if desired. I'm beside myself it's so cool.
  • [[*optionalAltText]] » You don't need this, but if you wanted a nicer alt text for your images, you can add it.

The output HTML tag will contain something like this:

img src"myPath/filename.jpg" alt="Alt Text filename.jpg"

The alt-text-set-by-TV means every image in the gallery will have the same prefix. Ok but not ideal. If anyone knows how to make FileLister pull metadata/EXIF from the image files like "Caption" or something, please comment on this post.

Last Required Chunk

This last Chunk is a template for FileLister's links - [[$galleryLink]]

[[+url]]

Yeah, I know. I'm cringing even as I write this. "What?" you ask, "I have to make a whole new Chunk just to tell FileLister to use the file's URL as a link?!?!?" The answer is, "Yes, as far as I can tell." Otherwise FileLister will still output the link as a salted-hash.

I asked around in the lively MODX Forums if anyone knew how to turn off the hash behaviour, but no luck so far. I'm pretty sure you can also just enter the Chunk code - the url placeholder - as the default value for &fileLinkTpl in FileLister's Property Set. If that works for anyone please comment on this post and let us know. As I mentioned, I don't have a lot of time right now and using a Chunk works well enough for me....

Now, upload image files to the directory specified, and watch the magic happen! Did I miss anything? Feel free to comment below if you have stuff to add. Enjoy!