Plug-in provided SDK - Publish service provider

Summary

Functions

publishServiceProvider.addCommentToPublishedPhoto( publishSettings, remotePhotoId, commentText )

(optional) This plug-in defined callback function is called when the user adds a new comment to a published photo in the Library module's Comments panel. Your implementation should publish the comment to the service.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. remotePhotoId

(string or number) The remote ID of the photo as previously assigned via a call to exportRendition:recordRemotePhotoId().

3. commentText

(string) The text of the new comment.

Return value

(Boolean) True if comment was successfully added to service.

publishServiceProvider.canAddCommentsToService( publishSettings )

(optional) This plug-in defined callback function is called whenever a published photo is selected in the Library module. Your implementation should return true if there is a viable connection to the publish service and comments can be added at this time. If this function is not implemented, the new comment section of the Comments panel in the Library is left enabled at all times for photos published by this service. If you implement this function, it allows you to disable the Comments panel temporarily if, for example, the connection to your server is down.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

Return value

(Boolean) True if comments can be added at this time.

publishServiceProvider.deleteFirstOnPublish()

This (optional) plug-in defined callback function is called when publishing has been initiated, and should simply return true or false to indicate whether any deletion of photos from the service should take place before any publishing of new images and updating of previously published images. The default behavior is to perform the deletion of images which have been removed from the published collection in Lightroom as the last step in a publishing operation, but this callback allows the plug-in to alter the timing of the deletion in cases where that is desirable.

First supported in version 4.0 of the Lightroom SDK.

publishServiceProvider.deletePhotosFromPublishedCollection( publishSettings, arrayOfPhotoIds, deletedCallback, localCollectionId )

This plug-in defined callback function is called when one or more photos have been removed from a published collection and need to be removed from the service. If the service you are supporting allows photos to be deleted via its API, you should do that from this function.

As each photo is deleted, you should call the deletedCallback function to inform Lightroom that the deletion was successful. This will cause Lightroom to remove the photo from the "Delete Photos to Remove" group in the Library grid.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. arrayOfPhotoIds

(table) The remote photo IDs that were declared by this plug-in when they were published.

3. deletedCallback

(function) This function must be called for each photo ID as soon as the deletion is confirmed by the remote service. It takes a single argument: the photo ID from the arrayOfPhotoIds array.

4. localCollectionId

(number) The local identifier for the collection for which photos are being removed.

publishServiceProvider.deletePublishedCollection( publishSettings, info )

This plug-in callback function is called when the user has deleted a published collection via the Publish Services panel user interface. This is your plug-in's opportunity to make the corresponding change on the service. (Note that this callback function is only invoked when the user clicks the 'Delete' button in the dialog which Lightroom presents to alert the user of what happens to photos which have been published via this published collection. If the user chooses to leave the photos in their published location, the function is not called.)

If your plug-in is unable to update the remote service for any reason, you should throw a Lua error from this function via error() or a related built-in function. This causes Lightroom to present a dialog asking the user whether to revert the change, or proceed with the change locally while informing the user this will leave the equivalent collection unaltered on the remote service.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. info

(table) A table with these fields:

• isDefaultCollection: (Boolean) True if this is the default collection.
• name: (string) The new name being assigned to this collection.
• parents: (table) An array of information about parents of this collection, in which each element contains:
  • localCollectionId: (number) The local collection ID.
  • name: (string) Name of the collection set.
  • remoteCollectionId: (number or string) The remote collection ID assigned by the server.
• publishService: (LrPublishService) The publish service object.
• publishedCollection: (LrPublishedCollection or LrPublishedCollectionSet) The published collection object being renamed.
• remoteId: (string or number) The ID for this published collection that was stored via exportSession:recordRemoteCollectionId
• remoteUrl: (optional, string) The URL, if any, that was recorded for the published collection via exportSession:recordRemoteCollectionUrl.

publishServiceProvider.didCreateNewPublishService( publishSettings, info )

(optional) This plug-in defined callback function is called when the user creates a new publish service via the Publish Manager dialog. It allows your plug-in to perform additional initialization.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. info

(table) A table with these fields:

• connectionName: (string) the name of the newly-created service
• publishService: (LrPublishService) The publish service object.

publishServiceProvider.didUpdatePublishService( publishSettings, info )

(optional) This plug-in defined callback function is called when the user creates a new publish service via the Publish Manager dialog. It allows your plug-in to perform additional initialization.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. info

(table) A table with these fields:

• connectionName: (string) the name of the newly-created service
• nPublishedPhotos: (number) how many photos are currently published on the service
• publishService: (LrPublishService) The publish service object.
• changedMoreThanName: (boolean) true if any setting other than the name (description) has changed

publishServiceProvider.endDialogForCollectionSetSettings( publishSettings, info )

(optional) This plug-in defined callback function is called when the user closes the dialog for creating a new published collection set or editing an existing one. It is only called if you have also provided the viewForCollectionSetSettings callback, and is your opportunity to clean up any tasks or processes you may have started while the dialog was running.

This is a blocking call. If you need to start a long-running task (such as network access), create a task using the LrTasks namespace.

Your code should not update the server from here. That should be done via the updateCollectionSetSettings callback. (If, for instance, the settings changes are later undone; this callback will not be called again; updateCollectionSetSettings will be.)

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. info

(table) A table with these fields:

• collectionSettings: (LrObservableTable) plug-in specific settings for this collection set. The settings in this table are not interpreted by Lightroom in any way, except that they are stored with the collection set. These settings can be accessed via LrPublishedCollectionSet:getCollectionSetInfoSummary. The values in this table must be numbers, strings, or Booleans.
• collectionType: (string) "collectionSet"
• isDefaultCollection: (boolean) true if this is the default collection (will always be false)
• name: (string) If the dialog was canceled, the name of the collection (or collection set) which was selected when the create or edit operation was initiated. If no published collection or collection set was selected, the name of the publish service it belongs to. If the dialog was dismissed with Edit or Create, the name of the collection set when the dialog was dismissed.
• parents: (table) An array of information about parents of this collection, in which each element contains:
  • localCollectionId: (number) The local collection ID.
  • name: (string) Name of the collection set.
  • remoteCollectionId: (number or string) The remote collection ID assigned by the server.
  This field is only present when editing an existing published collection set.
• pluginContext: (LrObservableTable) This is a place for your plug-in to store transient state while the collection set settings dialog is running. It will be passed to your plug-in during the endDialogForCollectionSettings and then discarded.
• publishedCollectionSet: (LrPublishedCollectionSet) The published collection set object being edited.
• publishService: (LrPublishService) The publish service object.
• why: (string) Why the dialog was closed. Either "ok" or "cancel".

publishServiceProvider.endDialogForCollectionSettings( publishSettings, info )

(optional) This plug-in defined callback function is called when the user closes the dialog for creating a new published collection or editing an existing one. It is only called if you have also provided the viewForCollectionSettings callback, and is your opportunity to clean up any tasks or processes you may have started while the dialog was running.

This is a blocking call. If you need to start a long-running task (such as network access), create a task using the LrTasks namespace.

Your code should not update the server from here. That should be done via the updateCollectionSettings callback. (If, for instance, the settings changes are later undone; this callback is not called again, but updateCollectionSettings is.)

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. info

(table) A table with these fields:

• collectionSettings: (LrObservableTable) Plug-in specific settings for this collection. The settings in this table are not interpreted by Lightroom in any way, except that they are stored with the collection. These settings can be accessed via LrPublishedCollection:getCollectionInfoSummary. The values in this table must be numbers, strings, or Booleans.
• collectionType: (string) Either "collection" or "smartCollection"
• isDefaultCollection: (Boolean) True if this is the default collection.
• name: (string) If the dialog was canceled, the name of the collection (or collection set) which was selected when the create or edit operation was initiated. If no published collection or collection set was selected, the name of the publish service it belongs to. If the dialog was dismissed with Edit or Create, the name of the collection when the dialog was dismissed.
• parents: (table) An array of information about parents of this collection, in which each element contains:
  • localCollectionId: (number) The local collection ID.
  • name: (string) Name of the collection set.
  • remoteCollectionId: (number or string) The remote collection ID assigned by the server.
  This field is only present when editing an existing published collection.
• pluginContext: (LrObservableTable) This is a place for your plug-in to store transient state while the collection settings dialog is running. It is passed to your plug-in's endDialogForCollectionSettings callback, and then discarded.
• publishedCollection: (LrPublishedCollection) The published collection object being edited.
• publishService: (LrPublishService) The publish service object to which this collection belongs.
• why: (string) The button that was used to close the dialog, one of "ok" or "cancel".

publishServiceProvider.getCollectionBehaviorInfo( publishSettings )

(optional) If you provide this plug-in defined callback function, Lightroom calls it to retrieve the default collection behavior for this publish service, then use that information to create a built-in default collection for this service (if one does not yet exist). This special collection is marked in italics and always listed at the top of the list of published collections.

This callback should return a table that configures the default collection. The elements of the configuration table are optional, and default as shown.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

Return value

(table) A table with the following fields:

• defaultCollectionName: (string) The name for the default collection. If not specified, the name is "untitled" (or a language-appropriate equivalent).
• defaultCollectionCanBeDeleted: (Boolean) True to allow the user to delete the default collection. Default is true.
• canAddCollection: (Boolean) True to allow the user to add collections through the UI. Default is true.
• maxCollectionSetDepth: (number) A maximum depth to which collection sets can be nested, or zero to disallow collection sets. If not specified, unlimited nesting is allowed.

publishServiceProvider.getCommentsFromPublishedCollection( publishSettings, arrayOfPhotoInfo, commentCallback )

(optional) This plug-in defined callback function is called (if supplied) to retrieve comments from the remote service, for a single collection of photos that have been published through this service. This function is called:

• For every photo in the published collection each time any photo in the collection is published or re-published.
• When the user clicks the Refresh button in the Library module's Comments panel.
• After the user adds a new comment to a photo in the Library module's Comments panel.

This function is not called for unpublished photos or collections that do not contain any published photos.

The body of this function should have a loop that looks like this:

 function publishServiceProvider.getCommentsFromPublishedCollection( settings, arrayOfPhotoInfo, commentCallback )
 
     for i, photoInfo in ipairs( arrayOfPhotoInfo ) do
 
         -- Get comments from service.
 
         local comments = (depends on your plug-in's service)
 
         -- Convert comments to Lightroom's format.
 
         local commentList = {}
         for i, comment in ipairs( comments ) do
             table.insert( commentList, {
                 commentId = (comment ID, if any, from service),
                 commentText = (text of user comment),
                 dateCreated = (date comment was created, if available; Cocoa date format),
                 username = (user ID, if any, from service),
                 realname = (user's actual name, if available),
             } )
 
         end
 
         -- Call Lightroom's callback function to register comments.
 
         commentCallback { publishedPhoto = photoInfo, comments = commentList }
 
     end
 
 end 

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. arrayOfPhotoInfo

(table) An array of tables with a member table for each photo. Each member table has these fields:

• photo: (LrPhoto) The photo object.
• publishedPhoto: (LrPublishedPhoto) The publishing data for that photo.
• remoteId: (string or number) The remote systems unique identifier for the photo, as previously recorded by the plug-in.
• url: (string, optional) The URL for the photo, as assigned by the remote service and previously recorded by the plug-in.
• commentCount: (number) The number of existing comments for this photo in Lightroom's catalog database.

3. commentCallback

(function) A callback function that your implementation should call to record new comments for each photo; see example.

publishServiceProvider.getRatingsFromPublishedCollection( publishSettings, arrayOfPhotoInfo, ratingCallback )

(optional) This plug-in defined callback function is called (if supplied) to retrieve ratings from the remote service, for a single collection of photos that have been published through this service. This function is called:

• For every photo in the published collection each time any photo in the collection is published or re-published.
• When the user clicks the Refresh button in the Library module's Comments panel.
• After the user adds a new comment to a photo in the Library module's Comments panel.

The body of this function should have a loop that looks like this:

 function publishServiceProvider.getRatingsFromPublishedCollection( settings, arrayOfPhotoInfo, ratingCallback )
 
     for i, photoInfo in ipairs( arrayOfPhotoInfo ) do
 
         -- Get ratings from service.
 
         local ratings = (depends on your plug-in's service)
             -- WARNING: The value for ratings must be a single number.
             -- This number is displayed in the Comments panel, but is not
             -- otherwise parsed by Lightroom.
 
         -- Call Lightroom's callback function to register rating.
 
         ratingCallback { publishedPhoto = photoInfo, rating = rating }
 
     end
 
 end 

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. arrayOfPhotoInfo

(table) An array of tables with a member table for each photo. Each member table has these fields:

• photo: (LrPhoto) The photo object.
• publishedPhoto: (LrPublishedPhoto) The publishing data for that photo.
• remoteId: (string or number) The remote systems unique identifier for the photo, as previously recorded by the plug-in.
• url: (string, optional) The URL for the photo, as assigned by the remote service and previously recorded by the plug-in.

3. ratingCallback

(function) A callback function that your implementation should call to record new ratings for each photo; see example.

publishServiceProvider.goToPublishedCollection( publishSettings, info )

(optional) This plug-in defined callback function is called when the user chooses the "Go to Published Collection" context-menu item.

If this function is not provided, Lightroom uses the URL recorded for the published collection via exportSession:recordRemoteCollectionUrl.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. info

(table) A table with these fields:

• publishedCollection: (LrPublishedCollection) The published collection object.
• publishedCollectionInfo: A table containing publication information for this published collection.
  • isDefaultCollection: (boolean) true if this is the default collection (will always be false)
  • name: (string) the name of this collection set
  • parents: (table) array of information about parents of this collection set; each element of the array will contain:
    • localCollectionId: (number) local collection ID
    • name: (string) name of the collection set
    • remoteCollectionId: (number of string) remote collection ID
• publishService: (LrPublishService) The publish service to which this collection belongs.
• remoteId: (string or number) The ID for this published collection that was stored via exportSession:recordRemoteCollectionId
• remoteUrl: (optional, string) The URL, if any, that was recorded for the published collection via exportSession:recordRemoteCollectionUrl.

publishServiceProvider.goToPublishedPhoto( publishSettings, info )

(optional) This plug-in defined callback function is called when the user chooses the "Go to Published Photo" context-menu item.

If this function is not provided, Lightroom invokes the URL recorded for the published photo via exportRendition:recordPublishedPhotoUrl.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. info

(table) A table with these fields:

• publishedCollectionInfo: A table containing publication information for this published collection.
  • isDefaultCollection: (boolean) true if this is the default collection (will always be false)
  • name: (string) the name of this collection set
  • parents: (table) array of information about parents of this collection set; each element of the array will contain:
    • localCollectionId: (number) local collection ID
    • name: (string) name of the collection set
    • remoteCollectionId: (number of string) remote collection ID
• photo: (LrPhoto) The photo object.
• publishService: (LrPublishService) The publish service to which this collection belongs.
• publishedPhoto: (LrPublishedPhoto) The object that contains information previously recorded about this photo's publication.
• remoteId: (string or number) The ID for this published photo that was stored via exportRendition:recordPublishedPhotoId
• remoteUrl: (optional, string) The URL, if any, that was recorded for the published photo via exportRendition:recordPublishedPhotoUrl.

publishServiceProvider.imposeSortOrderOnPublishedCollection( publishSettings, info, remoteIdSequence )

(optional) This plug-in defined callback function is called after each time that photos are published via this service assuming the published collection is set to "User Order." Your plug-in should ensure that the photos are displayed in the designated sequence on the service.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. info

(table) A table with these fields:

• collectionSettings: (LrObservableTable) plug-in specific settings for this collection set. The settings in this table are not interpreted by Lightroom in any way, except that they are stored with the collection set. These settings can be accessed via LrPublishedCollectionSet:getCollectionSetInfoSummary. The values in this table must be numbers, strings, or Booleans.
• isDefaultCollection: (boolean) true if this is the default collection (will always be false)
• name: (string) the name of this collection set
• parents: (table) array of information about parents of this collection set; each element of the array will contain:
  • localCollectionId: (number) local collection ID
  • name: (string) name of the collection set
  • remoteCollectionId: (number of string) remote collection ID
• remoteCollectionId: (string or number) The ID for this published collection that was stored via exportSession:recordRemoteCollectionId
• publishedUrl: (optional, string) The URL, if any, that was recorded for the published collection via exportSession:recordRemoteCollectionUrl.

3. remoteIdSequence

(array of string or number) The IDs for each published photo that was stored via exportRendition:recordPublishedPhotoId

Return value

(boolean) true to reverse the sequence when publishing new photos

publishServiceProvider.metadataThatTriggersRepublish( publishSettings )

(optional) This plug-in defined callback function is called whenever a new publish service is created and whenever the settings for a publish service are changed. It allows the plug-in to specify which metadata should be considered when Lightroom determines whether an existing photo should be moved to the "Modified Photos to Re-Publish" status.

This is a blocking call.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

Return value

(table) A table containing one or more of the following elements as key, Boolean true or false as a value, where true means that a change to the value does trigger republish status, and false means changes to the value are ignored:

• default: All built-in metadata that appears in XMP for the file. You can override this default behavior by explicitly naming any of these specific fields:
  • rating
  • label
  • title
  • caption
  • gps
  • gpsAltitude
  • creator
  • creatorJobTitle
  • creatorAddress
  • creatorCity
  • creatorStateProvince
  • creatorPostalCode
  • creatorCountry
  • creatorPhone
  • creatorEmail
  • creatorUrl
  • headline
  • iptcSubjectCode
  • descriptionWriter
  • iptcCategory
  • iptcOtherCategories
  • dateCreated
  • intellectualGenre
  • scene
  • location
  • city
  • stateProvince
  • country
  • isoCountryCode
  • jobIdentifier
  • instructions
  • provider
  • source
  • copyright
  • rightsUsageTerms
  • copyrightInfoUrl
  • copyrightStatus
  • keywords (Applies to keywords marked for inclusion on export only.)
• customMetadata: All plug-in defined custom metadata (defined by any plug-in).
• (plug-in ID).*: All custom metadata defined by the plug-in with the specified ID.
• (plug-in ID).(field ID): One specific custom metadata field defined by the plug-in with the specified ID.

publishServiceProvider.renamePublishedCollection( publishSettings, info )

This plug-in callback function is called when the user has renamed a published collection via the Publish Services panel user interface. This is your plug-in's opportunity to make the corresponding change on the service.

If your plug-in is unable to update the remote service for any reason, you should throw a Lua error from this function via error() or a related built-in function. This causes Lightroom to present a dialog asking the user whether to revert the change, or proceed with the change locally while informing the user this will leave the equivalent collection unaltered on the remote service.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. info

(table) A table with these fields:

• isDefaultCollection: (Boolean) True if this is the default collection.
• name: (string) The new name being assigned to this collection.
• parents: (table) An array of information about parents of this collection, in which each element contains:
  • localCollectionId: (number) The local collection ID.
  • name: (string) Name of the collection set.
  • remoteCollectionId: (number or string) The remote collection ID assigned by the server.
• publishService: (LrPublishService) The publish service object.
• publishedCollection: (LrPublishedCollection or LrPublishedCollectionSet) The published collection object being renamed.
• remoteId: (string or number) The ID for this published collection that was stored via exportSession:recordRemoteCollectionId
• remoteUrl: (optional, string) The URL, if any, that was recorded for the published collection via exportSession:recordRemoteCollectionUrl.

publishServiceProvider.reparentPublishedCollection( publishSettings, info )

This plug-in callback function is called when the user has reparented a published collection via the Publish Services panel user interface. This is your plug-in's opportunity to make the corresponding change on the service.

If your plug-in is unable to update the remote service for any reason, you should throw a Lua error from this function via error() or a related built-in function. This causes Lightroom to present a dialog asking the user whether to revert the change, or proceed with the change locally while informing the user this will leave the equivalent collection unaltered on the remote service.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. info

(table) A table with these fields:

• isDefaultCollection: (Boolean) True if this is the default collection.
• name: (string) The new name being assigned to this collection.
• parents: (table) An array of information about parents of this collection, in which each element contains:
  • localCollectionId: (number) The local collection ID.
  • name: (string) Name of the collection set.
  • remoteCollectionId: (number or string) The remote collection ID assigned by the server.
• publishService: (LrPublishService) The publish service object.
• publishedCollection: (LrPublishedCollection or LrPublishedCollectionSet) The published collection object being renamed.
• remoteId: (string or number) The ID for this published collection that was stored via exportSession:recordRemoteCollectionId
• remoteUrl: (optional, string) The URL, if any, that was recorded for the published collection via exportSession:recordRemoteCollectionUrl.

publishServiceProvider.shouldDeletePhotosFromServiceOnDeleteFromCatalog( publishSettings, nPhotos )

(optional) This plug-in defined callback function is called when the user has attempted to delete one or more photos from the Lightroom catalog that are published through your service. It provides an opportunity for you to customize the confirmation dialog.

Do not use this hook to actually delete photo(s). Instead, if the user confirms the deletion for all relevant services. Lightroom will call deletePhotosFromPublishedCollection for that purpose.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. nPhotos

(number) The number of photos that are being deleted. At least one of these photos is published through this service; some may only be published on other services or not published at all.

Return value

(string) What action should Lightroom take?

• "ignore": Leave the photos on the service and simply forget about them.
• "cancel": Stop the attempt to delete the photos.
• "delete": Have Lightroom delete the photos immediately from the service. (Your plug-in will receive a call to its deletePhotosFromPublishedCollection in this case.)
• nil: Allow Lightroom's built-in confirmation dialog to be displayed.

publishServiceProvider.shouldDeletePublishService( publishSettings, info )

(optional) This plug-in defined callback function is called when the user has attempted to delete the publish service from Lightroom. It provides an opportunity for you to customize the confirmation dialog.

Do not use this hook to actually tear down the service. Instead, use willDeletePublishService for that purpose.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. info

(table) A table with these fields:

• publishService: (LrPublishService) The publish service object.
• nPhotos: (number) The number of photos contained in published collections within this service.
• connectionName: (string) The name assigned to this publish service connection by the user.

Return value

(string) 'cancel', 'delete', or nil (to allow Lightroom's default dialog to be shown instead)

publishServiceProvider.shouldDeletePublishedCollection( publishSettings, info )

(optional) This plug-in defined callback function is called when the user has attempted to delete one or more published collections defined by your plug-in from Lightroom. It provides an opportunity for you to customize the confirmation dialog.

Do not use this hook to actually tear down the collection(s). Instead, use deletePublishedCollection for that purpose.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. info

(table) A table with these fields:

• collections: (array of LrPublishedCollection or LrPublishedCollectionSet) The published collection objects.
• nPhotos: (number) The number of photos contained in the published collection. Only present if there is a single published collection to be deleted.
• nChildren: (number) The number of child collections contained within the published collection set. Only present if there is a single published collection set to be deleted.
• hasItemsOnService: (boolean) True if one or more photos have been published through the collection(s) to be deleted.

Return value

(string) "ignore", "cancel", "delete", or nil (If you return nil, Lightroom's default dialog will be displayed.)

publishServiceProvider.shouldReverseSequenceForPublishedCollection( publishSettings, collectionInfo )

(optional) This plug-in defined callback function is called when new or updated photos are about to be published to the service. It allows you to specify whether the user-specified sort order should be followed as-is or reversed. The Flickr sample plug-in uses this to reverse the order on the Photostream so that photos appear in the Flickr web interface in the same sequence as they are shown in the library grid.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. collectionInfo

Return value

(boolean) true to reverse the sequence when publishing new photos

publishServiceProvider.updateCollectionSetSettings( publishSettings, info )

(optional) This plug-in defined callback function is called when the user has changed the per-collection set settings defined via the viewForCollectionSetSettings callback. It is your opportunity to update settings on your web service to match the new settings.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

Your code should not use this callback function to clean up from the dialog. This callback will not be called if the user cancels the dialog.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. info

(table) A table with these fields:

• collectionSettings: (LrObservableTable) Plug-in specific settings for this collection set. The settings in this table are not interpreted by Lightroom in any way, except that they are stored with the collection set. These settings can be accessed via LrPublishedCollectionSet:getCollectionSetInfoSummary. The values in this table must be numbers, strings, or Booleans.
• isDefaultCollection: (Boolean) True if this is the default collection (always false in this case).
• name: (string) The name of this collection set.
• parents: (table) An array of information about parents of this collection, in which each element contains:
  • localCollectionId: (number) The local collection ID.
  • name: (string) Name of the collection set.
  • remoteCollectionId: (number or string) The remote collection ID assigned by the server.
• publishedCollection: (LrPublishedCollectionSet) The published collection set object being edited.
• publishService: (LrPublishService) The publish service object.

publishServiceProvider.updateCollectionSettings( publishSettings, info )

(optional) This plug-in defined callback function is called when the user has changed the per-collection settings defined via the viewForCollectionSettings callback. It is your opportunity to update settings on your web service to match the new settings.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

Your code should not use this callback function to clean up from the dialog. This callback is not be called if the user cancels the dialog.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. info

(table) A table with these fields:

• collectionSettings: (LrObservableTable) Plug-in specific settings for this collection. The settings in this table are not interpreted by Lightroom in any way, except that they are stored with the collection. These settings can be accessed via LrPublishedCollection:getCollectionInfoSummary. The values in this table must be numbers, strings, or Booleans.
• isDefaultCollection: (Boolean) True if this is the default collection.
• name: (string) The name of this collection.
• parents: (table) An array of information about parents of this collection, in which each element contains:
  • localCollectionId: (number) The local collection ID.
  • name: (string) Name of the collection set.
  • remoteCollectionId: (number or string) The remote collection ID assigned by the server.
• publishedCollection: (LrPublishedCollection or LrPublishedCollectionSet) The published collection object being edited.
• publishService: (LrPublishService) The publish service object to which this collection belongs.

publishServiceProvider.validatePublishedCollectionName( proposedName )

This plug-in defined callback function is called when the user attempts to change the name of a collection, to validate that the new name is acceptable for this service.

This is a blocking call. You should use it only to validate easily-verified characteristics of the name, such as illegal characters in the name. For characteristics that require validation against a server (such as duplicate names), you should accept the name here and reject the name when the server-side operation is attempted.

Parameters

1. proposedName

(string) The name as currently typed in the new/rename/edit collection dialog.

Return values

1. (Boolean) True if the name is acceptable, false if not
2. (string) If the name is not acceptable, a string that describes the reason, suitable for display.

publishServiceProvider.viewForCollectionSetSettings( f, publishSettings, info )

(optional) This plug-in defined callback function is called when the user creates a new published collection set or edits an existing one. It can add additional controls to the dialog box for editing this collection set. These controls can be used to configure behaviors specific to this collection set (such as privacy or appearance on a web service).

This is a blocking call. If you need to start a long-running task (such as network access), create a task using the LrTasks namespace.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. f

(LrView.osFactory object) A view factory object.

2. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

3. info

(table) A table with these fields:

• collectionSettings: (LrObservableTable) plug-in specific settings for this collection set. The settings in this table are not interpreted by Lightroom in any way, except that they are stored with the collection set. These settings can be accessed via LrPublishedCollection:getCollectionSetInfoSummary. The values in this table must be numbers, strings, or Booleans. There are some special properties in this table:

  LR_canSaveCollection, which allows you to disable the Edit or Create button in the collection set dialog. (If set to true, the Edit / Create button is enabled; if false, it is disabled.)

  LR_liveName will be kept current with the value displayed in the name field of the dialog during the life span of the dialog. This enables a plug-in to add an observer to monitor name changes performed in the dialog.

  LR_canEditName allows the plug-in to control whether the edit field containing the collection set name in the dialog is enabled. In the case of new creation, the value defaults to true, meaning that the collection set name is editable via the UI, while in the case of a collection being edited, the value defaults in accordance with what the plug-in specifies (or doesn't specify) via 'publishServiceProvider.disableRenamePublishedCollection'.

• collectionType: (string) "collectionSet"
• isDefaultCollection: (Boolean) true if this is the default collection (will always be false)
• name: (string) In the case of edit, the name of this collection set (at the time when the edit operation was initiated), otherwise nil.
• parents: (table) An array of information about parents of this collection, in which each element contains:
  • localCollectionId: (number) The local collection ID.
  • name: (string) Name of the collection set.
  • remoteCollectionId: (number or string) The remote collection ID assigned by the server.
  This field is only present when editing an existing published collection set.
• pluginContext: (LrObservableTable) This is a place for your plug-in to store transient state while the collection set settings dialog is running. It will be passed to your plug-in during the endDialogForCollectionSettings and then discarded.
• publishedCollection: (LrPublishedCollectionSet) The published collection set object being edited. Will be nil when creating a new collection Set.
• publishService: (LrPublishService) The publish service object.

Return value

(table) A single view description created from one of the methods in the view factory. (We recommend that f:groupBox be the outermost view.)

publishServiceProvider.viewForCollectionSettings( f, publishSettings, info )

(optional) This plug-in defined callback function is called when the user creates a new published collection or edits an existing one. It can add additional controls to the dialog box for editing this collection. These controls can be used to configure behaviors specific to this collection (such as privacy or appearance on a web service).

This is a blocking call. If you need to start a long-running task (such as network access), create a task using the LrTasks namespace.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. f

(LrView.osFactory object) A view factory object.

2. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

3. info

(table) A table with these fields:

• collectionSettings: (LrObservableTable) Plug-in specific settings for this collection. The settings in this table are not interpreted by Lightroom in any way, except that they are stored with the collection. These settings can be accessed via LrPublishedCollection:getCollectionInfoSummary. The values in this table must be numbers, strings, or Booleans. There are some special properties in this table:

  LR_canSaveCollection, which allows you to disable the Edit or Create button in the collection dialog. (If set to true, the Edit / Create button is enabled; if false, it is disabled.)

  LR_liveName will be kept current with the value displayed in the name field of the dialog during the life span of the dialog. This enables a plug-in to add an observer to monitor name changes performed in the dialog.

  LR_canEditName allows the plug-in to control whether the edit field containing the collection name in the dialog is enabled. In the case of new creation, the value defaults to true, meaning that the collection name is editable via the UI, while in the case of a collection being edited, the value defaults in accordance with what the plug-in specifies (or doesn't specify) via 'publishServiceProvider.disableRenamePublishedCollection'.

• collectionType: (string) Either "collection" or "smartCollection" (see also: viewForCollectionSetSettings)
• isDefaultCollection: (Boolean) True if this is the default collection.
• name: (string) In the case of editing, the name of this collection (at the time when the edit operation was initiated), otherwise nil.
• parents: (table) An array of information about parents of this collection, in which each element contains:
  • localCollectionId: (number) The local collection ID.
  • name: (string) Name of the collection set.
  • remoteCollectionId: (number or string) The remote collection ID assigned by the server.
  This field is only present when editing an existing published collection.
• pluginContext: (LrObservableTable) This is a place for your plug-in to store transient state while the collection settings dialog is running. It is passed to your plug-in's endDialogForCollectionSettings callback, and then discarded.
• publishedCollection: (LrPublishedCollection) The published collection object being edited, or nil when creating a new collection.
• publishService: (LrPublishService) The publish service object to which this collection belongs.

Return value

(table) A single view description created from one of the methods in the view factory. (We recommend that f:groupBox be the outermost view.)

publishServiceProvider.willDeletePublishService( publishSettings, info )

(optional) This plug-in defined callback function is called when the user has confirmed the deletion of the publish service from Lightroom. It provides a final opportunity for you to remove private data immediately before the publish service is removed from the Lightroom catalog.

Do not use this hook to present user interface (aside from progress, if the operation will take a long time). Instead, use shouldDeletePublishService for that purpose.

This is not a blocking call. It is called from within a task created using the LrTasks namespace. In most cases, you should not need to start your own task within this function.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishSettings

(table) The settings for this publish service, as specified by the user in the Publish Manager dialog. Any changes that you make in this table do not persist beyond the scope of this function call.

2. info

(table) A table with these fields:

• publishService: (LrPublishService) The publish service object.
• nPhotos: (number) The number of photos contained in published collections within this service.
• connectionName: (string) The name assigned to this publish service connection by the user.

Properties

publishServiceProvider.disableRenamePublishedCollection : (Read-Only)

(Boolean) This plug-in defined value, when true, disables (dims) the Rename Published Collection command in the context menu of the Publish Services panel for all published collections created by this service.

First supported in version 3.0 of the Lightroom SDK.

publishServiceProvider.disableRenamePublishedCollectionSet : (Read-Only)

(Boolean) This plug-in defined value, when true, disables (dims) the Rename Published Collection Set command in the context menu of the Publish Services panel for all published collection sets created by this service.

First supported in version 3.0 of the Lightroom SDK.

publishServiceProvider.publish_fallbackNameBinding : (Read-Only)

(optional, string) Plug-in defined value customizes the behavior of the Description entry in the Publish Manager dialog. If the user does not provide an explicit name choice, Lightroom can provide one based on another entry in the publishSettings property table. This entry contains the name of the property that should be used in this case.

publishServiceProvider.small_icon : (Read-Only)

(string) Plug-in defined value is the filename of the icon to be displayed for this publish service provider, in the Publish Services panel, the Publish Manager dialog, and in the header shown when a published collection is selected. The icon must be in PNG format and no more than 24 pixels wide or 19 pixels tall.

First supported in version 3.0 of the Lightroom SDK.

publishServiceProvider.supportsCustomSortOrder : (Read-Only)

(Boolean) If this plug-in defined property is set to true, Lightroom will enable collections from this service to be sorted manually and will call the imposeSortOrderOnPublishedCollection callback to cause photos to be sorted on the service after each Publish cycle.

publishServiceProvider.titleForGoToPublishedCollection : (Read-Only)

When set to the string "disable", the "Go to Published Collection" context-menu item is disabled (dimmed) for this publish service.

First supported in version 3.0 of the Lightroom SDK.

publishServiceProvider.titleForGoToPublishedPhoto : (Read-Only)

(optional, string) Plug-in defined value overrides the label for the "Go to Published Photo" context-menu item, allowing you to use something more appropriate to your service. Set to the special value "disable" to disable (dim) the menu item for this service.

First supported in version 3.0 of the Lightroom SDK.

publishServiceProvider.titleForPhotoRating : (Read-Only)

(optional, string) This plug-in defined property allows you to customize the name of the viewer-defined ratings that are obtained from the service via getRatingsFromPublishedCollection.

First supported in version 3.0 of the Lightroom SDK.

publishServiceProvider.titleForPublishedCollection : (Read-Only)

(optional, string) Plug-in defined value customizes the name of a published collection to match the terminology used on the service you are targeting.

This string is typically used in combination with verbs that take action on the published collection, such as "Create ^1" or "Rename ^1".

If not provided, Lightroom uses the default name, "Published Collection."

First supported in version 3.0 of the Lightroom SDK.

publishServiceProvider.titleForPublishedCollectionSet : (Read-Only)

(optional, string) Plug-in defined value customizes the name of a published collection set to match the terminology used on the service you are targeting.

This string is typically used in combination with verbs that take action on the published collection set, such as "Create ^1" or "Rename ^1".

If not provided, Lightroom uses the default name, "Published Collection Set."

First supported in version 3.0 of the Lightroom SDK.

publishServiceProvider.titleForPublishedCollectionSet_standalone : (Read-Only)

(optional, string) Plug-in defined value customizes the name of a published collection to match the terminology used on the service you are targeting.

Unlike titleForPublishedCollectionSet, this string is typically used by itself. In English, these strings may be the same, but in other languages (notably German), you may have to use a different form of the name to be gramatically correct. If you are localizing your plug-in, use a separate translation key to make this possible.

If not provided, Lightroom uses the value of titleForPublishedCollectionSet instead.

First supported in version 3.0 of the Lightroom SDK.

publishServiceProvider.titleForPublishedCollection_standalone : (Read-Only)

(optional, string) Plug-in defined value customizes the name of a published collection to match the terminology used on the service you are targeting.

Unlike titleForPublishedCollection, this string is typically used by itself. In English, these strings nay be the same, but in other languages (notably German), you may have to use a different form of the name to be gramatically correct. If you are localizing your plug-in, use a separate translation key to make this possible.

If not provided, Lightroom uses the value of titleForPublishedCollection instead.

First supported in version 3.0 of the Lightroom SDK.

publishServiceProvider.titleForPublishedSmartCollection : (Read-Only)

(optional, string) Plug-in defined value customizes the name of a published smart collection to match the terminology used on the service you are targeting.

This string is typically used in combination with verbs that take action on the published smart collection, such as "Create ^1" or "Rename ^1".

If not provided, Lightroom uses the default name, "Published Smart Collection."

First supported in version 3.0 of the Lightroom SDK.

publishServiceProvider.titleForPublishedSmartCollection_standalone : (Read-Only)

(optional, string) Plug-in defined value customizes the name of a published smart collection to match the terminology used on the service you are targeting.

Unlike titleForPublishedSmartCollection, this string is typically used by itself. In English, these strings may be the same, but in other languages (notably German), you may have to use a different form of the name to be gramatically correct. If you are localizing your plug-in, use a separate translation key to make this possible.

If not provided, Lightroom uses the value of titleForPublishedSmartCollectionSet instead.

First supported in version 3.0 of the Lightroom SDK.