Everything you ever wanted to know about the auto index
The auto index was one of our earliest creations, and remains one of our most innovative and unique offerings. It responds to the Web module's most blatant shortcoming, and it's frakkin' magical. As with all things magical, though, it is often met with confusion. Our documentation clearly outlines its capabilities, but reads somewhat technical, so not everyone gets it. In this tutorial, I'll tell you everything you ever wanted to know about the auto index and more, and I'll do it in a way that should be eminently digestible.
This is going to be a lengthy article. I will be laying out some background on the auto index, addressing its layout options, and eventually getting into methods of thumbnail manipulation. It's the latter that users find most arcane.
Most importantly, do not be mislead. The auto index is powerful, and capable to doing quite a lot. But it's also really easy to use. That's the point. A lot of the advanced features discussed below can be ignored by those wanting to take the easy road.
The historical context leading up to the auto index.
The auto index is a superb solution, but what was the question?
Lightroom 1.0 hit the streets allowing the publishing of web photo galleries. Smart!
So you published a gallery, sent the link to your friends, family and clients, and enjoyed the warm, fuzzy feeling welling up inside you.
Sometime later, you published a second gallery and then a third. Now you send three separate links to your friends, family and clients, each leading to a separate gallery, and you begin to realize a problem forming. You push the problem to the back of your mind, eventually publishing a fourth and fifth gallery, and with five disparate links to five disparate galleries in-hand, the problem rages to the fore of your consciousness with more force than ever before:
Image galleries do not a website make; you need some way of tying these things together.
You decide upon a course of action. You roll up your sleeves, pull on your rubber gloves, and plunge your hand deep into the anis of Dreamweaver or your favorite equivalent in hopes of pulling something out other than crap. You end up with a page the same color as your galleries, and a few text links, a block of welcoming text and maybe a picture. It's not great, but it will serve. You put it online and now you have a single location to which to send your friends, family and clients to access your image galleries.
The day comes you want to add another gallery. You export from Lightroom and upload to your server. Then you download your index page, open it in Dreamweaver, add a new link, save, upload and replace. And you repeat this process every time you add or remove a gallery. It's an extra step and tedious, and for many users not well-versed in HTML it can be a struggle. And whatever you do, the page just doesn't look as nice as the website of Famous Photographer X whom you adore and respect. You think, "Surely there must be a better way." And the stage is set ...
The auto index is a better way to organize and maintain your image galleries.
The rise of the auto index.
Standing toe-to-toe with the problems above, I conceived a solution: the auto index. But it would require PHP, and my PHP skills are, in all honesty, nearly nonexistent. I drew up the concept and contracted a friend to help me with the scripting. With a working script in-hand, I then took it to Lightroom to sort out the plugin. PHP being a server-side scripting language and Lightroom being not a server, it would not be able to preview the script. The plugin therefore became a two step endeavor, first rendering a fake page within Lightroom during the design process, and then translating those design decisions into functional scripts and components on output. Through experimentation, trial and error I got things working and released my work to the public. For years, it stood.
Heading into the CE versions, I made the acquaintance of John Bishop, a photographer and TTG user with loads of scripting experience. He liked the auto index, and offered to make it better, more solid. John would later help me to create our password protection and PHPlugins features as well.
For CE2, we revisited the auto index yet again. I restructured the indexing scripts in such a way that we would be able to implement password protection on image galleries and added support for the padlock icons on protected galleries. John then reinforced and expanded the script, allowing us to call on the auto index to generate dynamic drop-down menus of galleries, adding new methods of controlling thumbnails, and more.
Two variations of the auto index.
The auto index is available in two engines, TTG CE2 Auto Index and TTG CE2 Pages. In each case, the index is essentially the same and follows the same rules. The difference is that TTG CE2 Auto Index is portable and can be deployed in any location for any number of purposes, while the Galleries page in TTG CE2 Pages operates from a single, dedicated location and is solely intended for use as your website's main index of image galleries.
Which should you use? Do you need both? That depends on you and what you want to do.
If you're building a complete website using TTG plugins and require only one index to corral your galleries, then TTG CE2 Pages will suffice.
Purposes requiring TTG CE2 Auto Index include:
- You're not building a website, but want a standalone index in which to organize your image galleries;
- You have a preexisting website and wish to add an auto index to organize your image galleries;
- You're building a website with TTG CE2 Pages, but want more than one top-level index of image galleries -- for example, you want a separate index for client galleries, or you want a main portfolio and a separate index for recent work or personal projects;
- You're building a website with TTG CE2 Pages, but you want to organize your galleries into subcategories within the main index, for example having categories for Travel, Portraiture and Concerts, each containing multiple image galleries;
- You want to create a gallery of video clips;
- You want to create a gallery of retouch examples;
Moving along ...
Adding galleries to TTG CE2 Pages
In TTG CE2 Pages, the Galleries page lists image galleries which are located within the
/galleries/ folder. The
/galleries/ folder is created when TTG CE2 Pages is exported from Lightroom.
Image galleries should exist each as individual folders within the
Adding galleries to TTG CE2 Auto Index
In TTG CE2 Auto Index, image galleries are located within the auto index folder itself. This folder will bear whatever name you assign it when exporting.
Image galleries should exist as individual folders within this folder.
How the auto index works
A complete understanding of the auto index's inner workings may be had in the official documentation. Here, we'll do the short version. Let's begin by looking inside one of our image galleries ...
On the right, we peer into the contents of one of our image galleries. The two items highlighted green --
autoindex.xml and the
/thumbnails/ folder -- are of importance to our auto index.
autoindex.xml is the most important component; the auto index will list any folder containing an
autoindex.xml file. The file contains vital information for the listing of our image gallery. First, the presence of the file indicates to the auto index that a list-item should be created for this folder. The auto indexing script then looks into this folder to extract our Album Title and Album Description, and optionally instructions for displaying an Album Thumbnail and an Album URL.
autoindex.xml is like a passport that every image gallery carries around, and this passport identifies that gallery to our local authorities, the auto index. This information resides within the gallery itself; while the auto index displays this information, it does not own this information.
So, where does the
autoindex.xml come from?
Every TTG image gallery contains this in the Output Settings control pane:
When creating the image gallery, this should be filled in. The information here is published in the
autoindex.xml file. Think of this as a passport application for your image gallery. The most important items to fill in are the Album Title and Album Description. It's okay to leave Album Thumbnail and Album URL blank; we'll talk more about these later.
Of secondary importance is the
/thumbnails/ folder. Unless told to do otherwise, the auto indexing script will dig into your
/thumbnails/ folder and randomly pull an image to display in the list-item for each image gallery. This process is automatic. Users may override the automatic behavior, but more on that later.
The takeaway information for this section is this:
Every image gallery should be assigned an Album Title and Album Description during gallery creation. This information will later be used by the auto index.
On thumbnail sizes ...
We will talk about thumbnails in more detail further on, but there is one very important thing to understand and it's best understood from the start.
The thumbnails displayed within the Lightroom preview when designing your index are not actually the thumbnails that will be used by your published index. They are standins only, used only as a point of reference so that you may design your page.
Published indexes will draw upon thumbnail images from within the image galleries themselves, and those thumbnail images will be sized according to the settings used to create that image gallery, not the sizes specified by the auto index design.
For easiest implementation, plan ahead. Know the size of your image gallery thumbnails, set your thumbnails to that same size when designing your auto index, and design your index accordingly. If you want larger, more iconic images to be used by your gallery index than actually appear in your image galleries, we can do that and will discuss it further on; but know that it will require additional steps in our publishing workflow.
The auto index, a chameoleon.
The layout of the auto index is very flexible, capable of many different page designs. The three layout styles are 'Descriptive', 'Iconic' and the unfortunately named 'Iconic, Entitled'. Within this three basic layout types exists potential for many more visual styles. Let's take a look at some of the possibilities.
The 'Descriptive' Layout
What the 'Descriptive' layout lacks in visual oomph, it makes up for in ease of deployment. The default layout for the auto index, it is also the easiest and most hands-off to implement. The layout displays both the Album Title and Album Description, and allows a highlight color when list-items are moused-over.
The descriptive layout comfortably accommodates thumbnail images of any size. Images smaller than our design will be displayed at their native size, while overlarge images will be scaled down to fit entirely within our boxes. Whatever the size of your thumbnail images, your design will never break. And so, you never need think about your thumbnails at all (though you can if you want to). Being so fully automatic makes this the easiest layout to deploy and the best choice for TTG beginners.
The list-item box dimensions and shapes may be changed. Here's an example with different box dimensions and rounded corners:
The 'Iconic' Layout
With the 'Iconic' layout, we start making sexy. The focus of the layout is on large, graphic icons to represent our galleries. Thumbnails with OOOMPH!! That's what we get when we go Iconic. But we also make more work for ourselves ... probably, maybe. Let's look at some examples.
But if we leave the automatic thumbnail selection enabled and we publish galleries with smaller thumbnails than our auto index design, we end up with this ...
We get around this either by using very large thumbnails in our image galleries, or by using custom thumbnails. And this is what I was referring to when I said we might be making more work for ourselves. But I get ahead of myself. We'll talk about custom thumbnails further on. For now, back to the 'Iconic' layout.
In this layout, the idea is that thumbnails be used to completely fill index entry's box. The Album Title and optional Album Description may be made to appear as an overlay on the thumbnail image. You can see various configurations of this in the images above. The overlay can be always on, or it can slide or fade in on mouseover. The overlay may be attached to the top or bottom of the image, or may cover it completely.
The 'Iconic, Entitled' Layout
The 'Iconic, Entitled' layout offers a variation on the 'Iconic' layout where Album Title and Album Description appear beneath the thumbnail, rather than in an overlay. Again, large images are the focus of this layout. Here's a basic example:
As with the 'Iconic' layout, it's possible to create square, rectangular, circular or odd-shaped thumbnails.
As promised, let's talk about your thumbnail options.
The default is that your auto index will randomly select a thumbnail image from each image gallery and display it on the index page. This is great because it's fully automatic, and works out very well with the 'Descriptive' index layout. Finally, if using TTG CE2 Horizon for your image galleries the random thumbnails work out well because the galleries don't actually display thumbnails, so are are free to export galleries with thumbnails however large you want them to appear in the index.
Because the random thumbnailing is completely automatic and hands-off, it's the easiest to use. To enable random thumbnailing, leave the Album Thumbnail field blank:
But random thumbnailing may not be appropriate for all layouts. For example, consider our 'Iconic' layout in which the album thumbnails are designed to be much larger than our gallery thumbnails:
In this situation, we will want to use custom thumbnails. And we have two options for doing so.
In situations where it may be undesirable to have thumbnails selected at random, you may instruct the auto index to use a specific thumbnail. This may be a specific thumbnail from within the
/thumbnails/ folder, or a custom-made thumbnail that you've created separately from the gallery. There are lots of ways to create custom thumbnails, either cropping and exporting from Lightroom or creating them in Photoshop or some other application.
To use a specific thumbnail, supply the path to the thumbnail image relative to the gallery folder.
For example, to target a thumbnail within the gallery's
/thumbnails/ folder, we would write the path this way:
This gets filled into the Album Thumbnail field:
Here's a fun tip. If I plan to use custom thumbnails with a design, I will often fill in "thumbnail.jpg" as my Album Thumbnail, and will then save this as part of my template using the Template Browser. It looks like this:
Later, I export my gallery. In each of my gallery folders, I drop a custom thumbnail image named
thumbnail.jpg, like this:
Because I've saved the Album Thumbnail with my template, I never need to revisit the field again, and it's dead simple to add a
thumbnail.jpg file to each of my image galleries as I export them.
Custom Thumbnail Folders
It's also possible to create a folder containing several custom thumbnail images, and to have the auto index randomly select one of those thumbnails.
To specify a folder of custom thumbnails, supply the path relative to the location of the index. This folder may be inside the gallery folder (that's where I like to keep it), or in another folder. For example:
To instruct the auto index to select a thumbnail image from within this folder, we provide a relative path from the auto index location. In this example, that path would be:
Again, this goes into the Album Thumbnail field when creating our image gallery.
Troubleshooting the Auto Index
Sometimes, you may find that the auto index is not behaving as expected. Typically this will be due either to an inadequate hosting environment, or to pilot error. Here are some common conundrums, how to diagnose them, and what to do about them.
No thumbnail image!
Using one of the Iconic layouts, you find that your index entry is missing a thumbnail image. This is probably because you've named your image gallery folder using a space. When it comes to the web, spaces are bad and they don't belong in folder names.
For example, maybe you've named the folder "Trip to Italy". Well, that's a problem. Try "Trip-to-Italy" instead, or "Trip_to_Italy".
Space Invaders! Aaaah!
You were expecting a thumbnail, but all you got was a space invader. What the hell?! This guy shows up when the gallery can't find any thumbnails. This typically means you're missing a
/thumbnails/ folder in your gallery and either ... a) have not specified a custom thumbnail, or b) have specified a custom thumbnail, but have done so incorrectly so that the thumbnail cannot be found.
I specified a thumbnail, but thumbnails are still random
If you've specified a random thumbnail but still find that your index entry is drawing thumbnails at random, it means that your custom thumbnail path is invalid. The auto index cannot find your thumbnail, and as a fallback is pulling images at random from the
Titles and descriptions disappear when they contain invalid characters. The most common culprit is the ampersand -- & -- so don't use it. If your title is "Italy & France", try using "Italy and France" instead.
If you're not using ampersands, but still find your titles or descriptions vanishing, look for other oddball characters: punctuation, non-English letters, etc. and replace them with more vanilla content.
I see errors!!
If you're seeing errors, it probably means your host fails to meet our minimum system requirements of Linux OS, Apache server and PHP 5.2.6 or newer. The auto index contains a verification script for testing whether your host is capable of running the auto index. It's located at
/resources/autoindex/verify.php. Run the script in your browser by prepending that path with the URI of your auto index.
If your host is inadequate, one or more of the checks will FAIL. Contact your host about resolving the matter. Depending on the problem, you may need to move to a new server or upgrade your PHP version. If the host cannot sort you out, consider moving to a better host; we trust Bluehost and recommend them fervently.
Debugging the auto index
Apart from the issues above, the auto index contains several debugging tools which may be accessed by URL. To use these tools, append the following commands to your auto index URL.
Displays whatever information the auto index is getting from the
autoindex.xml files in each of your image galleries.
Reports all actions and findings whilst the index scans your folders.
Displays information about your PHP version and configuration.
Using TTG CE2 Auto Index, you may call these actions on your index location:
Using TTG CE2 Pages, you should call these actions on
Now you know ...
... and knowing is half the battle.
That pretty well covers everything you could possibly want to know about the auto index. From this day forward, I will very likely greet auto index questions with dirty looks and links to this article. Ta!