Resource Scenarios

Adding items to an exhibit

Curators can add items to an exhibit from the Curation > Items page:

The exhibit administrator can configure the available options.

Indexing existing items

Items can be imported from external systems. Community-contributed gems provide prebuilt importing from common data sources:

• https://github.com/sul-dlss/spotlight-iiif-resources (now merged into Spotlight)
• https://github.com/sul-dlss/spotlight-dor-resources (now incorporated into sul-dlss/exhibits)
• https://github.com/jkeck/spotlight-flickr-resources
• https://github.com/cbeer/spotlight-atom
• https://github.com/cbeer/spotlight-import-internet_archive
• https://github.com/harvard-lts/spotlight-oaipmh-resources

Uploaded resources

Spotlight allows curators to create new exhibit-specific objects with an image, title, and basic descriptive metadata. This configuration allows implementors to use Spotlight without existing data or needing to wire in external indexing processes, and allows curators to build out simple exhibits out-of-the-box.

At this time, uploaded resources must be images (#1071) and are limited to single-image items (#851).

Exhibit-specific metadata fields

Curators can add exhibit-specific metadata fields from the Curation > Metadata page.

These fields can be populated on any resource, including manually uploaded resources.

Creating multiple items from a spreadsheet

Configuring uploaded metadata

In addition to exhibit-specific custom fields, the Spotlight::Engine configuration can provide a set of additional fields. Unlike exhibit-specific fields, which map to exhibit-specific field names, the uploaded fields can be mapped to arbitrary fields in the Solr schema. This allows the application maintainer to create some parity between externally indexed resources (so all resources have e.g. the same descriptive metadata field), and some parity across exhibits within an application.

These fields will be automatically added as metadata fields on the search results page.

    # Defaults to the blacklight_config.index.title_field:
    Spotlight::Engine.config.upload_title_field = nil # OpenStruct.new(...)

    Spotlight::Engine.config.upload_fields = [
      OpenStruct.new(field_name: :spotlight_upload_description_tesim, label: "Description", form_field_type: :text_area),
      OpenStruct.new(field_name: :spotlight_upload_attribution_tesim, label: "Attribution"),
      OpenStruct.new(field_name: :spotlight_upload_date_tesim, label: "Date")
    ]

Limiting file extensions for uploaded resources

    # The allowed file extensions for uploading non-repository items.
    Spotlight::Engine.config.allowed_upload_extensions = %w(jpg jpeg png)

Externally indexed resources

Spotlight, just as with Blacklight, can be configured to work with an existing Solr index. Spotlight will use Blacklight's CatalogController configuration to provide the default options available to the curator. Blacklight configuration is discussed in depth on the Blacklight wiki.

Spotlight adds some additional requirements to the Solr schema:

• In order to index exhibit-specific fields, out-of-the-box, Spotlight provides an indexing strategy that uses Atomic Updates. This approach requires specific Solr schema configuration, so note the caveats, limitations and required configuration necessary to use this feature. The rake task spotlight:check:solr will test if your Solr configuration is configured correctly for Atomic Updates.

Alternatively, if you are unable to use the Atomic Update strategy, your SolrDocument class must implement a #reindex method that can update the document in Solr with the exhibit-specific data provided by a #to_solr call.

• Exhibit-specific fields are generated using a suffix to indicate the expected Solr schema types. These are the default values (which can be overridden in an application initializer):

Spotlight::Engine.config.solr_fields.prefix = "".freeze
Spotlight::Engine.config.solr_fields.boolean_suffix = "_bsi".freeze # boolean, stored, indexed
Spotlight::Engine.config.solr_fields.string_suffix = "_ssim".freeze # string, stored, indexed, multivalued
Spotlight::Engine.config.solr_fields.text_suffix = "_tesim".freeze # text, stored, indexed, multivalued

• Spotlight sends facet.field and facet.query parameters as part of the search request in order to provide exhibit-specific features (e.g. tags, item visibility). Solr must be configured to respect these parameters (the default).

On-demand resource indexing

Another supported resource configuration allows the curator to select resources within the exhibit. To configure this user experience, you need to write some basic Ruby code. First, use the spotlight:scaffold_resource generator to create the model-view-controller classes.

$ bundle exec rails generate spotlight:scaffold_resource example

Update the generated ExampleResource model with your custom model behavior and stored attributes:

class ExampleResource < Spotlight::Resource
  def self.indexing_pipeline
    @indexing_pipeline ||= super.dup.tap do |pipeline|
      # your pipeline here...
    end
  end
end

Update the generated ExampleResource pipeline with code to convert the resource into a Solr hash, e.g.

class ExampleResource < Spotlight::Resource
  def self.indexing_pipeline
    @indexing_pipeline ||= super.dup.tap do |pipeline|
      # call the to_solr method on the resource, and apply Spotlight's default data
      pipeline.transforms = [Spotlight::Etl::Sources::SourceMethodSource(:to_solr)] + pipeline.transforms
    end
  end

  def to_solr
    # your hash here:
    # { }
  end
end

An instance of the ExampleResource provides several out-of-the-box attributes:

• #exhibit, the exhibit that this resource belongs to
• #data, a serialized hash that your application can put arbitrary data into

Update the generated form to add any additional form fields:

<%= form_for([current_exhibit, @resource.becomes(ExampleResource)]) do |f| %>
  <%= f.text_field :values  %>
  <%= f.submit t('.add_item'), class: 'btn btn-primary' %>
<% end if can? :manage, ExampleResource %>

Finally, add the form to the external_resources_partials in the config/spotlight_initializer.rb file:

Spotlight::Engine.config.external_resources_partials += ['example_resources/form']