File ExportFilter.lua

Functions

ExportFilter._getFilterName (id) Compute filter name based on ID - MUST be same as extended filter class name.
ExportFilter._getPropName (filterName, pqName) Get filter-specific property name, without having filter object.
ExportFilter.assureFilter (id, props, starter) Create export filter for either dialog or filter-context, and store in property table.
ExportFilter.postProcessRenderedPhotos (functionContext, filterContext) Post process rendered photos.
ExportFilter.sectionForFilterInDialog (vf, propertyTable) This function will create the section displayed on the export dialog when this filter is added to the export session.
ExportFilter.shouldRenderPhoto (exportSettings, photo) This function obtains access to the photos and removes entries that don't match the metadata filter.
ExportFilter.startDialog (propertyTable) This optional function adds the observers for our required fields metachoice and metavalue so we can change the dialog depending if they have been populated.
ExportFilter.updateFilterStatus (extendedExportFilterClass, props, name, value) This function will check the status of the Export Dialog to determine if all required fields have been populated.
ExportFilter:allowExport (message, ...) Sets boolean status property to true (no problem detected), and status message as passed or generic "ok", - export may be enabled if no other filters from this plugin have denied.
ExportFilter:cancelExport (autoLog) Abort/cancel the export.
ExportFilter:clearExportCondition () Clears export condition, *if* no other filters in this plugin have denied it.
ExportFilter:denyExport (reason, ...) Sets boolean status property to false (denied), and (always) sets status message to 'reason', thus disabling export.
ExportFilter:getFilters () Get "pseudo-array" of filters, plus indexes of first and last, plus total from this plugin (and names).
ExportFilter:getPropName (namePart) Get property name as combination of partially qualified name, and filter name.
ExportFilter:getSectionTitle () Get section-in-dialog title, prefixed by app-name if >1 filter in plugin.
ExportFilter:new (t) Constructor for new instance (may serve dialog box only, or actual export filtering - which one depends on whether filter-context is passed in starter table.
ExportFilter:newClass (t) Constructor for extending class.
ExportFilter:passRenditionsThrough (errm) No-op (call from post-process-rendered-photos method if, for example, filter doesn't meet criteria for doing it's thing...).
ExportFilter:peruseRenditions (params) Peruse renditions and return photo/video tables, candidate renditions, metadata cache.
ExportFilter:postProcessRenderedPhotosFinale (call) Generic finale method for photo processing method - assures exiftool session is closed (if assigned to standard member), and shows dialog box if problem,
since there will be no error box shown if foreign export service.
ExportFilter:processRenderedPhotosMethod () Process rendered photos method.
ExportFilter:requireFilter (requiredFilterId, dependentFilterId) Assures export filter position within this plugin.
ExportFilter:requireFilterInDialog (id, nameOrTitle) Called from update-filter-status method, to ensure main filter.
ExportFilter:requireFilterInPost (id, nameOrTitle) Assure pre-requisite filter is (still) there.
ExportFilter:sectionForFilterInDialogFinale (call) Generic finale method if section method is wrapped - override, ignore, or use as is..
ExportFilter:sectionForFilterInDialogGetStatusView (lines) Get view object which presents labeled status, typically at bottom of section.
ExportFilter:sectionForFilterInDialogMethod () return section for filter setup
ExportFilter:shouldRenderPhotoMethod (photo) Determine if photo should pass go or not.
ExportFilter:updateFilterStatusMethod (name, value) Export setting property change handler - note: usually should be programmed to handle case when no name/value has been passed too, to check initial values even if nothing's changed yet.
ExportFilter:updateSynopsis () Update synopsis


Functions

ExportFilter._getFilterName (id)
Compute filter name based on ID - MUST be same as extended filter class name.

Parameters:

  • id:

Usage:

    this function assumes id format "{whatev}.{class-name}" 
    in other words, id will end with the name of the implementing class.
    if you prefer another naming convention, override this method, but realize the class name must be *somewhere* (verbatim) in the ID, or else you'll have to override constructor too (and maybe some other methods).
ExportFilter._getPropName (filterName, pqName)
Get filter-specific property name, without having filter object.

Parameters:

  • filterName:
  • pqName:

Usage:

    this function is implemented as a local function instead of an overridable class function because it's important that all filters 
    in a plugin are having status property name computed the same way, regardless of their class heritage.
ExportFilter.assureFilter (id, props, starter)
Create export filter for either dialog or filter-context, and store in property table.

Parameters:

  • id: (class, required) class of export filter object to be created, if creation is warranted (i.e. not already created with specified export settings & filter-context...).
  • props: (export setttings in the form of an observable property table) required if no filter-context in starter table.
  • starter: (table) optional: typically includes function-context & filter-context in case object is for export-run time (as opposed to dialog-box/set-up time).

Usage:

  • in export class, registry is static array in base class, and object is cleaned up upon completion.
  • export filter registry is export properties themselves, and new objects replace old objects - note: there is no explicit cleanup, cleanup relies on "fact" that Lr will create new properties object at export time, and thus all previously registered filter objects will be wiped.
  • props are used as "registry" for constructed export filter object. Maybe not by the book, but no problems, yet.. - the advantage is that they are recreated by Lightroom each dialog-box/export, thus no explicit cleanup need be implemented. 
ExportFilter.postProcessRenderedPhotos (functionContext, filterContext)
Post process rendered photos.

Parameters:

  • functionContext:
  • filterContext:

Usage:

    override this function, or set it to nil. 
ExportFilter.sectionForFilterInDialog (vf, propertyTable)
This function will create the section displayed on the export dialog when this filter is added to the export session.

Parameters:

  • vf:
  • propertyTable:

Usage:

    generally should be overridden, unless you just want the generic "nuthin' to see here" text where settings would otherwise be. 
ExportFilter.shouldRenderPhoto (exportSettings, photo)
This function obtains access to the photos and removes entries that don't match the metadata filter.

Parameters:

  • exportSettings:
  • photo:

Usage:

    Worth noting: there is *no* filter-context at this stage, nor export session, nor export context... 
ExportFilter.startDialog (propertyTable)
This optional function adds the observers for our required fields metachoice and metavalue so we can change the dialog depending if they have been populated.

Parameters:

  • propertyTable:

Usage:

    generally should be overridden. 
ExportFilter.updateFilterStatus (extendedExportFilterClass, props, name, value)
This function will check the status of the Export Dialog to determine if all required fields have been populated.

Parameters:

  • extendedExportFilterClass: (ExportFilter derivative, required) must be the class of extended export filter.
  • props: (prop-table) are common to all filters.
  • name: (string, optional) property table *key* (include 'LR_' prefix, or not, as appropriate). pass name if called due to property change, otherwise may be nil for generic update.
  • value: (any, optional) value correpsonding to name - makes no sense to pass if no name.

Usage:

    this function need not be overridden by base classes, as long as the ID in the observer is the extended class. 
ExportFilter:allowExport (message, ...)
Sets boolean status property to true (no problem detected), and status message as passed or generic "ok", - export may be enabled if no other filters from this plugin have denied.

Parameters:

  • message:
  • ...:
ExportFilter:cancelExport (autoLog)
Abort/cancel the export.

Parameters:

  • autoLog:

Usage:

  • Must be called before rendering has started.
  • Best practice: log warning or error before calling this, but note - *** Log file may be suppressed if 'Reload After Export' is enabled in plugin manager. 

Return values:

  1. status (boolean) true iff all renditions skipped.
  2. message (string) explains false status.
ExportFilter:clearExportCondition ()
Clears export condition, *if* no other filters in this plugin have denied it.

Usage:

    Lr itself keeps track of which plugins have set it, but NOT individual filters within a plugin - yeah: oops (Adobe). 
    it is for this reason the common status property was set up - universal for all plugin filters.
ExportFilter:denyExport (reason, ...)
Sets boolean status property to false (denied), and (always) sets status message to 'reason', thus disabling export.

Parameters:

  • reason:
  • ...:
ExportFilter:getFilters ()
Get "pseudo-array" of filters, plus indexes of first and last, plus total from this plugin (and names).

Usage:

  • Do NOT traverse filters using ipairs, since first entries may be nil (ipairs quits on a nil).
  • You *can* traverse names array using ipairs, and index filters in loop body..
  • *** last may be greater than total (but will never be less).
  • There are no settings from other plugins in here, nor are they in list of export filters... 
    such settings influence exporting, but are managed by Lightroom. No doubt the reason we can't initiate exports on the fly which include filters from other plugins.

Return values:

  1. filters (pseudo-array) aka "sparse" array, of filter IDs.
  2. first (numeric) index - can be used to index filters or names.
  3. last (numeric) index - can be used to index filters or names.
  4. total (numeric) number of export filters from this plugin.
  5. names (array) array of partially-qualified export filter names (not sparse), values include "other/unknown" entry if not from this plugin.
ExportFilter:getPropName (namePart)
Get property name as combination of partially qualified name, and filter name. Thus, each like property will be unique and determinate when multiple filters.

Parameters:

  • namePart:
ExportFilter:getSectionTitle ()
Get section-in-dialog title, prefixed by app-name if >1 filter in plugin.

Usage:

    one can always override this.. 
ExportFilter:new (t)
Constructor for new instance (may serve dialog box only, or actual export filtering - which one depends on whether filter-context is passed in starter table.

Parameters:

  • t:

Usage:

  • @19/Nov/2013 16:48, "extension" of ID must match class name. - this is not strictly necessary, but more of a sanity check - if too inflexible, delete the assertion (not tested). 
    in any case, class-name will need to be found as part of the ID, and had better be unique.
  • exportSettings or filterContext must be passed.
  • class name must be unique - NOT checked. 
ExportFilter:newClass (t)
Constructor for extending class.

Parameters:

  • t:
ExportFilter:passRenditionsThrough (errm)
No-op (call from post-process-rendered-photos method if, for example, filter doesn't meet criteria for doing it's thing...).

Parameters:

  • errm:

Usage:

    - my experience: if post-process-rendered-photos function is defined, it will be called, and expected to operate. This method is therefore necessary to keep the ball rolling. 
ExportFilter:peruseRenditions (params)
Peruse renditions and return photo/video tables, candidate renditions, metadata cache.

Parameters:

  • params: (table) named parameters.
    rawIds (array, optional) raw ids for metadata cache, if desired.
    fmtIds (array, optional) fmt ids for metadata cache, if desired.
    call (object, required) calling context call object.

Return values:

  1. photos (array) of photos - may be empty, but never nil.
  2. videos (array) of videos - may be empty, but never nil.
  3. union (array) of photos & videos - may be empty, but never nil.
  4. unionCache (Cache) containing specified metadata for photos & videos - may be empty, but never nil.
  5. candidates (array) candidate renditions. It's possible to pare down candidates depending on filter - thus the name.
ExportFilter:postProcessRenderedPhotosFinale (call)
Generic finale method for photo processing method - assures exiftool session is closed (if assigned to standard member), and shows dialog box if problem,
since there will be no error box shown if foreign export service.

Parameters:

  • call:
ExportFilter:processRenderedPhotosMethod ()
Process rendered photos method.

Usage:

    ordinarily, derived type would override this method, but maybe not.. 
ExportFilter:requireFilter (requiredFilterId, dependentFilterId)
Assures export filter position within this plugin.

Parameters:

  • requiredFilterId:
  • dependentFilterId:

Usage:

    can not assure position w.r.t. export filters of other plugins. 

Return values:

  1. status (boolean) true iff top/bottom filter, as desired.
  2. lastId (string) ID of top/bottom filter, if not as desired.
ExportFilter:requireFilterInDialog (id, nameOrTitle)
Called from update-filter-status method, to ensure main filter.

Parameters:

  • id:
  • nameOrTitle:

Usage:

    preferrably called in edb when LR-export-filters.. changes, since that catches it at earliest point, 
    on the down side, if multiple filters are present, you have to set through the prompt multiple times. - oh well, user shouldn't make that mistake more than once or twice..
ExportFilter:requireFilterInPost (id, nameOrTitle)
Assure pre-requisite filter is (still) there.

Parameters:

  • id: (string, optional) If not passed, name/title will be the extension of the ID.
  • nameOrTitle:

Usage:

    call in post-process photos method. 
ExportFilter:sectionForFilterInDialogFinale (call)
Generic finale method if section method is wrapped - override, ignore, or use as is..

Parameters:

  • call:
ExportFilter:sectionForFilterInDialogGetStatusView (lines)
Get view object which presents labeled status, typically at bottom of section.

Parameters:

  • lines:
ExportFilter:sectionForFilterInDialogMethod ()
return section for filter setup

Usage:

    typically overridden. 
ExportFilter:shouldRenderPhotoMethod (photo)
Determine if photo should pass go or not.

Parameters:

  • photo:

Usage:

  • if no-go, then it will be *silently* omitted, so if you want to make a fuss, it costs extra..
  • extras you may want to consider: file-format (consider video), virtual-copy, filename extension, smart preview, original source online/offline.. 
ExportFilter:updateFilterStatusMethod (name, value)
Export setting property change handler - note: usually should be programmed to handle case when no name/value has been passed too, to check initial values even if nothing's changed yet.
Reminder: initial values may have come from an old (or hand-edited) preset, so all bets are off.

Parameters:

  • name:
  • value:
ExportFilter:updateSynopsis ()
Update synopsis

Usage:

    Default implementation here assumes enable/disable & status - override to customize.. 

Valid XHTML 1.0!