[joecorall]

What does this Pull Request do?

This PR modernizes Advanced Search for Drupal 10.3/11 and Facets 3, adds View-integrated search controls, and extracts the module's legacy presentation layer into a new optional advanced_search_olivero submodule. Existing Olivero installations receive the compatibility submodule automatically through a post-update hook, while other themes can style the base module's semantic markup without inheriting Olivero-specific CSS and form alterations.

For new implementations, Advanced Search controls can now live inside the Search API View that owns the results. This keeps the search form, exposed facets, result toolbar, and AJAX updates within one View replacement boundary. Legacy block plugins remain available for existing configurations.

The resulting responsibility boundary is clearer: the base Advanced Search module owns search behavior and semantic markup, the optional Olivero submodule preserves the historical Olivero presentation, and other themes own their own layout, typography, color, and component presentation.

• Related GitHub Issue:

  • Facets 3 compatibility #62

• Other Relevant Links:

  • Islandora DXPR companion PR #2
  • Starter Site companion PR #257

What's new?

Presentation extraction and upgrade compatibility

• Moves the Advanced Search form and results-pager presentation out of the base module and into the new optional advanced_search_olivero submodule.
• Moves the legacy Olivero-specific CSS and presentation-oriented form alterations with that compatibility layer.
• Stops the base module from imposing one theme's layout and styling on every site that enables Advanced Search.
• Retains stable semantic classes, accessible labels, and behavioral JavaScript in the base module so custom themes have a reliable integration contract.
• Adds a post-update hook that enables advanced_search_olivero when Olivero is already installed, protecting existing sites from an unexpected presentation regression.
• Limits compatibility styling to Olivero and Olivero subthemes. Custom themes can style the base module directly and do not need the compatibility submodule.

Facets 3 and platform compatibility

• Supports both Facets 2 and Facets 3.
• Removes the hard dependency on the experimental Facets Summary submodule.
• Uses supported Facets 3 behavior where available while retaining guarded compatibility for Facets 2 installations.
• Removes the module's obsolete custom facet soft-limit JavaScript.
• Updates requirements to Drupal 10.3 or Drupal 11 and PHP 8.1 or later.
• Retains Search API Solr 4.x support.

View-integrated search controls

Adds two configurable Views header-area plugins:

• Advanced Search form
  • Selects and orders searchable Search API fields.
  • Supports collection searching through a configurable direct-child contextual filter.
  • Uses the current View display instead of requiring a separately configured derived block.
• Advanced Search results toolbar
  • Displays the current result range.
  • Provides exposed sorting without offering ascending relevance.
  • Provides results-per-page links for progressive enhancement.
  • Provides list/grid display controls.
  • Supports per-display list/grid defaults and availability.
  • Omits the pager from the top toolbar so pagination can remain below the results.

The View-integrated handlers are preferred for new sites. Existing Advanced Search form and pager block plugins remain available for upgrades and layouts that still require separate blocks.

AJAX and navigation behavior

• Scopes AJAX configuration and events to a specific View instance.
• Supports multiple instances of the same View on a page.
• Preserves repeated query parameters and active search state.
• Keeps sorting, page-size, and list/grid navigation within the owning View.
• Preserves browser history and back/forward navigation.
• Uses ordinary links and form submission as the non-JavaScript fallback.
• Avoids modifying Drupal's global History API behavior.

Query and service improvements

• Handles malformed or nested query parameters defensively.
• Makes the advanced-search and recursive-search parameter names configurable through the query factory.
• Uses dependency injection for configuration, block storage, routing, and request-stack access.
• Ensures temporary contextual-filter requests are removed from the request stack even when argument resolution throws an exception.
• Uses the current request safely in the Search API Solr event subscriber.

Dependencies and upgrade considerations

No new contributed module dependency is introduced.

Existing sites can continue using their current Advanced Search blocks. New sites must add the new area handlers to the appropriate View headers to use the integrated experience.

The minimum supported platform changes to:

• PHP 8.1 or later
• Drupal 10.3 or later, or Drupal 11
• Facets 2.x or 3.x
• Search API Solr 4.2 or later

Drupal 8 and Drupal 9 are no longer supported by this branch.

How should this be tested?

Automated testing

The following targeted tests have been run on Drupal 11.4 with PHP 8.4:

• PHPCS using the Drupal and DrupalPractice standards
• 2 query unit tests with 17 assertions
• 7 View-integration functional tests with 54 assertions

The GitHub Actions test matrix should also complete successfully.

Olivero upgrade testing

1. Install the existing Advanced Search release with Olivero installed.
2. Update to this branch and run drush updb.
3. Confirm that advanced_search_olivero is enabled automatically.
4. Confirm that existing Advanced Search and pager blocks continue working and retain their presentation.
5. Confirm that the compatibility library loads with Olivero and an Olivero subtheme, but not with an unrelated theme.
6. Confirm that Advanced Search no longer prevents uninstalling Facets Summary.

View-integrated testing

1. Add Advanced Search form and Advanced Search results toolbar to the
   header of a Search API View.
2. Configure searchable fields and, for a collection display, its direct-child contextual filter.
3. Verify repository-wide and collection-specific searching.
4. Verify that search terms, facets, sorting, page size, and display mode survive AJAX updates.
5. Verify list/grid switching on both page and block displays.
6. Verify browser back and forward navigation.
7. Place two instances of the same View on one page and confirm that their AJAX behavior remains isolated.
8. Disable JavaScript and confirm that forms and toolbar links still navigate correctly.
9. Test malformed and repeated query parameters and confirm that they do not trigger PHP errors.
10. Test with both Facets 2 and Facets 3.

Documentation Status

• README.md documents:
  • supported Drupal and PHP versions;
  • the base-module, compatibility-module, and theme responsibility boundary;
  • the optional Olivero compatibility submodule;
  • the new View-integrated search controls;
  • the continued availability of legacy block plugins.
• modules/advanced_search_olivero/README.md documents the compatibility
  submodule.
• The companion Starter Site and Islandora DXPR PRs demonstrate the preferred
  configuration and presentation.

Additional Notes:

This PR provides semantic markup and accessible interaction foundations, but
presentation and final color-contrast decisions remain the active theme's
responsibility.

The View handlers are intentionally additive. They allow the Starter Site to
reduce the number of separately placed blocks without forcing existing sites to
rebuild their search layouts immediately.

Interested parties

[t4k]

I briefly tested this on an existing codebase with a theme other than Olivero. I can say that:

• My original Facets Block blocks remained in place and worked with AJAX.
• The "Displaying 1 - 60 of 217" (for example) and "Results per page" active class worked as expected. (I am having trouble with those working properly in my current setup.)
• The sort options and pager also works as expected.
• advanced_search_olivero is not enabled automatically when we didn't have the Olivero theme installed.

I could probably deploy this right now and be happy.

[joecorall]

Heads-up from the islandora_dxpr 1.0.0 sprint (Islandora/islandora_dxpr#25): Islandora-Devops/islandora-starter-site#257 (branch dxpr) carries this PR as three local patches (facets-3-compatibility, view-integrated-search-areas, view-integrated-search-polish). Those patches are an older snapshot of this branch. Applied to 2.4.2, they don't include:

• the advanced_search_olivero submodule and its post-update hook (the Olivero CSS is still in the base module)
• AdvancedSearchQueryFactory and the DI changes in the query, form, and event subscriber
• the rewritten advanced_search.form.js / facets-views-ajax.js
• the removal of soft-limit.js, and drupal/facets: ^2.0 || ^3.0 in composer.json
• the new tests

So sprint testers on Islandora-Devops/islandora-starter-site#257 aren't exercising what this PR will ship. The plan: review and merge this PR, tag a release (2.5.0, given the [minor]), then drop the three patches and the drupal/facets: "3.0.3 as 2.0.10" alias from the Starter Site's dxpr branch. Reviews welcome, especially from anyone with an Olivero site to try the upgrade path.