My export plugins for Lightroom offer the ability to create template presets for constructing titles and captions used for the exported photos. They're designed to allow you to combine photo metadata with your custom text on a per-image basis.
The rest of this page documents the template notation as it exists for the latest versions of the plugins. If something doesn't seem to work as documented, please make sure you're using the latest version of your plugin by using the [check now] updates button in the last section of each plugin's export dialog.
A template is a combination of prose and special tokens wrapped in { ... } that insert photo-specific items.
For example, the template
Copyright {YYYY} {Artist}
includes the text “Copyright”, a space, the token YYYY (which stands for the year that the photo was taken), a space, and the Artist token (which stands for the value of the "Artist" metadata item).
For one of my photos taken in 2006, this example would become
Copyright 2006 Jeffrey Eric Francis Friedl
Here is the list of tokens that are currently supported:
| YYYY | The year the photo was taken, as a four-digit string |
| YY | The year the photo was taken, as a two-digit string |
| MM | The month the photo was taken, as a two-digit string |
| DD | The day of the month the photo was taken, as a two-digit string |
| HH | The hour value for the time the photo was taken, as a two-digit string |
| MIN | The minute value for the time the photo was taken, as a two-digit string |
| SS | The seconds value for the time the photo was taken, as a two-digit string |
| Mon | The month the photo was taken, as a localized three-character string |
| Month | The month the photo was taken, as a localized string |
| Date | The day of the month the photo was taken, as one- or two-digit string |
| yy | The current year as a two-digit string |
| mm | The current month as a two-digit string |
| dd | The current day of the month as a two-digit string |
| hh | The current hour value, as a two-digit string |
| min | The current minute value, as a two-digit string |
| ss | The current seconds value, as a two-digit string |
| mon | The current month, as a localized three-character string |
| month | The current month, as a localized string |
| date | The current day of the month, as one- or two-digit string |
| Caption | The “Caption“ metadata string |
| CopyName | The name of the copy (master or virtual) being exported, if any |
| Empty | An empty string, perhaps useful for testing |
| Filename | The filename – without path and without extension – of the exported copy |
| FILENAME | Like Filename, but includes the extension |
| LibraryFilename | The filename – without path and without extension – of the master file in the library (which is not necessarily the filename being generated for the exported copy) |
| LIBRARYFILENAME | Like LibraryFilename, but includes the extension |
| Filetype | One of: “JPEG”, “PNG”, “TIFF”, “PSD”, or “DNG” |
| FocalLength | Focal Length, as a number |
| FocalLength35 | Focal Length in 35mm format, as a number |
| FocalLengthMM | Focal Length (with locale-specific “mm” appended) |
| FocalLength35MM | Focal Length in 35mm format (with locale-specific “mm” appended) |
| Folder | The name of the folder (without path) in which the master image in the catalog resides |
| Path | The full path of the folder in which the master image in the catalog resides |
| Headline | The “Headline” metadata item |
| Rating | The number of stars assigned to the image: “0” through “5”. You can also use with an argument, e.g. {Rating=*} or {Rating=great } to have, for example, a three-star photo result in "***" or "great great great". In either case, a photo with a zero rating results in nothing, but you can combine tokens (as described below) along these lines: {Rating=*|"unrated"}. |
| Title | The “Title” metadata item |
| ColorLabel | The “Label” metadata item |
| Artist | The “Artist” metadata item |
| Scene | The “Scene” metadata item |
| Location | The “Location” metadata item |
| City | The “City” metadata item |
| State | The “State” metadata item |
| Province | The “State” metadata item |
| Country | The “Country” metadata item |
| Source | The “Source” metadata item |
| Copyright | The “Copyright” metadata item |
| OriginalWidth | The width of the original image (not the exported one), in pixels |
| OriginalHeight | The height of the original image (not the exported one), in pixels |
| UUID | Lightroom's internal unique identifier for the photo (a long sequence of letters and numbers) |
| Aperture
ApertureNum CameraMake CameraModel CameraSerialNumber Creator CreatorAddress CreatorCity CreatorCountry CreatorEmail CreatorJobTitle CreatorPhone CreatorState CreatorUrl CreatorZip Exposure ExposureBias ExposureBiasNum ExposureProgram Flash GPSAltitude GPSCoordinates ISO Latitude Longitude Lens MeteringMode ShutterSpeed ShutterSpeedNum SubjectDistance SubjectDistanceNum EditCount Cropped | Items that I added on Sep 14, but have yet to document here. See the “Token Exaples” button in the plugin for examples of each item. |
| " text " | The text as provided. It may not contain the following characters: { | } " |
| - | Inserts a hyphen that is never squelched; essentially the same as {"-"} |
| , | Inserts a comma that is never squelched; essentially the same as {","} |
Token Basics
As mentioned above, tokens are identified within a template by wrapping them with { ... }. The value generated by the token has leading and trailing spaces removed before being inserted into the result. For example, if the “Caption” metadata item is the string “My Vacation ”, the value actually used for the Caption token (which appears as “{Caption}” in the template) is “My Vacation”.
Combining Tokens
You may list multiple tokens within { ... }, separated by | (a vertical bar). In such a case case, the first token that results in non-empty text is used. Tokens may result in an empty value if the photo is missing the associated metadata. For example, if a photo is missing the “date taken” metadata, the YYYY token is empty. Thus, the previous copyright example may be better written as:
Copyright {YYYY|yyyy} {Artist}
In this case, if the YYYY token is empty, the yyyy token (the current year, which can never be empty) is used.
Continuing with this example, because the Artist token results in an empty item if there is no artist metadata, this example might be written as:
Copyright {YYYY|yyyy} {Artist|"by the photographer"}
to become
Copyright 2008 by the photographer
when there is no artist metadata.
Token Filters
Filters allow you to modify the text that a token generates. For example, applying the S2U filter (“Space to Underscore”) to the “Caption” example given earlier results in a value of “My_Vacation”. To indicate that a filter should be applied to a token, append it to the token name with a colon. This example appears would appear in a template as “{Caption:S2U}”.
Token filters:
| S2U | Space to Underscore | Any sequences of spaces (and/or underscores) are replaced by a single underscore |
| S2D | Space to Dash | Any sequences of spaces (and/or dashes) are replaced by a single dash |
| U2S | Underscore to Space | Any sequences of underscores (and/or spaces) are replaced by a single space |
| D2S | Dash to Space | Any sequences of dashes (and/or spaces) are replaced by a single space |
| DU2S | Dash/Underscore to Space | Any sequences of dashes, underscores, and/or spaces are replaced by a single space |
| After=text | Use value to the right of text | If the given text is found in the value that the token generates, strip it and all that appeared before (to the left), leaving only what appears to the right of text in the value. If the text is not found in the value, the result of the token is empty. For example, if you tend to use captions like “My trip to Paris” and “My trip to the Canadian Rockies”, and you wanted shorter text, you might consider using {Caption:After=trip to} to result in values like “Paris” and “the Canadian Rockies”. If you wanted to implement an idea such as “Strip the '...trip to' text from the caption if it's there, and use the unadulterated caption if not”, you would append an unadorned Caption token as described in the “Combining Tokens” section above, resulting in {Caption:After=trip to|Caption}. |
Squelching Superfluous Joining Characters
Within a template, joining characters are special. These are the space character, the hyphen/minus character, and the comma character. After a photo-specific value has been computed from a template, all leading and trailing joining characters are removed, and embedded repetitions are replaced by a single item.
As an example of the first case, consider
Copyright {YYYY|yyyy} {Artist}
when there is no artist metadata. Without these special rules, this would result in the derived value having trailing space, but the special squelching rules remove it.
As another example, consider the template:
{Location}-{Country}-{State}-{City}-{Caption}
for a photo that has “Location” and “Caption”, but no “Country,” “City,” or “State.”. Assuming that location and caption are “Home” and “Having Fun” respectively, it becomes:
Home-Having Fun
which is better than it would be without these special rules:
Home----Having Fun
Note that space, comma, and hyphen/minus are only special when they're part of the template itself. When they are part of the value derived from a token (such as the space in “Having Fun” above), they are never considered for squelching.
As such, you can use either {-} or {"-"} to include a hyphen/minus that will never be squelched. Similarly, you can use {,} or {","} for a comma, and {" "} for a space.
Would love the possibility of adding a line break
I’m sorry for that question. Found out that I can use html in there. Very cute!
Hi Jeffrey! Thanks for adding this great feature. A suggestion for an alternate syntax, perhaps better than the squelching–
{City “-”}{State|Province}
Right now the braces enclose a single token. Extending that to a sequence would allow for more general squelching, such as
{”©” YYYY “.” |”Image is in the public domain.”}
or using HTML for line breaks:
{Title “”}{Location “” City|City}
(If any token in the sequence were empty, then the whole sequence would fail for the alternative.)
On a practical level, I found some parsing bugs in version 46 (Lightroom 1.4.1):
- {Rating} doesn’t seem to work — it parses it as “{Rating” and complains of a missing closing brace
- Squelching multiple joiners is broken, such as in this case if there is no “State”:
{City}, {State}, {Country}
Hope that helps!
Whoops, my second example should have been–
{Title “<br>}{Location “<br>” City|City}
I’m like Caroline at her first comment: I’d love to be able to add a line break, but can’t figure it out, even by experimenting some HTML here and there… What is the correct syntax?
Whether you can send HTML depends on the destination (e.g. Flickr, Zenfolio, etc.). The ones that I know allow HTML have an option nearby the preset pulldown that lets you choose whether the text you write should be interpreted as html or as plain text. The others, as far as I know, allow only plain text. (Let me know if I’ve made a mistake with one.) —Jeffrey
Using LR2 with the latest Flickr plugin. I’m getting two problems:
- The indicated line break doesn’t work
- I lost field customization. Even I update the preset, data is lost after restarting LR
Regards
I’m not sure what you mean by “indicated line break”, but about the preset data being lost, I’ve heard of that in one other case, and have no idea why it does that. Do presets for the standard export-to-disk export also reset, or is it limited to my plugins? —Jeffrey
Jefrey, thanks for the reply.
By “indicated line break” I refer to the requested/commented possibility to include a line break in the title or description preset. I’ve not been able to add.
Regarding to preset data being lost, I just updated to your latest version plugin. Now the preset is working as expected (preset template is not lost, and available every time). Looks it’s solved.
The tokens are a great aspect of your very useful Lightroom plugin. I would like to be able to use the same tokens in the tags for the photo, is that possible?
It’s on the to-do list…. —Jeffrey
Hello,
Thanks for your great plugins. I would like to know if there are/will be tokens for capture time and month of the year, I.E. Dec, December?
Thanks a bunch,
Gonzalo
Added in versions as of Aug 29. —Jeffrey
Hellow,
Awesome plugin. Many thanks. Not sure whether to post this here or in your Metadata Preset post…
Is it possible to include the plugin metadata from your Flicker plugin (’Uploaded to Flickr’ and ‘At Flickr’) in a custom metadata preset panel? I would love to include those in my custom preset. I am comfortable editing the preset file, just not sure of the values to include.
Thanks again for some AWESOME tools.
It’s on my (long) to-do list to update the metadata-preset-builder to allow this, but if you want to edit by hand, try info.regex.lightroom.export.flickr2.uploaded and info.regex.lightroom.export.flickr2.url —Jeffrey
This is brilliant, almost reason enough to upgrade to LR 2
However, I’m having a problem that I also had with previous versions - I simply can’t create empty titles!
Maybe this is a problem with the flickr api, but if a photo doesn’t have a suitable title, I like to use the empty string. I definitely don’t want the filename. I tried this template:
{Title|Headline|”"}
But according to the preview that seems to result in the filename. This one also:
{Title|Headline}
I found that the preview was correctly empty if I used
{Title|Headline|Empty}
but when the images were uploaded to flickr, they had the filename as their title. Is it possible to change this?
Thanks a bunch for giving out these great tools!
cheers,
Arnar
Is there a way to use templates in Flickr:Upload Destination to create a New Set? For e.g., I would like to use {Folder} for the “New set name”.
Thanks.
Yes, click on the “auto dests” button (”automatic destinations”) and create a destination that uses {Folder}. —Jeffrey
Very nice to be able to go beyond title and caption. Are more tokens in the works to be added for other camera EXIF data beyond Focal Length? Only personally interested in Exposure (w/aperture) and ISO Speed Rating, but others might want more.
I added a bunch of these today (Sep 14). —Jeffrey
Great plugin. I still cannot figure out however how to insert newline in Flickr caption. At the moment all I can do is enter one long string (BTW the ‘Description Presets’ popup window does try to resize to fit this long string and ends up being wider than my screen). What I would like to achieve is a nicely formatted block of text. My template is as follows
{City}, {Country} {Month} {YYYY} • {Copyright} • {CameraModel} • {Exposure}, ISO {ISO}, {ExposureBias}, {ExposureProgram}, {MeteringMode}, {Flash} • {Lens} @ {FocalLengthMM} • {Caption}
I would like to have a newline instead of • character. When I hit Enter key, the dialog window closes. Shif-Enter, Control-Enter does not work. Yet, when editing caption in Flickr, all I have to do is hit Enter key. Am I doing something wrong? Am I overlooking something simple? Please help.
This is a really really great feature. Thank you!
The new ability to use these tokens in the keyword tag section is brilliant.
I’d like to suggest two additional tokens:
1. Flag status (pick or reject)
2. Rating as a repeated sequence of characters, ideally user specified. E.g. if the rating is 3, the generated tag is •••
This would be useful in many contexts where search capabilities are limited, allowing the user to easily search for photos with n or more stars.
The flag status, unfortunately, is not available to the plugin, so I can’t add that. I’ve just pushed new versions with an enhanced Rating token that allows for what you want. —Jeffrey
Whenever I attempt to upload photos to Flickr, it never shows the Album names. As I cant choose an album, the upload always fails. In uploads to Zenfolio, it always shows them, and uploads are successful.
The DD token returns the day that the photo was pulled off the camera, not the actual day that the photo was taken. I confirmed this via the metadata information for the image.
Excellent plugin. The option to create sets dynamically based on folder name, exif data, etc and the ability to create tags from exif data are two things I’ve been searching for. As far as I know, you are the only person to have implemented such a feature, and I think you for adding it.
A couple small requests if you have time..
- At the moment YYYY MM DD SS are all possible, but no hours and minutes. Can this be added, along with JobCode?
- Fantastic to have ISO. For Aperture you currently have Aperture and ApertureNum. Could you do the same for ISO? Ie, so ISO would return ISO320, and ISONum would return just 320? I tried doing ISO{ISO} but in the case {ISO} is not available I am just left with the string ISO
- Fractions in ShutterSpeed do not display properly in flickr (at least for me), and ShutterSpeedNum has very long fractions in some cases - like 0.834289347289347. Could you perhaps add ShutterSpeedNum4 which would truncate to 4dp? or something similar
- Last but not least, Path seems to return a full path, etc “> Users > ABC > Dir1 > Dir2 ….” I tried to use the After option to remove the “> Users > ABC > ” part but it complains “Hierarchical structions not allowed with this plugin”. Can this be fixed?
- Finally, like many others I am trying to work out how to get a newline to appear in the flickr description. I tried the html for br, and backslash n, but to no joy.
Once again, thank you very much for your hard work on this plugin.
Are conditionals something that might be possible in a future version? For captioning on Flickr, I use the format Location | City, State in the Description field.
With this wonderfully, marvelous plugin, I can automate this by {Location} | {City}, {State} but the Location is somewhat optional for me so if the Location field isn’t filled out I get “| City, State” — note the meaningless pipe.
If I could do something like, oh, {if Location}{Location} |{/if}{City}, {State} that would be wonderful.
Thanks, so much, for this plugin.
Thank you very much. Fantastic plug-in. It would be awesome to have LR Collections. Is it anyway possible? Once again thank you!
Hi, love you plugins. Yet I miss one feature: parsing exif strings, since I don’t mind getting my hand dirty. For example, if you choose {CameraModel} I get NIKON D700. It would be nifty to just get D700.
While I’m at it, might is suggest a lowercase uppercase converter? You know, Nikon D700 instead of NIKON D700. If you ever make one, be sure to leave an option whether or not to leave the first letter of a word capital (eg. Canon Powershot 520).
Keep up the good work!
Hi Jeffrey, and thanx for the great tool. I have yet to upload my first pics to flickr though, because i’m still trying to figure out the newline thing. I’ve read all the posts, and like others I can’t get it to work.
Seems like we have to insert a somewhere, but where ? I tried differents things like
{CameraModel} {Lens}
{CameraModel } {Lens}
{CameraModel} “” {Lens}
… but none of those worked.
In one of your replies you’re mentionning an option to check, to interpret text as html, but I don’t know where to find that option. Is it on our flickr settings page ? In your plugin ?
Finally, if we manage to get it to work, will the preview display newlines (I tried exporting some pictures to double check that it wasn’t just a preview issue but same result) ?
Can somebody who know how to do this post a sample code ? And explain about the “interpret text as html” option ?
Thanx.