Image banks
The image banks plugin provides the ability to search external image banks for photos without navigating manually to their system.
How to use it
Searches are run in the external image bank using the simple search box and using the dropdown selector called "Search external image banks".
Clicking Search runs the search for you. Note: some Image Bank providers might have restrictions and ResourceSpace will, where required, cache the results as per Providers' API requirements.
The search results will be displayed showing at the top how many results were found in total, which Image Bank you've searched through and how many results to show per page.
How to use the files
There are a few ways to interact with the results:
- Clicking on the preview image will take you to the Image Bank Providers' page of that file
- Clicking on will download the file to your system. Alternatively, you can right-click on the icon and select "Save link as"
- Depending on the users' ability to create new resources in the system, an option to create a resource based on the result from Pixabay will be available. Click on to create new resource.
Configuration
Image Banks plugin can be configured based on each Providers' requirements. For example, Pixabay only requires a Pixabay API key.
Shutterstock is also available to search from the image banks drop down, images can be downloaded but cannot be used to create resources directly as with Pixabay. Clicking Download will take you to the Shutterstock site to complete the download.
From version 10.3 Image Banks plugin provides linking with multiple ResourceSpace instances. The configuration page allows admins to input a ResourceSpace provider instance details. The format for an instance configuration is i18n name|baseURL|API username|API key|JSON config. For example, here's how you could link with two other ResourceSpace instances:
USA|https://usa.rs.example.com|central-api|yourAPIKey|{}
~en:France~ro:Franţa|https://fr.library.example.com|central-api|yourAPIKeyOnThisSystem|{"view_title_field": 238}
The name of each instance can be translated as this will be used to display the option when selecting the Provider.
The JSON configuration allows mapping an instance configuration to the hosts' ResourceSpace application. Only the "view_title_field" configuration option is currently supported which allows the admin to specify which field should be used as the title for the remote resources.
Note: all configured ResourceSpace instances should be on v10.3+ and ideally all have the same version.
Selected providers
From version 10.3 administrators can enable providers as required. By default, both Pixabay and Shutterstock are selected.
Multi-instance providers (e.g ResourceSpace) can only be selected once configured.
Moving from Resource Connect
The ResourceSpace provider allows admins to connect with other ResourceSpace systems. To do this, admins need to go through their resourceconnect configuration file, and for each of the affiliates to add them as an instance in the Image Banks' plugin setup page.
While there are multiple ways to achieve this, it is recommended for ease of use and transparency to use a dedicated user (and user group) for Image Bank integration on each affiliate system.
Developers
Image Banks plugin has been designed to allow developers to add new providers with little effort.
New providers should be added to the providers folder, each in its own separate file. Any libraries that should be installed for a particular provider should be added to the lib folder.
Note: It is advised that developers do not commit dependent libraries to ResourceSpace, but use the checkDependencies() method the provider needs to implement to notify administrators if a particular provider needs to be configured more (e.g install libraries).
Most important requirements are:
- All Providers MUST extend the Provider class
- The runSearch() method MUST return a ProviderSearchResults object
- All elements of a ProviderSearchResults object MUST be a ProviderResult object
If needed to add certain elements for the configuration page of the plugin, use the buildConfigPageDefinition() method. Any configs used for the configuration page will have to be set in the configs property so the system can register them for the plugin.
Multi-instance Provider
From version 10.3 the plugin supports Providers having multiple instances of themselves. Each Provider instance is of course going to link with a different system (e.g linking with ResourceSpace system from different regions within the same organisation).
When a Provider requires multi-instance support, implement the MultipleInstanceProviderInterface.
When writing new pages, in order to handle both types of Providers, the usual flow is to combine the following functions: getProviders, providersCheckedAndActive and getProviderSelectInstance. For examples see the view and search pages.
View page (emulation)
From version 10.3 the plugin allows Providers to show a search result on a minimal view page. This can be used to show associated metadata or any extra information which may be required.
If a Provider wants to use the view page emulation it should override, as needed, the following AbstractProvider's methods: getResourceDownloadOptionsTable, getImageNonMetadataProperties and getImageMetadata.