What is the difference between the GetItems and GetFolderContent methods on IContentLibraryContext Interface

Question

I have written an External Content Library (ECL) provider and it works very well. My GetFolderContent() method of my context class which implements IContentLibraryContext successfully populates my lists in the CME.

I have also implemented the GetItem() method which is called when I open a Folder or File from the ECL provider.

Having watched the Developing an Provider (ECL) video, I notice that there is also a GetItems() method, but it unclear to me what it does and when it is called. Can anyone explain what it does, and why I should implement it (it currently returns null).

Answer 1

The main difference between GetItems and GetFolderContent is that GetItems is provided with a list of URLs identifying the exact items to get. GetFolderContent is only provided the ID of the parent item and is then getting the child items.

As you have discovered ECL only use GetFolderContent when all you do is browsing the content.

GetItems is used when it is already known exactly which ECL items should be retreived. Funcationally it is quite close to a loop calling GetItem for each item in the list, the obvious difference being possible performance benefits from bulk loading if the protocol you access the external system allows it, as well as a difference in error handling (more details on that below).

GetItems is called every time the UI load data from the backend that contains one or more ECL items. For example if you add ECL items to a bundle, you will get a call to GetItems in the provider when the items in the bundle are displayed.

Another concrete example: Add one or more ECL items to a component. GetItems will now be called every time this component is opened in the UI. This is done as ECL needs to get the correct title for the ECL items you added.

Another not so obvious example is when you display the BluePrint for an ECL item. While most providers will probably not be BluePrint aware it is possible to make one that is. This means ECL has to request the item for all publications in the BluePrint in case the provider is returning for example translated titles based on the Publication. So when implementing a Provider that is not BluePrint aware you should check that you only retrieve the external item once, but still return one item per requested publication.

As mentioned GetItems has to handle errors slightly different from GetItem. Specifically it is not allowed to throw an exception if the external item no longer exists, or if the current user does not have access to the external item. In this case it simply shouldn't return a result for that specific URI. In all other error cases it should still throw if possible.

This allows a Component to be loaded even if it contains a link to an ECL item that has been deleted. It also makes it possible to use GetItems as "Exists". Simply call GetItems with a single EclUri and check if the returned collection contains the requested item.

And finally remember your Provider is exposed to template writers as well... they can call GetItems whenever they want for whatever reason they want. :)