Skip to content

Configuration Results View

Jump to bottom Edit New page
_ygor_gallina edited this page Jun 15, 2023 · 20 revisions

Note that Solr fields you configure for display must be STORED fields in the Solr index.

Index View

Index View

Basic configuration

The index view is configured from your CatalogController's blacklight configuration. Here is a listing of the configuration parameters Blacklight uses and their default values:

configure_blacklight do |config|
   ...

   config.index.title_field = unique_key
   config.index.partials = [:index_header, :thumbnail, :index]
   config.index.display_type_field = 'format'
   config.index.group = false

   ...
end

The configuration keys are not limited or restricted, so plugins or applications that need additional index configuration may add additional parameters directly.

config.index.my_custom_parameters = "some value"

Configure which Solr document field to use for record titles in search results.

The configuration setting config.index.title_field determines the value that Blacklight uses to display the record title in search results, and can be set within the Blacklight configuration block in your controller.

# app/controllers/catalog_controller.rb
class CatalogController < ApplicationController
  ...
  configure_blacklight do |config|
    ...
    config.index.title_field = :my_solr_field
    ...
  end
  ...
end

NOTE: By default, Blacklight will use the ID of the Solr document as it's title, which is specified by the unique_key class instance variable of the Solr document class, and can also be customized.

NOTE: The Solr document field specified for config.index.title_field must be the complete field name, including any dynamic suffixes that may have been added by Solrizer, e.g. if the complete Solr field name is actually :book_title_tesim, then you must use config.index.title_field = :book_title_tesim.

Add custom logic for displaying record titles in search results.

The config.index.document_presenter_class specifies which class should be used for returning values displayed in the index view and partials.

The default presenter class is Blacklight::IndexPresenter. When the search results are rendered, an instance of the presenter class is available from within the index views and partials. Those views and partials then call instance methods on the presenter class to return values for display.

By specifying your own class for config.index.document_presenter_class, you can implement your own instance methods that the index views are calling.

For example, the value for a record's title comes from Blacklight::IndexPresenter#label, which in turn uses the value specified by config.index.title_field to return the record title. So to add your own custom logic for how a record's title is created from Solr document fields, you can create your own presenter class, and implement your own version of the #label method.

Example: Use two concatenated Solr document fields for record titles in search results.

# app/presenters/my_presenter.rb
class MyPresenter < Blacklight::IndexPresenter
  def label(field_or_string_or_proc, opts = {})
    # Assuming that :main_title and :sub_title are field names on the Solr document.
    document.first(:main_title) + " - " + document.first(:sub_title)
  end
end

# app/controllers/catalog_controller.rb
class CatalogController < ApplicationController
  ...
  configure_blacklight do |config|
    ...
    config.index.document_presenter_class = MyPresenter
    ...
  end
  ...
end

Using document_component

(Starting in Blacklight 7.11)

Blacklight uses View Components to display a search result. This largely replaces the previous practice of overriding Blacklight's partials or providing format-specific partials (documented below). In this case, view components provide a clear(er) API for changing what displays while still allowing downstream applications to take advantage of some of Blacklight's default behaviors.

# app/controllers/catalog_controller.rb
class CatalogController < ApplicationController
  ...
  configure_blacklight do |config|
    ...
    config.index.document_component = MyDocumentComponent
    ...
  end
  ...
end

# app/components/my_document_component.rb
class MyDocumentComponent < Blacklight::DocumentComponent
end

# app/components/my_document_component.html.erb
<div>...</div>

The component will receive the document and its presenter (as presenter) and can render whatever content makes sense for the document in that context.

Partials and display_type_field

(Discouraged after Blacklight 7.11 in favor of view components)

You can configure the partials that Blacklight will assemble to display a search result.

By default, Blacklight will render these three basic partials when displaying a document. The partial names are a combination of two configuration settings. The base name of the partial is given by the partials setting. The suffix is based on the type of document given by the value of the display_type_field. If a partial is not found with the given display_type_field value, it will attempt to render a default version of the base partial. If no matching partial is found, nothing will be displayed for that document.

For example, using the default values and a document without a format field, these partials will be rendered:

  • _index_header.html.erb: The document title and document actions
  • _thumbnail.html.erb: A representative thumbnail (from the thumbnail_field configuration below)
  • _index.html.erb: A list of document fields

However, if the document had a format field with the value book, Blacklight would attempt to render these partials:

  • _index_header_book.html.erb; if that doesn't exist, it will fall back to _index_header.html.erb
  • _thumbnail_book.html.erb; fall back to _thumbnail.html.erb
  • _index_book.html.erb; fall back to _index.html.erb

Blacklight only provides default partials for these three base partials. If you were to provide an app/views/catalog/_index_book.html.erb partial, Blacklight would render that partial instead of the default.

(Advanced) Result Collapsing / Grouping

Blacklight can use Solr's result collapsing feature. To use this feature, set the group parameter to the name of the field that Blacklight should use to render collapsed result sets.

Respond_to

You can also affect which search results response formats are available, in addition to the out-of-the-box HTML, JSON, Atom and RSS feeds.

Options include:

  • use the Rails default rendering options:

    config.index.respond_to.yaml = true

  • don't render the format (e.g. for overriding defaults):

      config.index.respond_to.yaml = false

  • options for render

      config.index.respond_to.yaml = { layout: 'custom-layout' }

  • custom proc to render

      config.index.respond_to.yaml = lambda { render text: "stuff" }

  • controller method to call to render

    config.index.respond_to.yaml = :my_custom_yaml_serialization

Fields

The fields the index default template uses to render fields are configured using add_index_field:

config.add_index_field 'title_display'

This will add a field to the display that will pull values from the Solr field 'title_display'. If the field is multivalued, Blacklight will concatenate them with Array#to_sentence, using ", " by default. This value can also be configured, e.g.:

config.add_index_field 'multivalued_title', separator_options: { words_connector: '; ' }

Additional configuration options can be also be used:

Labels

By default, Blacklight will calculate a default label by humanizing the Solr field (which is rarely desirable, but convenient for initial configuration). To customize the label, a :label option can be provided.

config.add_index_field 'title_display', label: "Title"

Or, using i18n syntax, may look something like:

config.add_index_field 'title_display', label: I18n.t('my.application.index.title_display')

The given label is also passed through an i18n filter for adding e.g. prefixes and suffixes. By default, Blacklight will append a ":" to the field value.

Model Accessors

If the value you wish to display is defined on the model, instead of in a single solr field, you can configure Blacklight to use an accessor on the SolrDocument instance:

config.add_index_field 'title_display', accessor: 'title'

This will call document.title to get the value of the field, e.g.:

class SolrDocument
  def title
    first(:main_title) + " - " + first(:sub_title)
  end
end

will concatenate the main and sub titles.

Highlight

Solr supports query hit-highlighting. Blacklight can display the highlighted version of the field:

config.add_index_field 'my_highlighted_field', highlight: true

To make it work out of the box Blacklight can send the most basic highlighting parameters if you set:

  config.add_field_configuration_to_solr_request!

This will enable the highlighting component and send 'hl.fl' parameters for the fields you wanted highlighted, but you will likely want to tweak this behavior further.

Component

Blacklight can be configured to render your field using a custom ViewComponent.

config.add_index_field 'some_field', component: MyCustomMetadataFieldComponent

The component will receive the Blacklight::FieldPresenter instance for that field (among other attributes) and can render the field data in whatever manner is appropriate.

Helper Method

When preparing a value for display, Blacklight can be configured to call a custom helper method.

config.add_index_field 'some_field_with_an_external_link', helper_method: 'make_this_a_link'
module ApplicationHelper
  def make_this_a_link options={}
    options[:document] # the original document
    options[:field] # the field to render
    options[:value] # the value of the field

    link_to options[:value], options[:value]
  end
end

Link To Search

Some display fields are also facet fields, and often it makes sense to link the displayed value to the corresponding facet selection.

# in Blacklight 7, link_to_search is deprecated in favor of link_to_facet
config.add_index_field 'genre', link_to_facet: true

Or use the value in a link to a different field (e.g. if your display field is not indexed)

# in Blacklight 7, link_to_search is deprecated in favor of link_to_facet
config.add_index_field 'genre', link_to_facet: 'genre_facet'

Conditional Rendering

You can supply a method symbol or a Proc to the 'if' and 'unless' keyword arguments to make fields render conditionally.

config.add_facet_field 'my_facet_field', if: lambda { |context, field_config, facet|
  # code returning a boolean goes here
} 
config.add_index_field 'my_index_field', if: lambda { |context, field_config, document|
  # code returning a boolean goes here
} 
config.add_index_field 'my_index_field', unless: lambda { |context, field_config, document|
  # code returning a boolean goes here
} 
config.add_show_field 'my_show_field', if: lambda { |context, field_config, document|
  # code returning a boolean goes here
} 
config.add_show_field 'my_show_field', if: :display_my_show_field?

# this should be defined in the controller
def display_my_show_field?(field_config)
  # code returning a boolean goes here
end

Schema.org configuration

config.add_index_field 'genre', itemprop: "genre"

The genre values will be marked up as schema.org genre values. See the schema.org documentation for a full list of classes and properties.

Note that by default, Blacklight will mark up documents using the Schema class Thing. Since this has a very limited range of properties, adding properties such as author or genre will be invalid. In order to describe your documents with more descriptive classes you can overwrite the itemtype method in your SolrDocument class, for example:

...
  def itemtype
    type = self.to_hash['cat_ssi'] || ''
    case type
      when 'work'
        'http://schema.org/CreativeWork'
      when 'person'
        'http://schema.org/Person'
      else
        'http://schema.org/Thing'
    end
  end

Google provides a Structured Data Testing Tool which you can use to test the validity of your Schema markup.

View Types

Blacklight provides a default "list" view of results.

(Advanced) Results Grouping

Show view

Show view

Advanced Configuration

You can also use the field configuration to inject field-specific configuration

config.add_index_field 'an_index_field', solr_params: { 'hl.alternativeField' => 'field_x'}
config.add_show_field 'a_show_field', solr_params: { 'hl.alternativeField' => 'field_y'}
# provided you also use: config.add_field_configuration_to_solr_request!

This will add field-specific parameters to the solr request.

Add a custom footer

Quickstart Guide

Upgrading to Blacklight 8

Demo

Example installations

Blacklight Summits and Events

Clone this wiki locally