blacklight-spotlight 5.1.0 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08d617eac0c85933f2ac4c6f0e50c82f8e6880b7296edf8730b0978aa9d81d7f'
-  data.tar.gz: 31c89e414dfd108a7bb02c5a16c64f7d1f8bbfea9c8c88e5bde93a8748475e0a
+  metadata.gz: 84efdb53b56ea18d71d5efbb5c68a2d5865b9591eb766236cf90e201200fc31a
+  data.tar.gz: ef61c3e200b76c193c22e0ba4fbf513c19f5dbfac7ddfd1e84c88c91e4e6b31d
 SHA512:
-  metadata.gz: a229baf50bb0314fde2767c5200017e254a9325d83a9a8722f2177540b9c5bf3a9d567f07df7b18485dee9752de4fc613d3ace636445229d3257570105cade36
-  data.tar.gz: 338366a9da9b8321748c957a31fb5ef210b5d2c95fb2594be0fa01d51e2a8cba0adc22736d0e1665fa1d4e30a319a1987bdcb9b2f6b6070eb8b965549d12dbf3
+  metadata.gz: 6a736b3c916d2ca85d1e320b98de576fb93941bad0cb9d8c5a280912a8759f8c118780a115b7a25d65ecabe3428bfc1e47ef3a9d38d49cdd35b952869898f73a
+  data.tar.gz: 786bdc118fdc240bac38b978feae84369a45e25feba6467506c39025b7bd23c1f154bc32ea18cb19cd4351d7733137ba291c469095e23a6e92c1f96480d23133

data/README.md

@@ -5,17 +5,21 @@ spotlight
 
 Spotlight is open source software that enables librarians, curators, and other content experts to easily build feature-rich websites that showcase collections and objects from a digital repository, uploaded items, or a combination of the two. Spotlight is a plug-in for [Blacklight](https://github.com/projectblacklight/blacklight), an open source, Ruby on Rails Engine that provides a basic discovery interface for searching an Apache Solr index.
 
-Read more about what Spotlight is, our motivations for creating it, and how to install and configure it in the [wiki pages](https://github.com/projectblacklight/spotlight/wiki). You might also want to take a look at our demo videos, especially the [tour of a completed Spotlight exhibit](https://www.youtube.com/watch?v=_A7vTbbiF4g) and the walkthrough of [building an exhibit with Spotlight](https://www.youtube.com/watch?v=qPJtgajJ4ic).
+In addition to the information found below, you can read more about what Spotlight is, our motivations for creating it, and how to configure it in the [wiki pages](https://github.com/projectblacklight/spotlight/wiki). You might also want to take a look at our demo videos, especially the [tour of a completed Spotlight exhibit](https://www.youtube.com/watch?v=_A7vTbbiF4g) and the walkthrough of [building an exhibit with Spotlight](https://www.youtube.com/watch?v=qPJtgajJ4ic).
+
+If you have questions or are interested in contributing, please reach out to the [Spotlight Community](#spotlight-community)
 
 ## Requirements
 
-1. [Ruby](https://www.ruby-lang.org/) 3.1+
+1. [Ruby](https://www.ruby-lang.org/) 3.2+
 2. [Ruby on Rails](https://rubyonrails.org/) 7.1+
 3. Java (11 or greater) *for Solr*
 4. ImageMagick (http://www.imagemagick.org/script/index.php) due to [carrierwave](https://github.com/carrierwaveuploader/carrierwave#adding-versions)
 
 ## Installation
 
+The following installation instructions are for setting up a new instance of Spotlight. To set up an environment for Spotlight development, see [Developing Spotlight](#developing-spotlight).
+
 To bootstrap a new Rails application using [importmap-rails](https://github.com/rails/importmap-rails):
 
 ```
@@ -70,59 +74,182 @@ Spotlight introduces functionality that depends on being able to send emails to
 
 See the [Spotlight wiki](https://github.com/projectblacklight/spotlight/wiki) for more detailed information on configuring Spotlight.
 
-# Developing Spotlight
+## Translations
+
+Spotlight ships with [`i18n-tasks`](https://github.com/glebm/i18n-tasks) to help manage translations. To run a translation health check:
+
+```sh
+bundle exec i18n-tasks health
+```
+
+See [developer-facing instructions for enabling translation](https://github.com/projectblacklight/spotlight/wiki/Translations) on the wiki.
+
+## Updating the JavaScript bundle
+
+The JavaScript is built by npm from sources in `app/javascript` into a bundle
+in `app/assets/javascripts/spotlight/spotlight.js`. This file should not be edited
+by hand as any changes would be overwritten.  When any of the JavaScript
+components in the gem are changed, this bundle should be rebuilt with the
+following steps:
+1. [Install npm](https://www.npmjs.com/get-npm)
+2. Run `npm install` to download dependencies
+3. Run `npm run prepare` to build the bundle
+4. If you are releasing a new version of the gem, follow the release instructions below.
+
+## Releasing a new version and publishing the JavaScript
+
+You only need to update `package.json` and prepare/publish the JavaScript package for npm if there are changes to the JavaScript.
+1. Edit `version.rb` and `package.json` to set the new version
+2. Run `npm run prepare` to build the JavaScript bundle
+3. Run `npm i --package-lock-only` to update the version in `package-lock.json`
+4. Commit the changes e.g. `git commit -am "Bump version to X.X.X"`
+5. Push the release to rubygems and GitHub: `bundle exec rake release`
+6. Run `npm publish` to push the JavaScript package to https://npmjs.org/package/spotlight-frontend
 
-## Branches
+See [Updating the JavaScript bundle](#updating-the-javascript-bundle) above for more details.
+
+## Developing Spotlight
+
+### Branches
 
 * The `main` branch is for development of the upcoming 5.0 release.
 * The `4.x` series is on the [release-4.x](https://github.com/projectblacklight/spotlight/tree/release-4.x) branch for backports of features and bug fixes.
 
-## Spotlight
+### Tooling
+
+* Spotlight is a Rails engine and needs to be used in the context of a Rails application. We use [engine_cart](https://github.com/cbeer/engine_cart) to create an internal test application at `.internal_test_app/`. 
+* Spotlight relies on Solr for its integration tests and to run a development instance. [solr_wrapper](https://github.com/cbeer/solr_wrapper) allows us to provide terse commands for development and testing. For more granular control, you can run Solr in Docker, then execute services and processes individually.
+* Spotlight's `rake spotlight:server` and `rake ci` tasks use engine_cart and Solr automatically, but you can refer to [engine_cart](https://github.com/cbeer/engine_cart) and [solr_wrapper](https://github.com/cbeer/solr_wrapper) documentation to work with these tools outside of those rake tasks.
+
+### Initial setup
+
+1. Install the [requirements above](#requirements). Note: You do not need to install Java if you plan to run Solr in Docker. 
+2. Clone the spotlight repository locally and `cd` into it.
+3. Install the Ruby gems used by spotlight: `bundle install`.
 
-* is a Rails engine and needs to be used in the context of a Rails application. We use [engine_cart](https://github.com/cbeer/engine_cart) to create an internal test application at .internal_test_app/
-* uses Solr as part of its integration tests. We use [solr_wrapper](https://github.com/cbeer/solr_wrapper) to manage the Solr instance used for development and test.
+Note: if your system is confused by conflicting gem versions, you may need to add "bundle exec" to the beginning of each command below, e.g. `bundle exec rake engine_cart:generate`. This ensures that the command is run in the context of bundler's gem version management.
 
-See more detailed instructions for development environment setup at ["Contributing to Spotlight"](https://github.com/projectblacklight/spotlight/wiki/Contributing-to-Spotlight)
+### Run a development server
 
-## Run a development server
+After following one of the instructions below, visit http://localhost:3000. A Solr instance will be running on port 8983. When using importmap (the default configuration), JavaScript changes in development should not require [bundling](#updating-the-javascript-bundle) or a server restart.
 
-### With EngineCart
+#### With solr_wrapper
+
+The following rake task will build a Spotlight-based application, start Solr with solr_wrapper, and run the built-in rails server. In the process, you will be prompted to create an admin user and password.
+
+```sh
+rake spotlight:server
 ```
-$ rake spotlight:server
+
+Alternatively, you can use [individual commands](#individual-commands) to start Solr separately and set everything else up.
+
+```sh
+solr_wrapper # Run in separate tab
+rake engine_cart:generate
+rake spotlight:fixtures
+cd .internal_test_app
+bin/rails spotlight:initialize
+bin/dev
 ```
 
-Then visit http://localhost:3000. A Solr instance will be running on port 8983. When using importmap (the default configuration), JavaScript changes in development should not require [bundling](#updating-the-javascript-bundle) or a server restart.
+#### With Docker
 
-### With Docker
+The following will run Solr in Docker and then use individual commands to set up a running development server.
 
 ```sh
-# because of how docker compose handles named images, running `docker compose up --build` will error when the Rails images have not been built locally
-docker compose build
-docker compose up
+docker compose up -d
+rake engine_cart:generate
+rake spotlight:fixtures
+cd .internal_test_app
+rake spotlight:seed_admin_user
+bin/dev
 ```
 
-## Tests
+### Run tests
 
-### Run all the tests:
+#### With solr_wrapper
 
+The following rake task will build a Spotlight-based application, start Solr, run the tests, and then shut down Solr when the tests are finished. Solr should not be running already when you run this.
+```sh
+rake
 ```
-$ rake
+
+#### With Docker (or solr_wrapper, if Solr is started separately)
+
+If you're using Solr on Docker, run `docker compose up -d` to start Solr if you haven't already. Once you have Solr running (either on Docker or with solr_wrapper), run the tests using the following commands:
+```sh
+rake engine_cart:generate
+rake spotlight:fixtures
+cd .internal_test_app && rake spec:prepare && cd - # not needed if you ran the dev server
+rspec
 ```
 
-This utilizes Solr and the testing rails app automatically.
+Using rspec directly allows you to run individual test files / lines.
 
-## Translations
+The `spec:prepare` task generates css assets for use by the tests. You can delete these assets with `rake assets:clobber`.
 
-Spotlight ships with [`i18n-tasks`](https://github.com/glebm/i18n-tasks) to help manage translations. To run a translation health check:
+Once you are set up, you can also run `rubocop` to enforce consistent coding style.
 
-```sh
-$ bundle exec i18n-tasks health
+
+### Individual commands
+
+#### Using solr_wrapper
+
+Start Solr with solr_wrapper: 
+```
+solr_wrapper
+```
+Reset Solr using solr_wrapper to a pristine state (e.g. remove Solr docs, core, etc.):
+```
+solr_wrapper clean
+```
+Note: Sometimes solr doesn't shut down properly.  You can check by seeing if solr is running:
+```
+ps -eaf | grep solr
 ```
 
-See [developer-facing instructions for enabling translation](https://github.com/projectblacklight/spotlight/wiki/Translations) on the wiki.
+#### Using test fixtures
+
+Add fixture data to Solr:
+```
+rake spotlight:fixtures
+```
+Delete an existing solr index:
+```
+rails c
+> Blacklight.default_index.connection.delete_by_query "*:*"
+> Blacklight.default_index.connection.commit
+```
+
+#### Generating and running the test app
+
+Build the test app: 
+```
+rake engine_cart:generate
+```
+From `./internal_test_app`, create the initial admin user:
+
+*With [default credientials](https://github.com/projectblacklight/spotlight/blob/9acd4bf5d4f2806b6e76aa03c31176ea5f6943de/lib/tasks/spotlight_tasks.rake#L20-L21)*
+```
+rake spotlight:seed_admin_user
+```
+*With user-provided credientials*
+```
+bin/rails spotlight:initialize
+```
+From `./internal_test_app`, start Rails to run the test app:
+```
+bin/dev
+```
+From the project root, delete the test app (if you want to regenerate from scratch):
+```
+$ rake engine_cart:clean
+```
+## Spotlight Community
 
-## Community
+See [Contributing to Spotlight](/CONTRIBUTING.md) for general information about participation in the Spotlight community.
 
+### Where to find us
 
 - Join us on the [code4lib Slack](https://code4lib.org/irc)
   - **#spotlight-development** - a developer-focused channel for Spotlight
@@ -131,25 +258,3 @@ See [developer-facing instructions for enabling translation](https://github.com/
 - Google Groups
   - [Blacklight Development Google group](https://groups.google.com/forum/#!forum/blacklight-development)
   - [Spotlight Community Group](https://groups.google.com/forum/#!forum/spotlight-community) (equivalent to #spotlight-service)
-
-## Updating the JavaScript bundle
-The JavaScript is built by npm from sources in `app/javascript` into a bundle
-in `app/assets/javascripts/spotlight/spotlight.js`. This file should not be edited
-by hand as any changes would be overwritten.  When any of the JavaScript
-components in the gem are changed, this bundle should be rebuilt with the
-following steps:
-1. [Install npm](https://www.npmjs.com/get-npm)
-2. Run `npm install` to download dependencies
-3. Run `npm run prepare` to build the bundle
-4. If you are releasing a new version of the gem, follow the release instructions below.
-
-## Releasing a new version and publishing the JavaScript
-You only need to update `package.json` and prepare/publish the JavaScript package for npm if there are changes to the JavaScript.
-1. Edit `version.rb` and `package.json` to set the new version
-2. Run `npm run prepare` to build the JavaScript bundle
-3. Run `npm i --package-lock-only` to update the version in `package-lock.json`
-4. Commit the changes e.g. `git commit -am "Bump version to X.X.X"`
-5. Push the release to rubygems and GitHub: `bundle exec rake release`
-6. Run `npm publish` to push the JavaScript package to https://npmjs.org/package/spotlight-frontend
-
-See [Updating the JavaScript bundle](#updating-the-javascript-bundle) above for more details.

data/app/assets/javascripts/spotlight/spotlight.esm.js

@@ -3266,7 +3266,37 @@ class BrowseGroupCateogries {
 class Carousel {
   connect() {
     if ($.fn.carousel) {
-      $('.carousel').carousel();
+      const $carousel = $('.carousel');
+
+      // updates the aria-describedby on the next and prev btns
+      const updateAriaDescribedBy = function ($carousel) {
+        const $activeItem = $carousel.find('.carousel-item.active');
+        const $items = $carousel.find('.carousel-item');
+        const curIndex = $items.index($activeItem);
+        const prevIndex = (curIndex - 1 + $items.length) % $items.length;
+        const nextIndex = (curIndex + 1) % $items.length;
+
+        const prevDataId = $items.eq(prevIndex).data('id');
+        const nextDataId = $items.eq(nextIndex).data('id');
+        if (prevDataId) {
+          $carousel.find('.carousel-control-prev').attr('aria-describedby', 'carousel-caption-' + prevDataId);
+        }
+        if (nextDataId) {
+          $carousel.find('.carousel-control-next').attr('aria-describedby', 'carousel-caption-' + nextDataId);
+        }
+      };
+
+      // on initial page load, set the aria-describedby on the btns for each carousel
+      $carousel.each(function () {
+        const $this = $(this);
+        $this.carousel();
+        updateAriaDescribedBy($this);
+      });
+
+      // on slide change
+      $carousel.on('slid.bs.carousel', function () {
+        updateAriaDescribedBy($(this));
+      });
     }
   }
 }
@@ -5999,6 +6029,8 @@ SirTrevor.Blocks.FeaturedPages = (function(){
 
     icon_name: "pages",
 
+    show_image_selection: false,
+
     autocomplete_url: function() { return document.getElementById(this.instanceID).closest('form[data-autocomplete-exhibit-pages-path]').dataset.autocompleteExhibitPagesPath; },
     autocomplete_fetch: function(url) {
       return this.fetchOnceAndFilterLocalResults(url);