Creating Lightroom Web Gallery plugins

The basic reference is the Lightroom SDK Guide, Chapter 6. But the relevant section hasn't been updated since it was first written, and there's a lot missing. This forum could potentially be helpful but there isn't a lot about web plugins. There are also a LOT of quirks and bugs to workaround when creating lightroom galleries, and amazingly almost none of them are discussed on the net.

This is a very incomplete list of things I've encountered or learned:

• When debugging, changes to luascript (*.lrweb) only update reliably by restarting Lightroom. Errors therein typically cause the gallery to disappear from the list of galleries. Changes to the HTML template code itself are updated whenever you change any gallery setting that triggers a preview browser refresh (or by switching to Library view and back). Errors in this HTML syntax typically (but not reliably) cause a web page showing an error message to appear. Sometimes things will just inexplicably not work.
• New or modified broken web galleries and web templates will only appear after LR restart.
• If you use manifest.lrweb's AddResources to actually move the files (ie, its purpose: the source and destination differ), then most if not all the resources will not be available when rendering the preview. One workaround is to then explicitly AddResource or AddPage for each file that's actually used in the preview. But this has problems too. I wound up using AddResources with the same source and destination directories.
• It's important that your pages (referenced in e.g. AddPage() or AddGridPages())  NOT be in your source directory for AddResources. They may however both have the same destination directories.
• In Windows, Lightroom 4 appears to use an internet explorer 6 or 7 rendering engine for the internal preview web page, so sadly this needs to be a target of your gallery. Debugging it in IE 7 (or at least a later version running with F12 compatibility mode for IE 7) is helpful to get it working in the preview mode (since I haven't figured out any facilities for debugging the actual preview album within lightroom). Not sure about other versions of LR or on a Mac.
• Correction: It turns out Lightroom 4 is actually using a modified build of the webkit library used by Safari 4.0.3 (released in August 2009) - the user agent string is "Mozilla/5.0 (Windows; U; en-US) AppleWebKit/531.9 (KHTML, like Gecko) AdobeAIR/2.7.1". Which is also seriously old too, but at least you can download it and test with this old Safari version outside lightroom, which I highly recommend if you're having trouble.
• There is a maximum of one level of indirection when referencing variables in galleryinfo.lrweb. E.g., if you want variable A to depend upon the value of another (using the function() syntax) and others to depend upon variable A, it's not possible.
• Variables names like "nonCSS.text.name" are actually twice-nested lua tables. Hyphens are not allowed in such names (are you subtracting?). To workaround this, you can express it as such: nonCSS.text["hyphenated-name"].
• Typical methods of debugging the lightroom preview webpage are unavailable (alerts, console logs, inspecting the dom, etc). live_update.js provides an AgDebugPrint() function, but I have no idea how or if it's possible to see output from this call. But one thing you can do is make a "debug" div and insert things into the content of that div to be displayed on page. Primitive, but helpful - I wish I'd thought of it sooner.
• Also, lightroom puts the preview album in the temporary folder named AgWPGPreview-### (eg, C:\Users\username\AppData\Local\Temp\AgWPGPreview-21). Inspecting the files here can tip you off about what may be going wrong when viewing inside LR (note that the images are not written here, or at least not named as you'd expect).
• Of course, it's useful to export the gallery and use typical browser debugging tools as well.
• If you want to support live update, you need to set the variable supportsLiveUpdate = true in galleryinfo.lrweb. This is unmentioned in all documentation. For debugging it's best to turn off to ensure things update as mentioned above. live_update.js calls methods under the variable 'myCallback', but checking for this variable's existence fails and causes live_update to bonk, even under lightroom preview. That means we can't check, so the code will give errors outside the preview (if testing- it shouldn't be included in the export anyway).
• For every metadata item you'd like to use for images (eg, title or gps location), you need to include them in a perImageSetting. These then need to be provided in the properties, perImage field of the GUI to be actually provided (it would also work if you don't provide a properties block, but then these settings will appear in random order on the GUI). Useful ones include com.adobe.X where X can be: caption, title, location (which is actually sublocation), city, state, country, GPS, and many more (all undocumented). If you name it as perImageSetting.title, it will be available under the image's metadata.title field in LuaPages. A longer list of properties is here.
• Luascript in LuaPages can be really tough to debug. I now do one small change at a time and check for failures by reloading the preview window and checking the generated preview html. One thing to note is that there seems to be only one pass-through by the interpreter and thus functions must be defined before they are used.
• If in your LuaPages you have long sections of html/javascript/etc with no luascript elements, then you may get the error "chunk has too many syntax levels". You can cure it by placing luascript comments e.g., <% --[[ Comment here ]] %> to break up the offending section.
• When making Lightroom UI elements with titles, you can use "\n" to break up long lines in the text. But, if you use the LOC function to localize the text and use other languages, there does not appear to be any way to break up lines. Thus other languages must fit on one line.
• Variables starting with "appearance." have magic powers in that they trigger a request to update the appearance of the webpage in the UI; other variables won't trigger refresh. Lightroom sends such changes to the web page's document.liveUpdate() function to determine how much of the page needs to be regenerated. I found that the return value "invalidateOldHTML" is almost always what I needed, and so I replaced the provided function to always return this (YMMV). Variables starting with "metadata" will be treated as text and remove any potential html tags. It also updates like those with "appearance".

Please share any more that you know about and/or know how to work around. Or if you're stuck and need a hand, perhaps it's something I've encountered. Ask in the comments.