Spotlight

Understanding the primary abstractions in Spotlight:

• Exhibits (Spotlight::Exhibit): The main organizational container for content.
• Pages (Spotlight::Page / Spotlight::HomePage): Curated pages within an exhibit, using Sir Trevor for rich text editing.
• Custom Fields (Spotlight::CustomField): Admin-defined fields (e.g., multivalued text, read-only metadata) added to exhibit items.
• Sidecars (Spotlight::SolrDocumentSidecar): Database-backed extensions to Solr documents that allow exhibit-specific metadata to persist locally.
• Resources (Spotlight::Resource): External or uploaded content that is converted into Solr documents.

Frontend Architecture:

• Source JavaScript is located in app/javascript/spotlight/.
• Core orchestration happens in app/javascript/spotlight/index.js, which listens for page loads and instantiates class components (e.g., new AddAnother().connect()).

To develop on Spotlight, you must work within the context of a Rails application. The project uses engine_cart to manage an internal test application and solr_wrapper to manage Solr.

Prerequisites

• Ruby 3.2+
• Ruby on Rails 7.1+
• Java 11+ (unless using Solr in Docker)
• ImageMagick (for riiif service or custom Carrierwave uploaders)

Quick Start with solr_wrapper

1. Clone the repository and cd into it.
2. Run bundle install.
3. Run the following command to build the app, start Solr, and launch the Rails server:

   rake spotlight:server

   You will be prompted to create an admin user.

Quick Start with Docker

1. Run Solr in Docker:

   docker compose up -d

2. Set up the test app and seed an admin user:

   rake engine_cart:generate
   rake spotlight:fixtures
   cd .internal_test_app
   rake spotlight:seed_admin_user
   bin/dev

To bootstrap a new Spotlight instance, use the provided Rails template. You can choose between importmap-rails (default) or jsbundling-rails with esbuild.

Note: During installation, you will be prompted to create an initial administrator email and password. This super-admin can manage any exhibit in the installation. If you skip this, the first user created will be granted administrative privileges.

Using importmap-rails:

$ SKIP_TRANSLATION=1 rails new app-name -m https://raw.githubusercontent.com/projectblacklight/spotlight/main/template.rb -a propshaft --css bootstrap

Using jsbundling-rails with esbuild:

$ SKIP_TRANSLATION=1 rails new app-name -m https://raw.githubusercontent.com/projectblacklight/spotlight/main/template.rb -a propshaft -j esbuild --css bootstrap

From an existing Rails application:

$ SKIP_TRANSLATION=1 rails app:template LOCATION=https://raw.githubusercontent.com/projectblacklight/spotlight/main/template.rb

For blocks that primarily interact with Solr documents (like carousels, grids, or embeds), extend SirTrevor.Blocks.SolrDocumentsBase. This class simplifies autocomplete and captioning for Solr results.

Key features provided by the base class:

• Autocomplete: Automatically handles Solr-based autocomplete using autocomplete_url() and transform_autocomplete_results().
• Captioning: Provides caption_options() which generates UI for selecting primary and secondary Solr fields to display as captions.
• Field Mapping: Uses caption_option_values() to populate dropdowns based on configured index fields.

Common implementations include:

• SirTrevor.Blocks.SolrDocuments: Standard Solr document list.
• SirTrevor.Blocks.SolrDocumentsCarousel: A carousel of Solr documents with configurable auto-play intervals and heights.
• SirTrevor.Blocks.SolrDocumentsGrid: A grid layout of Solr documents.
• SirTrevor.Blocks.SolrDocumentsEmbed: An embedded view of Solr documents.

To create a block that manages a collection of resources (like Solr documents or uploaded files), extend Spotlight$1.Block.Resources. This base class provides methods for managing item panels, autocomplete functionality, and item options.

Key methods to implement or override:

• type: A unique string identifier for the block.
• icon_name: The icon used in the editor.
• autocomplete_url(): Returns the URL used for fetching autocomplete suggestions.
• autocomplete_template(obj): Returns the HTML string for an individual autocomplete result item.
• _itemPanel(data): Generates the HTML markup for an individual item within the resource list.
• item_options(): Returns HTML for additional configuration settings for the entire block.
• afterPanelRender(data, panel): A lifecycle hook called after an item panel is added to the DOM. Useful for initializing third-party libraries (like IIIF or carousels) on the new panel.
• afterPanelDelete(): A lifecycle hook called after an item is removed from the list.

SirTrevor.Blocks.MyCustomResource = (function () {
  return Spotlight$1.Block.Resources.extend({
    type: "my_custom_resource",
    icon_name: "my_icon",
    autocomplete_url: function () { /* ... */ },
    autocomplete_template: function (obj) { /* ... */ },
    _itemPanel: function (data) { /* ... */ },
    item_options: function () { /* ... */ }
  });
})();