Class LrPublishedCollection

Summary

Functions

pubCollection:addPhotoByRemoteId( photo, remoteID, remoteUrl, published )

Adds a photo with a remote ID and URL to this collection, if it is not a smart collection. If the photo exists in the collection, replaces the old remote ID and URL with the new values. Throws an exception if this is a smart collection and the photo is not already included. (For a smart collection, a reason to call this function would be to update the 'published' status of a photo.)

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. photo

(LrPhoto) The photo object.

2. remoteID

(string or number) The new remote unique identifier.

3. remoteUrl

(string) The new URL, or nil.

4. published

(Boolean) True to mark the photo as "already published", false to mark as "need to publish".

pubCollection:addPhotos( photos )

Adds photos to this collection, if it is not a smart collection. Throws an exception if this is a smart collection.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. photos

(array of LrPhoto) The photo objects.

pubCollection:addPublishedPhotos( publishedPhotos )

Adds a set of published photos, along with their publication data, to this collection, if it is not a smart collection. Throws an exception if this is a smart collection.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. publishedPhotos

(array of LrPublishedPhoto) The publication-data objects. These point to the photo objects to be added.

pubCollection:delete()

Removes this collection from the containing catalog.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

pubCollection:getCollectionInfoSummary()

Retrieves an information summary about this published collection.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 3.0 of the Lightroom SDK.

Return value

table with the following information:

• name: Name of the published collection
• localIdentifier: Internal ID number of the collection (the local identifier).
• remoteId: The ID of the collection on the remote service.
• remoteUrl: URL of the collection (if applicable) as published.
• isDefaultCollection: (Boolean) True if this is the default collection.
• parents: (array of tables) Information about any published collection sets that contain this collection. An array of tables, each containing name, localCollectionId, remoteCollectionId, and publishedUrl.
• collectionSettings: (table) Any collection-specific settings that have been stored by the plug-in.
• publishSettings: (table) Publish settings for this plug-in.

pubCollection:getName()

Retrieves the current name of this collection.

This function must be called from within an asynchronous task started using LrTasks. Must not be called from within the same catalog:with___WriteAccessDo gate in which the collection object was created.

First supported in version 3.0 of the Lightroom SDK.

Return value

(string) The name.

pubCollection:getParent()

Retrieves the parent collection set, if any, that contains this collection.

This function must be called from within an asynchronous task started using LrTasks. Must not be called from within the same catalog:with___WriteAccessDo gate in which the collection object was created.

First supported in version 3.0 of the Lightroom SDK.

Return value

(LrPublishedCollectionSet) The parent set object or nil.

pubCollection:getPhotos()

Retrieves all of the photos in this collection.

This function must be called from within an asynchronous task started using LrTasks. Must not be called from within the same catalog:with___WriteAccessDo gate in which the collection object was created.

First supported in version 3.0 of the Lightroom SDK.

Return value

(array of LrPhoto) An array of photo objects.

pubCollection:getPublishedPhotos()

Retrieves the publication data for photos in this collection.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 3.0 of the Lightroom SDK.

Return value

(array of LrPublishedPhoto) An array of publication-data objects..

pubCollection:getRemoteId()

Retrieves the remote service's unique identifier for this published collection, as previously recorded by the plug-in.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 3.0 of the Lightroom SDK.

Return value

(string or number) The remote ID.

pubCollection:getRemoteUrl()

Retrieves the URL for this published collection, as assigned by the remote service and previously recorded by the plug-in.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 3.0 of the Lightroom SDK.

Return value

(string or number) The remote URL.

pubCollection:getSearchDescription()

Retrieves the search description for a smart collection. Throws an exception if this is not a smart collection.

First supported in version 5.0 of the Lightroom SDK.

See LrCatalog:findPhotos for details on what a search description looks like.

Return value

Table containing the search description.

pubCollection:getService()

Retrieves the service that this collection belongs to.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 3.0 of the Lightroom SDK.

Return value

(LrPublishService) The parent publish service object.

pubCollection:isSmartCollection()

Reports whether this collection is a smart collection.

This function must be called from within an asynchronous task started using LrTasks. Must not be called from within the same catalog:with___WriteAccessDo gate in which the collection object was created.

First supported in version 3.0 of the Lightroom SDK.

Return value

(Boolean) True if this is a smart collection.

pubCollection:publishNow( doneCallback )

Initiates a publish operation for this collection. It is strongly recommended that plug-ins make any auto-publishing behavior opt-in via the Lightroom Publishing Manager.

First supported in version 4.0 of the Lightroom SDK.

Parameters

1. doneCallback

(function, optional) A function which will be called when the publish operation has been completed.

pubCollection:removeAllPhotos()

Removes all photos from this collection if it is not a smart collection. Throws an exception if this is a smart collection.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

pubCollection:removePhotos( photos )

Removes photos from this collection if it is not a smart collection. Throws an exception if this is a smart collection.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. photos

(array of LrPhoto) The photo objects.

pubCollection:setCollectionSettings( settings )

Sets the plug-in-specific settings for this published collection. This is the same block of data that can be edited via the user interface if your plug-in implements the viewForCollectionSettings hook.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. settings

(table) The table of settings; contents are defined by the plug-in.

pubCollection:setName( name )

Sets a new name for this published collection.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. name

(string) The new name.

Return value

True on success, false if there is already a published collection or collection set with the same name and parent.

pubCollection:setParent( parent )

Sets a new parent for this published collection. This function does not enforce any restrictions on collection-set depth, nor does it call the plug-in's reparentPublishedCollection callback. The plug-in is responsible for ensuring synchronization with the publication site.

It is an error to set a parent that belongs to a different LrPublishService, or even to a different publish-service connection.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. parent

(LrPublishedCollectionSet) The new parent set in the same LrPublishService, or nil to make this an immediate child of the service that contains it.

pubCollection:setRemoteId( remoteId )

Sets the unique identifier for this published collection as understood by the remote service.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. remoteId

(string or number) The new remote ID.

pubCollection:setRemoteUrl( url )

Sets the URL for this published collection, as provided by the remote service. It is not required to have a URL on record with Lightroom. If one is provided, it is displayed in the publish header in the Library grid and used to enable the "Go to Published Collection" command in the collection context menu.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. url

(string) The URL.

pubCollection:setSearchDescription( searchDesc )

Sets the search description for this smart collection. Throws an exception if this is not a smart collection.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. searchDesc

(table) A search descriptor that defines what metadata fields to search, and how to match against a given value. See LrCatalog:findPhotos for details.

pubCollection:type()

Reports the type of this object.

First supported in version 3.0 of the Lightroom SDK.

Return value

(string) 'LrPublishedCollection'.

Properties

pubCollection.catalog : (Read-Only)

(LrCatalog) The catalog object that contains this collection.

First supported in version 3.0 of the Lightroom SDK.

See also: LrCatalog

pubCollection.localIdentifier : (Read-Only)

(number) The local identifier of the published collection, unique withing the catalog.

Must not be called from within the same catalog:with___WriteAccessDo gate in which the collection object was created.

First supported in version 3.0 of the Lightroom SDK.