### Manual Setup for Spotlight Development Server with solr_wrapper

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

Individual commands to set up and run a Spotlight development server manually using solr_wrapper. This involves starting Solr, generating the test application, loading fixtures, and starting the Rails server.

```shell
solr_wrapper # Run in separate tab
rake engine_cart:generate
rake spotlight:fixtures
cd .internal_test_app
bin/rails spotlight:initialize
bin/dev
```

--------------------------------

### Starting and Cleaning Solr with solr_wrapper

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

Commands to start a Solr instance using solr_wrapper and to reset Solr to a clean state, removing existing data and configurations. Useful for ensuring a pristine testing environment.

```shell
solr_wrapper
solr_wrapper clean
```

--------------------------------

### Bootstrap New Rails App for Spotlight

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Installs Spotlight and its dependencies into a new Rails application using importmap-rails or esbuild. Includes database migrations and starting the Solr wrapper and Rails server.

```bash
# Using importmap-rails (default)
SKIP_TRANSLATION=1 rails new my-exhibit-app \
  -m https://raw.githubusercontent.com/projectblacklight/spotlight/main/template.rb \
  -a propshaft --css bootstrap

# Using jsbundling with esbuild
SKIP_TRANSLATION=1 rails new my-exhibit-app \
  -m https://raw.githubusercontent.com/projectblacklight/spotlight/main/template.rb \
  -a propshaft -j esbuild --css bootstrap

cd my-exhibit-app
SKIP_TRANSLATION=1 rake db:migrate
solr_wrapper &  # Start Solr
bin/dev         # Start Rails server
```

--------------------------------

### Start Rails Development Server

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

This command starts the Rails development server, allowing you to view and interact with your Spotlight application in a browser.

```bash
bin/dev
```

--------------------------------

### Start Solr Wrapper for Spotlight

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

This command starts the Solr server, often using the `solr_wrapper` gem, which is a requirement for Spotlight to function. This is typically used during development or testing.

```bash
solr_wrapper
```

--------------------------------

### Running Spotlight Development Server with solr_wrapper

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

Command to start a Spotlight development server using solr_wrapper. This task automatically sets up an internal test application, starts Solr, and runs the Rails server. It prompts for admin user creation.

```shell
rake spotlight:server
```

--------------------------------

### Install npm Dependencies

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

This command installs the necessary Node.js dependencies for the JavaScript components of Spotlight, as managed by npm.

```bash
npm install
```

--------------------------------

### Add Spotlight to Existing Rails App

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

This command applies the Spotlight installation template to an existing Rails application. It automates the setup process for integrating Spotlight.

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

--------------------------------

### Running Spotlight Development Server with Docker

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

Commands to set up and run a Spotlight development server using Docker for Solr. This includes starting Solr via Docker Compose, generating the test application, seeding the admin user, and starting the Rails server.

```shell
docker compose up -d
rake engine_cart:generate
rake spotlight:fixtures
cd .internal_test_app
rake spotlight:seed_admin_user
bin/dev
```

--------------------------------

### Running Spotlight Tests with solr_wrapper

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

Command to run all Spotlight tests using solr_wrapper. This task automatically starts Solr, runs the tests, and shuts down Solr afterward. Ensure Solr is not already running before executing this command.

```shell
rake
```

--------------------------------

### Search and Catalog API Endpoints (Bash)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Demonstrates how to interact with the Blacklight Spotlight REST API for searching and retrieving catalog data. Includes examples for general search, document details, IIIF manifests, and autocomplete suggestions.

```bash
# Search within exhibit
curl "http://localhost:3000/my-exhibit/catalog.json?q=landscape"

# Get document details
curl "http://localhost:3000/my-exhibit/catalog/doc-id.json"

# Get IIIF manifest for document
curl "http://localhost:3000/my-exhibit/catalog/doc-id/manifest"

# Autocomplete suggestions
curl "http://localhost:3000/my-exhibit/catalog/autocomplete?q=paint"
```

--------------------------------

### Checking Running Solr Processes

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

Shell command to list all running processes and filter for those related to Solr. This can help diagnose issues if Solr fails to start or shut down properly.

```shell
ps -eaf | grep solr
```

--------------------------------

### Tag Management for Documents

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Provides examples for adding, removing, and performing bulk operations on tags associated with documents within an exhibit. Tagging helps in organizing and categorizing content for better discoverability.

```ruby
# Add tags to documents
sidecar = document.sidecar(exhibit)
sidecar.tag_list.add('painting', 'impressionism', '19th-century')
sidecar.save

# Remove tags
sidecar.tag_list.remove('impressionism')
sidecar.save

# Bulk tag operations
Spotlight::BulkActions.add_tags(
  exhibit: exhibit,
  document_ids: ['id1', 'id2'],
  tags: ['featured', 'homepage']
)
```

--------------------------------

### Exhibit Management API Endpoints (Bash)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Provides examples for managing exhibits via the REST API, including exporting exhibit data as JSON, importing exhibits (requires authentication), triggering reindexing, and monitoring resource indexing status.

```bash
# Export exhibit as JSON
curl "http://localhost:3000/my-exhibit/exhibit" > exhibit.json

# Import exhibit (requires authentication)
curl -X POST \
  -H "Content-Type: application/json" \
  -d @exhibit.json \
  "http://localhost:3000/my-exhibit/import"

# Trigger reindex
curl -X POST "http://localhost:3000/my-exhibit/reindex"

# Monitor resource indexing
curl "http://localhost:3000/my-exhibit/resources/monitor.json"
```

--------------------------------

### Example Custom Resource Form View (ERB)

Source: https://github.com/projectblacklight/spotlight/wiki/Resource-Scenarios

An ERB template for rendering a form for a custom resource, such as `ExampleResource`. It includes standard form elements like text fields and a submit button, and conditionally renders based on user permissions.

```erb
<%= 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 %>
```

--------------------------------

### Bulk Operations API Endpoints (Bash)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Shows how to perform bulk operations on documents within an exhibit using the REST API. Examples include changing visibility, adding tags, and removing tags, all requiring JSON payloads with document IDs and relevant data.

```bash
# Change visibility
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"document_ids":["id1","id2"], "visibility":"private"}' \
  "http://localhost:3000/my-exhibit/bulk_actions/change_visibility"

# Add tags
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"document_ids":["id1","id2"], "tags":["featured"]}' \
  "http://localhost:3000/my-exhibit/bulk_actions/add_tags"

# Remove tags
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"document_ids":["id1"], "tags":["outdated"]}' \
  "http://localhost:3000/my-exhibit/bulk_actions/remove_tags"
```

--------------------------------

### Check User Permissions with CanCanCan (Ruby)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Provides examples of checking user permissions using the CanCanCan gem within a Ruby application. It demonstrates how to verify if a user has rights to curate an exhibit or manage the Spotlight site and how to use `authorize!` in controllers.

```ruby
# CanCanCan authorization
ability = Ability.new(current_user)

if ability.can?(:curate, exhibit)
  puts "User can curate this exhibit"
end

if ability.can?(:manage, Spotlight::Site.instance)
  puts "User is a site administrator"
end

# Controller authorization
class MyController < ApplicationController
  def edit
    authorize! :curate, @exhibit
    # ... edit logic
  end
end
```

--------------------------------

### Reindex Specific Resource Synchronously and Asynchronously (Ruby)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Provides code examples for reindexing a specific resource within an exhibit, both synchronously (blocking until completion) and asynchronously. It returns the count of indexed documents for the synchronous operation.

```ruby
resource = exhibit.resources.find(123)

# Synchronous reindex (blocks until complete)
count = resource.reindex
puts "Indexed #{count} documents"

# Asynchronous reindex
resource.reindex_later
```

--------------------------------

### Search and Catalog Endpoints

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Endpoints for searching content within an exhibit, retrieving document details, and getting IIIF manifests.

```APIDOC
## GET /my-exhibit/catalog.json

### Description
Searches for content within the current exhibit.

### Method
GET

### Endpoint
`/my-exhibit/catalog.json`

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query.

### Request Example
```bash
curl "http://localhost:3000/my-exhibit/catalog.json?q=landscape"
```

## GET /my-exhibit/catalog/doc-id.json

### Description
Retrieves detailed information for a specific document within the exhibit.

### Method
GET

### Endpoint
`/my-exhibit/catalog/doc-id.json`

### Parameters
#### Path Parameters
- **doc-id** (string) - Required - The unique identifier of the document.

### Request Example
```bash
curl "http://localhost:3000/my-exhibit/catalog/doc-id.json"
```

## GET /my-exhibit/catalog/doc-id/manifest

### Description
Retrieves the IIIF manifest for a specific document, enabling integration with IIIF viewers.

### Method
GET

### Endpoint
`/my-exhibit/catalog/doc-id/manifest`

### Parameters
#### Path Parameters
- **doc-id** (string) - Required - The unique identifier of the document.

### Request Example
```bash
curl "http://localhost:3000/my-exhibit/catalog/doc-id/manifest"
```

## GET /my-exhibit/catalog/autocomplete

### Description
Provides autocomplete suggestions based on the user's query.

### Method
GET

### Endpoint
`/my-exhibit/catalog/autocomplete`

### Parameters
#### Query Parameters
- **q** (string) - Required - The partial search query for suggestions.

### Request Example
```bash
curl "http://localhost:3000/my-exhibit/catalog/autocomplete?q=paint"
```
```

--------------------------------

### Extend Resource Indexing Pipeline with Custom Transforms (Ruby)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Shows how to extend the ETL pipeline for resource indexing by creating a custom transform class. This allows adding custom fields or exhibit-specific data during the indexing process. The example registers a custom transform within a Resource subclass.

```ruby
# Create custom transform
class MyCustomTransform
  def initialize(context)
    @context = context
  end

  def call(data)
    # Add custom field to all indexed documents
    data[:my_custom_field_ssim] = 'Custom Value'

    # Add exhibit-specific data
    data[:exhibit_title_ssim] = @context.resource.exhibit.title

    data
  end
end

# Register transform in Resource subclass
class MyCustomResource < Spotlight::Resource
  self.indexing_pipeline = Spotlight::Etl::Pipeline.new do |pipeline|
    pipeline.sources = [Spotlight::Etl::Sources::IdentitySource]
    pipeline.transforms = [
      reject_blank: Spotlight::Etl::Transforms::RejectBlank,
      my_custom: MyCustomTransform,
      apply_exhibit_metadata: Spotlight::Etl::Transforms::ApplyExhibitMetadata
    ]
    pipeline.loaders = [Spotlight::Etl::SolrLoader]
  end
end
```

--------------------------------

### Configuration Options

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Details on how to configure the Blacklight Spotlight engine through its initializer.

```APIDOC
## Spotlight Engine Configuration

### Description
This section details the configuration options available for the Spotlight engine, which can be set in `config/initializers/spotlight_initializer.rb`.

### Method
N/A (Configuration)

### Endpoint
N/A (Configuration File)

### Parameters
#### Engine Configuration Options
- **config.user_class** (string) - The class name for the User model.
- **config.catalog_controller_class** (string) - The class name for the Catalog controller.
- **config.exhibit_themes** (array of strings) - A list of available themes for exhibits.
- **config.solr_fields.prefix** (string) - Prefix for Solr field names.
- **config.solr_fields.string_suffix** (string) - Suffix for multi-valued string Solr fields (default: `_ssim`).
- **config.solr_fields.text_suffix** (string) - Suffix for full-text searchable Solr fields (default: `_tesim`).
- **config.solr_fields.boolean_suffix** (string) - Suffix for boolean Solr fields (default: `_bsi`).
- **config.upload_fields** (array of Spotlight::UploadFieldConfig objects) - Defines fields for the upload form.
  - **field_name** (string) - The name of the field.
  - **label** (string) - The label displayed in the form.
  - **form_field_type** (symbol) - The type of form input (e.g., `:text_field`, `:text_area`).
- **config.iiif_service** (class) - The class implementing the IIIF service (e.g., `Spotlight::RiiifService`).
- **config.iiif_manifest_field** (string) - The Solr field storing the IIIF manifest URL (default: `iiif_manifest_url_ssi`).
- **config.thumbnail_field** (string) - The Solr field storing the thumbnail URL (default: `thumbnail_url_ssm`).
- **config.featured_image_thumb_size** (array of integers) - The dimensions [width, height] for featured image thumbnails.
- **config.featured_image_masthead_size** (array of integers) - The dimensions [width, height] for featured image mastheads.
- **config.uploader_storage** (symbol) - The storage backend for uploads (e.g., `:file`, `:aws`).
- **config.analytics_provider** (class) - The analytics provider class (e.g., `Spotlight::Analytics::Ga`).
- **config.ga_property_id** (string) - Google Analytics Property ID.
- **config.i18n_locales** (hash) - A mapping of locale codes to display names.
- **config.solr_batch_size** (integer) - Batch size for Solr operations (default: 20).
- **config.bulk_actions_batch_size** (integer) - Batch size for bulk actions (default: 1000).

### Request Example
```ruby
Spotlight::Engine.config.tap do |config|
  config.user_class = '::User'
  config.exhibit_themes = ['default', 'custom_theme']
  config.solr_fields.string_suffix = '_ssim'
end
```
```

--------------------------------

### Create New Rails App with Spotlight (JS Bundling)

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

This command bootstraps a new Rails application with Spotlight using jsbundling-rails with esbuild for JavaScript and Bootstrap for CSS. It utilizes a template from the Spotlight GitHub repository.

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

--------------------------------

### Create New Rails App with Spotlight (Importmap)

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

This command bootstraps a new Rails application with Spotlight using importmap-rails for JavaScript management and Bootstrap for CSS. It uses a template from the Spotlight GitHub repository.

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

--------------------------------

### Build JavaScript Bundle with npm

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

This command runs the npm script to build the JavaScript bundle for Spotlight. This process compiles the JavaScript sources into a single file for use in the application.

```bash
npm run prepare
```

--------------------------------

### Spotlight Engine Configuration Options (Ruby)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Illustrates common configuration options for the Spotlight::Engine within a Rails initializer file. Covers settings for user models, controllers, themes, Solr field mappings, upload fields, IIIF integration, image sizes, storage, analytics, and locales.

```ruby
# config/initializers/spotlight_initializer.rb

Spotlight::Engine.config.tap do |config|
  # User model class
  config.user_class = '::User'

  # Catalog controller class
  config.catalog_controller_class = '::CatalogController'

  # Available exhibit themes
  config.exhibit_themes = ['default', 'custom_theme']

  # Solr field suffixes
  config.solr_fields.prefix = ''
  config.solr_fields.string_suffix = '_ssim'      # Multi-valued string
  config.solr_fields.text_suffix = '_tesim'       # Full-text searchable
  config.solr_fields.boolean_suffix = '_bsi'      # Boolean

  # Upload form fields
  config.upload_fields = [
    Spotlight::UploadFieldConfig.new(
      field_name: 'spotlight_upload_title',
      label: 'Title',
      form_field_type: :text_field
    ),
    Spotlight::UploadFieldConfig.new(
      field_name: 'spotlight_upload_description',
      label: 'Description',
      form_field_type: :text_area
    )
  ]

  # IIIF configuration
  config.iiif_service = Spotlight::RiiifService
  config.iiif_manifest_field = 'iiif_manifest_url_ssi'
  config.thumbnail_field = 'thumbnail_url_ssm'

  # Image sizes
  config.featured_image_thumb_size = [400, 300]
  config.featured_image_masthead_size = [1800, 180]

  # CarrierWave storage
  config.uploader_storage = :file  # or :aws for S3

  # Analytics
  config.analytics_provider = Spotlight::Analytics::Ga
  config.ga_property_id = 'GA-123456'

  # Locales
  config.i18n_locales = {
    en: 'English',
    es: 'Spanish',
    fr: 'French',
    de: 'German'
  }

  # Performance tuning
  config.solr_batch_size = 20
  config.bulk_actions_batch_size = 1000
end
```

--------------------------------

### Run Database Migrations for Spotlight

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

This command executes the necessary database migrations for Spotlight to set up its required tables and schema within your Rails application.

```bash
SKIP_TRANSLATION=1 rake db:migrate
```

--------------------------------

### Create About Pages

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Shows how to create 'about' pages, which are typically displayed in the exhibit's 'About' section. This includes setting the main about page for the exhibit.

```ruby
# About pages appear in the "About" section
about_page = exhibit.about_pages.create!(
  title: 'Curator Statement',
  slug: 'curator',
  published: true,
  content: [
    {
      type: 'text',
      data: {
        text: '## About This Collection\n\nCurated by Dr. Smith...', ...,
        format: 'markdown'
      }
    }
  ].to_json
)

# Set as main about page
exhibit.update(main_about_page: about_page)
```

--------------------------------

### Publishing Spotlight JavaScript Package to npm

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

Steps to update package.json, build the JavaScript bundle, and publish the package to npm. This process is necessary when changes are made to the JavaScript code.

```shell
npm run prepare
npm i --package-lock-only
npm publish
```

--------------------------------

### Create Exhibit with Custom Theme and Configuration (Ruby)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Programmatically creates a Spotlight exhibit, specifying a custom theme and configuring facets. It also shows how to update the Blacklight configuration for index and show pages, and set per-page display options.

```ruby
exhibit = Spotlight::Exhibit.create!(
  title: 'Historical Maps Collection',
  slug: 'maps',
  published: true,
  theme: 'custom_theme',  # Must be in Spotlight::Engine.config.exhibit_themes
  facets: ['geographic_facet', 'decade_facet', 'format_facet']
)

# Configure search behavior
exhibit.blacklight_configuration.update(
  index: {
    title_field: 'title_display',
    display_type_field: 'format'
  },
  show: {
    display_type_field: 'format'
  },
  per_page: [20, 50, 100],
  default_per_page: 20
)
```

--------------------------------

### Initialize Spotlight Test App (Rails Command)

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

Initializes the Spotlight test application with user-provided credentials for the admin user. This offers more flexibility than the default seeding task. It requires the test app to be generated.

```ruby
bin/rails spotlight:initialize
```

--------------------------------

### Running Spotlight Tests with Docker or External Solr

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

Commands to run Spotlight tests when Solr is managed separately, either via Docker or a pre-running solr_wrapper instance. This involves generating the test application, preparing assets, and then running RSpec.

```shell
docker compose up -d # If using Docker for Solr
rake engine_cart:generate
rake spotlight:fixtures
cd .internal_test_app && rake spec:prepare && cd - # Not needed if dev server was run
rspec
```

--------------------------------

### Access and Use IIIF Manifests (Ruby)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Demonstrates how to retrieve the IIIF manifest URL for an uploaded item from its SolrDocument and then fetch and parse the manifest using Faraday. It also shows how to embed a IIIF viewer block within a page's content.

```ruby
# Uploaded items automatically get IIIF manifests
document = SolrDocument.find('uploaded-item-id')

# Manifest URL available in Solr
manifest_url = document['iiif_manifest_url_ssi']
# => "http://localhost:3000/my-exhibit/catalog/uploaded-item-id/manifest"

# Fetch manifest
require 'faraday'
response = Faraday.get(manifest_url)
manifest = JSON.parse(response.body)

puts "Label: #{manifest['label']}"
puts "Canvases: #{manifest['sequences'][0]['canvases'].count}"

# Add IIIF viewer block to page
page.content = [
  {
    type: 'iiif_viewer',
    data: {
      item_id: document.id,
      title: 'View in Detail',
      manifest_url: document['iiif_manifest_url_ssi']
    }
  }
].to_json
page.save
```

--------------------------------

### Add Spotlight to Existing Rails App

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Integrates Spotlight into an existing Rails application by running the provided Rails application template.

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

--------------------------------

### Grant Super Admin Role (Ruby)

Source: https://github.com/projectblacklight/spotlight/wiki/User-roles

This snippet demonstrates how to promote a user to a site-wide super administrator by creating a role entry in the `roles` table. It shows checking the superadmin status before and after the role is granted. No external dependencies are required beyond the application's user and role models.

```ruby
user = User.first
user.superadmin?
# => false

user.roles.create(role: 'admin', resource: Spotlight::Site.instance)
user.superadmin?
# => true
```

--------------------------------

### Releasing Spotlight Gem to Rubygems and GitHub

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

Commands to commit version changes and then release the Spotlight gem to both Rubygems and GitHub. This is part of the new version release process.

```shell
git commit -am "Bump version to X.X.X"
bundle exec rake release
```

--------------------------------

### Create Basic Exhibit Programmatically (Ruby)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Creates a new Spotlight exhibit with basic attributes like title, slug, subtitle, and description. It also demonstrates how to grant curator access to a user by creating a role.

```ruby
# Create the exhibit
exhibit = Spotlight::Exhibit.create!(
  title: 'Digital Art Collection',
  slug: 'digital-art',
  subtitle: 'Contemporary works from our archives',
  description: 'A curated selection of digital artwork spanning 2010-2024',
  published: true
)

# Grant curator role to a user
exhibit.roles.create!(
  user: User.find_by(email: 'curator@example.com'),
  role: 'admin'  # Options: 'admin', 'curator', 'viewer'
)

# Access the exhibit at: http://localhost:3000/digital-art
```

--------------------------------

### Seed Admin User for Test App (Rake Task)

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

Seeds the test application with an initial administrator user using default credentials. This is a quick way to set up a basic admin account for testing. It requires the test app to be generated first.

```ruby
rake spotlight:seed_admin_user
```

--------------------------------

### Create Custom Exhibit Menu Item Controller (BlorghController)

Source: https://github.com/projectblacklight/spotlight/wiki/Adding-new-navigation-menu-items

This Ruby code defines a `BlorghController` that subclasses `Spotlight::ApplicationController`. It includes a `before_action` filter to authorize read access to the current exhibit, ensuring the page is only visible when the exhibit is published. The `show` action is a simple placeholder.

```ruby
class BlorghController < Spotlight::ApplicationController
  before_action do
    authorize!(:read, current_exhibit)
  end

  def show; end
end
```

--------------------------------

### Create Feature Page with Rich Content

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Demonstrates the creation of a feature page with a variety of content blocks, including headings, formatted text, lists of Solr documents, and embedded browse categories. This enables the construction of complex, multi-faceted presentation pages.

```ruby
# Create parent feature page
page = exhibit.feature_pages.create!(
  title: 'Impressionism Movement',
  slug: 'impressionism',
  published: true,
  weight: 10,  # Display order
  content: [
    {
      type: 'heading',
      data: { text: 'The Birth of Impressionism' }
    },
    {
      type: 'text',
      data: {
        text: 'Impressionism emerged in France in the 1860s...', ...,
        format: 'markdown'
      }
    },
    {
      type: 'solr_documents',
      data: {
        item_ids: ['id1', 'id2', 'id3'],
        title: 'Featured Works',
        text: 'Key paintings from the movement'
      }
    },
    {
      type: 'browse',
      data: {
        search_id: search.id,
        heading: 'More Impressionist Works'
      }
    }
  ].to_json
)

# Page is accessible at:
# http://localhost:3000/your-exhibit/feature/impressionism
```

--------------------------------

### Configure Custom IIIF Service (Ruby)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Explains how to configure Spotlight to use a custom IIIF service by setting `Spotlight::Engine.config.iiif_service`. It outlines the required methods for a custom service class, including `info`, `thumbnail_url`, and `manifest_url`.

```ruby
# In config/initializers/spotlight_initializer.rb
Spotlight::Engine.config.iiif_service = MyCustomIiifService

# Custom service class must implement:
# - info(id) - returns IIIF info.json
# - thumbnail_url(id, size) - returns thumbnail URL
# - manifest_url(id) - returns manifest URL

# Default uses Spotlight::RiiifService (RIIIF gem)
```

--------------------------------

### Configure Blacklight with oEmbed Field in Ruby

Source: https://github.com/projectblacklight/spotlight/wiki/Case-Study:-exhibits.stanford.edu

Configures the Blacklight interface to use a specific field for oEmbed content and inserts a custom partial for rendering oEmbed or OSD (OpenSeadragon) content. This relies on the blacklight-oembed gem.

```ruby
class CatalogController < ApplicationController
  include Blacklight::Controller
  include Blacklight::Catalog

  configure_blacklight do |config|
    config.show.oembed_field = :url_fulltext
    config.show.partials.insert(1, :osd_or_embed)
  end
end
```

--------------------------------

### Add Custom Resource Form to Initializer (Ruby)

Source: https://github.com/projectblacklight/spotlight/wiki/Resource-Scenarios

Configures Spotlight to include a specific form partial for custom resources. This ensures that the defined form fields for the custom resource (e.g., `ExampleResource`) are rendered when curators manage resources within an exhibit.

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

--------------------------------

### Configure Spotlight Catalog Controller for SUL Embed Viewer

Source: https://github.com/projectblacklight/spotlight/wiki/Case-Study:-exhibits.stanford.edu

This Ruby code snippet demonstrates how to configure the CatalogController in a Spotlight application to integrate with the SUL Embed viewer. It involves adding a show partial to the Blacklight configuration, likely to display embedded content from SUL resources.

```ruby
class CatalogController < ApplicationController
  include Blacklight::Catalog

  # ... other configuration ...

  configure_blacklight do |config|
    # ... other config ...
    config.show.partials << 'show_embed'
  end
end
```

--------------------------------

### Bulk CSV Upload for Resources (Ruby)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Handles bulk uploading of resources from a CSV file to a Spotlight exhibit. The CSV should contain columns like 'url', 'title', 'description', and custom fields. The code creates a temporary CSV file, uploads it, and initiates the indexing process.

```ruby
# Prepare CSV file with columns: url, title, description, custom_field
csv_content = <<~CSV
  url,title,description,date,artist
  https://example.com/item1.jpg,Portrait,Study in blue,1890,Artist A
  https://example.com/item2.jpg,Landscape,Mountain view,1895,Artist B
CSV

# Create CSV upload resource
csv_file = Tempfile.new(['upload', '.csv'])
csv_file.write(csv_content)
csv_file.rewind

resource = Spotlight::Resources::CsvUpload.create!(
  exhibit: exhibit
)
resource.url = csv_file
resource.save_and_index

# Monitor progress
resource.reindex_progress.total    # Total items
resource.reindex_progress.completed # Items processed
```

--------------------------------

### Define Custom Resource Model and Indexing Pipeline (Ruby)

Source: https://github.com/projectblacklight/spotlight/wiki/Resource-Scenarios

Defines a custom resource model inheriting from Spotlight::Resource and customizes its indexing pipeline. This allows for tailored data extraction and transformation before indexing resources into Solr, including calling a `to_solr` method.

```ruby
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
```

--------------------------------

### Configure Spotlight Exhibit Themes

Source: https://github.com/projectblacklight/spotlight/wiki/Creating-a-theme

This code demonstrates how to add a new theme name to the Spotlight engine's configuration. This makes the specified theme available for use in exhibits. It involves updating the `config/initializers/spotlight_initializer.rb` file.

```ruby
Spotlight::Engine.config.exhibit_themes = %w[nothumb default]
```

--------------------------------

### Upload Single File with Metadata (Ruby)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Uploads a single file (e.g., an image) to a Spotlight exhibit and associates custom metadata with it. The code prepares the resource, attaches the file, saves, and indexes it, with a check for successful persistence and indexing progress.

```ruby
# Upload an image file with custom metadata
resource = Spotlight::Resources::Upload.create!(
  exhibit: exhibit,
  data: {
    'spotlight_upload_title_tesim' => 'Landscape Painting',
    'spotlight_upload_description_tesim' => 'Oil on canvas, circa 1892',
    'spotlight_upload_attribution_tesim' => 'Artist: Jane Smith',
    'spotlight_upload_date_tesim' => '1892'
  }
)

# Attach the actual file
resource.upload = File.open('/path/to/image.jpg')
resource.save_and_index

# Track indexing progress
if resource.persisted?
  puts "Resource #{resource.id} created and queued for indexing"
  # Check job status via resource.reindex_progress
end
```

--------------------------------

### Manage User Roles for Exhibits and Site (Ruby)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Shows how to manage user roles within Spotlight, including adding curators to an exhibit, assigning site administrator privileges, removing roles, and listing all curators for an exhibit.

```ruby
# Add curator role
exhibit.roles.create!(
  user: User.find_by(email: 'curator@example.com'),
  role: 'curator'
)

# Add site administrator
Spotlight::Site.instance.roles.create!(
  user: User.find_by(email: 'admin@example.com'),
  role: 'admin'
)

# Remove role
role = exhibit.roles.find_by(user: user)
role.destroy

# List all curators
exhibit.users.joins(:roles).where(spotlight_roles: { role: 'curator' })
```

--------------------------------

### Download Metadata CSV Template (Bash)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Downloads a CSV template file from the Spotlight exhibit's bulk update endpoint. This template can be edited to provide metadata updates for documents, including item ID, title, visibility, custom fields, and tags. Dependencies: curl.

```bash
# Download current metadata as CSV template
curl -o template.csv \
  "http://localhost:3000/my-exhibit/bulk_updates/download_template"

# Edit CSV with updates:
# Item ID,Item Title,Visibility,spotlight_custom_field,Tag: genre
# id1,New Title,private,Updated value,painting
# id2,Another Title,public,Another value,sculpture
```

--------------------------------

### Grant Exhibit Role (Ruby)

Source: https://github.com/projectblacklight/spotlight/wiki/User-roles

This code illustrates how to grant a user a specific role (e.g., 'admin') for a particular exhibit. It involves creating a role entry associated with the user and the exhibit resource. The `Spotlight::Exhibit` model is used to retrieve an exhibit instance.

```ruby
exhibit = Spotlight::Exhibit.first
user.roles.create(role: 'admin', resource: exhibit)
```

--------------------------------

### Convert Atom Feed to CSV for Spotlight Upload

Source: https://github.com/projectblacklight/spotlight/wiki/Case-Study:-basic-digital-archive

This Ruby script parses an Atom feed, extracts relevant content, and transforms it into a CSV format compatible with Spotlight's bulk upload. It utilizes Nokogiri for XML and HTML parsing. Dependencies include Nokogiri and CSV.

```ruby
doc = open('http://stanislausriver.org/items/browse?output=atom').read
ns = { atom: "http://www.w3.org/2005/Atom" }

h = Nokogiri::XML(doc).xpath('//atom:entry', ns).map do |x|
  content = Hash[Nokogiri::HTML(x.xpath("atom:content", ns).text).css('div').map do |d|
      [d.css('h3').text, d.css('.element-text').text]
  end];

  {
    full_title_tesim: x.xpath('atom:title', ns).text,
    url: x.xpath('atom:link[contains(@rel, "enclosure")]/@href', ns).text,
    spotlight_upload_attribution_tesim: content['Rights'],
    spotlight_upload_date_tesim: content['Date'],
    "exhibit_default-exhibit_creator_ssim" => content['Creator'],
    "exhibit_default-exhibit_source_ssim" => content['Source'],
    "exhibit_default-exhibit_type_ssim" => content['Type']
  }
end

puts CSV.generate { |csv| csv << h.first.keys; _.each { |x| csv << x.values } }
```

--------------------------------

### Create Browse Category with Full-Text Search

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Shows how to create a browse category that performs a full-text search based on keywords. This allows users to find items matching specific terms across designated search fields.

```ruby
# Create a search for items matching keywords
search = exhibit.searches.create!(
  title: 'Portraits',
  published: true,
  query_params: {
    q: 'portrait OR self-portrait',
    search_field: 'all_fields',
    sort: 'score desc'
  }
)

# Get results count
search.count  # Returns number of matching documents
```

--------------------------------

### Make Documents Public in a Collection (Ruby)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Demonstrates how to make all documents within a specific collection public using both iterative and bulk actions. It iterates through documents in batches for efficiency and shows how to use Spotlight's bulk actions for changing visibility.

```ruby
collection_docs = SolrDocument.where(collection: 'Prints Collection')

collection_docs.each_slice(100) do |batch|
  batch.each do |doc|
    doc.make_public!(exhibit)
  end
end

Spotlight::BulkActions.change_visibility(
  exhibit: exhibit,
  document_ids: collection_docs.map(&:id),
  visibility: 'public'
)
```

--------------------------------

### Create Hierarchical Pages (Parent/Child)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Explains how to create parent and child feature pages to establish a hierarchical structure for content. This is useful for organizing related pages and creating nested navigation within an exhibit.

```ruby
parent_page = exhibit.feature_pages.create!(
  title: 'Art Movements',
  slug: 'movements',
  published: true
)

# Create child pages
child_page = exhibit.feature_pages.create!(
  title: 'Impressionism',
  slug: 'impressionism',
  parent_page: parent_page,
  published: true
)

# Navigation automatically shows hierarchy:
# Art Movements
#   → Impressionism
```

--------------------------------

### Organize Searches into Groups

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Details how to create groups for browse categories (saved searches) and associate searches with these groups. This enables hierarchical organization of browsing navigation, improving user experience.

```ruby
# Create groupings for browse categories
decades_group = exhibit.groups.create!(
  title: 'Browse by Decade',
  slug: 'decades',
  published: true,
  weight: 1  # Display order
)

# Associate searches with group
search_1890s = exhibit.searches.find_by(slug: '1890s')
search_1900s = exhibit.searches.find_by(slug: '1900s')

search_1890s.groups << decades_group
search_1900s.groups << decades_group

# Groups appear in browse navigation
exhibit.groups.published.each do |group|
  puts "Group: #{group.title}"
  group.searches.each do |s|
    puts "  - #{s.title} (#{s.count} items)"
  end
end
```

--------------------------------

### Reindex Entire Exhibit Asynchronously (Ruby)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Shows how to trigger a full reindex of an exhibit asynchronously and how to monitor its progress. It includes checking the total documents, completed count, percentage, and the current status (pending, in progress, completed, failed).

```ruby
# Trigger full reindex (asynchronous)
exhibit.reindex_later(current_user)

# Monitor reindex progress
progress = exhibit.reindex_progress
puts "Total: #{progress.total}"
puts "Completed: #{progress.completed}"
puts "Percentage: #{progress.percentage}%"

# Check if reindex is running
if progress.pending? || progress.in_progress?
  puts "Reindexing..."
elsif progress.completed?
  puts "Reindex complete!"
elsif progress.failed?
  puts "Reindex failed: #{progress.errors}"
end
```

--------------------------------

### Exhibit Management Endpoints

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Endpoints for managing the exhibit itself, including export, import, and reindexing.

```APIDOC
## GET /my-exhibit/exhibit

### Description
Exports the entire exhibit configuration and content as a JSON file.

### Method
GET

### Endpoint
`/my-exhibit/exhibit`

### Request Example
```bash
curl "http://localhost:3000/my-exhibit/exhibit" > exhibit.json
```

## POST /my-exhibit/import

### Description
Imports exhibit data from a JSON file. This operation typically requires authentication.

### Method
POST

### Endpoint
`/my-exhibit/import`

### Parameters
#### Request Body
- **JSON File** - Required - The exhibit data to import, provided as a JSON file.

### Request Example
```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d @exhibit.json \
  "http://localhost:3000/my-exhibit/import"
```

## POST /my-exhibit/reindex

### Description
Triggers a reindexing process for the exhibit's content in Solr.

### Method
POST

### Endpoint
`/my-exhibit/reindex`

### Request Example
```bash
curl -X POST "http://localhost:3000/my-exhibit/reindex"
```

## GET /my-exhibit/resources/monitor.json

### Description
Monitors the status and progress of resource indexing within the exhibit.

### Method
GET

### Endpoint
`/my-exhibit/resources/monitor.json`

### Request Example
```bash
curl "http://localhost:3000/my-exhibit/resources/monitor.json"
```
```

--------------------------------

### Generate Spotlight Scaffold Resource (Rails Console)

Source: https://github.com/projectblacklight/spotlight/wiki/Resource-Scenarios

Uses the Spotlight Rails generator to create the necessary model, view, and controller files for a new custom resource type. This command initiates the basic structure for handling 'on-demand' resources within an exhibit.

```bash
bundle exec rails generate spotlight:scaffold_resource example
```

--------------------------------

### Clone Exhibit (Ruby)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Clones an existing exhibit by exporting its data to JSON and then importing it into a newly created exhibit. This provides a complete copy of the exhibit configuration and content. Resources are reindexed after cloning. Dependencies: Spotlight::Exhibit, Spotlight::ExhibitImportExportService.

```ruby
# Export source exhibit
source = Spotlight::Exhibit.find('source-exhibit')
export_service = Spotlight::ExhibitImportExportService.new(source)
data = export_service.as_json

# Import to new exhibit
clone = Spotlight::Exhibit.create!(
  title: "#{source.title} (Copy)",
  slug: "#{source.slug}-copy"
)
import_service = Spotlight::ExhibitImportExportService.new(clone)
import_service.from_hash!(data)

# Reindex resources
clone.reindex_later(current_user)
```

--------------------------------

### Add Fixture Data to Solr (Rake Task)

Source: https://github.com/projectblacklight/spotlight/blob/main/README.md

This task adds fixture data to the Solr index, which is useful for testing and development. It requires the Rake environment to be set up.

```ruby
rake spotlight:fixtures
```

--------------------------------

### Access Harvested IIIF Manifests

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Iterates through harvested IIIF manifests for a given resource and prints their labels. This is useful for accessing and displaying metadata from IIIF sources.

```ruby
resource.iiif_manifests.each do |manifest|
  puts "Manifest: #{manifest['label']}"
end
```

--------------------------------

### Configure Default Exhibit Menu Items (spotlight_initializer.rb)

Source: https://github.com/projectblacklight/spotlight/wiki/Adding-new-navigation-menu-items

This Ruby code snippet configures the default main navigation items for all new exhibits created within Spotlight. By adding `:blorgh` to `Spotlight::Engine.config.exhibit_main_navigation`, the custom menu item will be automatically included in the navigation for every new exhibit.

```ruby
Spotlight::Engine.config.exhibit_main_navigation = [:curated_features, :browse, :about, :blorgh]
```

--------------------------------

### Create a Formable H2 Block (JavaScript)

Source: https://github.com/projectblacklight/spotlight/wiki/Page-widgets

This JavaScript code defines a new Sir-Trevor block for creating H2 headings with a text input for the title. It enables the 'formable' plugin, allowing for easy serialization and deserialization of form data. The block includes a text input field in its template.

```javascript
SirTrevor.Blocks.H2 = (function(){

  return SirTrevor.Block.extend({
    type: "h2",

    title: function() { return "H2"; },

    icon_name: "h2",

    formable: true, // <-- this enables the formable plugin.
    
    editorHTML: function() { 
      return _.template(this.template, this)(this);
    },

    template: '<input type="text" name="title" />'
  });
})();

```

--------------------------------

### Upload and Apply Metadata Updates via CSV (Ruby)

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Uploads a CSV file containing metadata updates to the exhibit's bulk update service. The changes are processed asynchronously via a background job. The progress and any errors can be monitored through job trackers. Dependencies: Spotlight::BulkUpdateJob, File.

```ruby
# Upload and apply changes
csv_file = File.open('updated_metadata.csv')
bulk_update = exhibit.bulk_updates.create!

bulk_update.file = csv_file
bulk_update.save

# Process asynchronously
Spotlight::BulkUpdateJob.perform_later(bulk_update, exhibit, current_user)

# Monitor progress
bulk_update.job_trackers.each do |tracker|
  puts "Status: #{tracker.status}"
  puts "Progress: #{tracker.progress}"
  puts "Errors: #{tracker.errors}" if tracker.errors.any?
end
```

--------------------------------

### Bulk Operations Endpoints

Source: https://context7.com/projectblacklight/spotlight/llms.txt

Endpoints for performing batch operations on multiple documents, such as changing visibility or managing tags.

```APIDOC
## POST /my-exhibit/bulk_actions/change_visibility

### Description
Changes the visibility setting for a list of documents.

### Method
POST

### Endpoint
`/my-exhibit/bulk_actions/change_visibility`

### Parameters
#### Request Body
- **document_ids** (array of strings) - Required - A list of document IDs to modify.
- **visibility** (string) - Required - The desired visibility setting (e.g., 'private', 'public').

### Request Example
```json
{
  "document_ids": ["id1", "id2"],
  "visibility": "private"
}
```

## POST /my-exhibit/bulk_actions/add_tags

### Description
Adds one or more tags to a list of documents.

### Method
POST

### Endpoint
`/my-exhibit/bulk_actions/add_tags`

### Parameters
#### Request Body
- **document_ids** (array of strings) - Required - A list of document IDs to tag.
- **tags** (array of strings) - Required - A list of tags to add to the documents.

### Request Example
```json
{
  "document_ids": ["id1", "id2"],
  "tags": ["featured"]
}
```

## POST /my-exhibit/bulk_actions/remove_tags

### Description
Removes one or more tags from a list of documents.

### Method
POST

### Endpoint
`/my-exhibit/bulk_actions/remove_tags`

### Parameters
#### Request Body
- **document_ids** (array of strings) - Required - A list of document IDs to untag.
- **tags** (array of strings) - Required - A list of tags to remove from the documents.

### Request Example
```json
{
  "document_ids": ["id1"],
  "tags": ["outdated"]
}
```
```