Class: Blacklight::Configuration

Inherits:
OpenStructWithHashAccess show all
Extended by:
ActiveSupport::Autoload
Includes:
Fields
Defined in:
lib/blacklight/configuration.rb,
lib/blacklight/configuration/fields.rb,
lib/blacklight/configuration/context.rb,
lib/blacklight/configuration/view_config.rb

Overview

Blacklight::Configuration holds the configuration for a Blacklight::Controller, including fields to display, facets to show, sort options, and search fields.

Defined Under Namespace

Modules: Fields Classes: Context, DisplayField, FacetField, Field, IndexField, NullField, SearchField, ShowField, SortField, ToolConfig, ViewConfig

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Fields

#add_blacklight_field

Methods inherited from OpenStructWithHashAccess

#deep_dup, #merge, #merge!, #reverse_merge, #select, #sort_by, #sort_by!, #to_h, #try

Constructor Details

#initialize(hash = {}) {|_self| ... } ⇒ Configuration

Returns a new instance of Configuration.

Yields:

  • (_self)

Yield Parameters:



180
181
182
183
184
185
 
# File 'lib/blacklight/configuration.rb', line 180

def initialize(hash = {})
  super(self.class.default_values.deep_dup.merge(hash))
  yield(self) if block_given?

  @view_config ||= {}
end

Class Method Details

.default_values ⇒ Object

rubocop:disable Metrics/MethodLength



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/blacklight/configuration.rb', line 25

def default_values
  @default_values ||= begin
    {
    # === Search request configuration
    # HTTP method to use when making requests to solr; valid
    # values are :get and :post.
    http_method: :get,
    # The path to send requests to solr.
    solr_path: 'select',
    # Default values of parameters to send with every search request
    default_solr_params: {},
    ##
    # === Single document request configuration
    # The solr request handler to use when requesting only a single document
    document_solr_request_handler: nil,
    # The path to send single document requests to solr
    document_solr_path: 'get',
    document_unique_id_param: :ids,
    # Default values of parameters to send when requesting a single document
    default_document_solr_params: {},
    fetch_many_document_params: {},
    document_pagination_params: {},
    ##
    # == Response models
    ## Class for sending and receiving requests from a search index
    repository_class: nil,
    ## Class for converting Blacklight parameters to request parameters for the repository_class
    search_builder_class: nil,
    # model that maps index responses to the blacklight response model
    response_model: nil,
    # the model to use for each response document
    document_model: nil,
    # Class for paginating long lists of facet fields
    facet_paginator_class: nil,
    # repository connection configuration
    connection_config: nil,
    ##
    # == Blacklight view configuration
    navbar: OpenStructWithHashAccess.new(partials: {}),
    # General configuration for all views
    index: ViewConfig::Index.new(
      # document presenter class used by helpers and views
      document_presenter_class: nil,
      # component class used to render a document; defaults to Blacklight::DocumentComponent,
      #   but can be set explicitly to avoid any legacy behavior
      document_component: nil,
      # solr field to use to render a document title
      title_field: nil,
      # solr field to use to render format-specific partials
      display_type_field: nil,
      # partials to render for each document(see #render_document_partials)
      partials: [:index_header, :thumbnail, :index],
      document_actions: NestedOpenStructWithHashAccess.new(ToolConfig),
      collection_actions: NestedOpenStructWithHashAccess.new(ToolConfig),
      # what field, if any, to use to render grouped results
      group: false,
      # additional response formats for search results
      respond_to: OpenStructWithHashAccess.new
    ),
    # Additional configuration when displaying a single document
    show: ViewConfig::Show.new(
      # document presenter class used by helpers and views
      document_presenter_class: nil,
      document_component: nil,
      display_type_field: nil,
      # Default route parameters for 'show' requests.
      # Set this to a hash with additional arguments to merge into the route,
      # or set `controller: :current` to route to the current controller.
      route: nil,
      # partials to render for each document(see #render_document_partials)
      partials: [:show_header, :show],
      document_actions: NestedOpenStructWithHashAccess.new(ToolConfig)
    ),
    action_mapping: NestedOpenStructWithHashAccess.new(
      ViewConfig,
      default: { top_level_config: :index },
      show: { top_level_config: :show },
      citation: { parent_config: :show }
    ),
    # SMS and Email configurations.
    sms: ViewConfig.new,
    email: ViewConfig.new,
    # Configurations for specific types of index views
    view: NestedOpenStructWithHashAccess.new(ViewConfig,
                                             list: {},
                                             atom: {
                                               if: false, # by default, atom should not show up as an alternative view
                                               partials: [:document],
                                               summary_partials: [:index]
                                             },
                                             rss: {
                                               if: false, # by default, rss should not show up as an alternative view
                                               partials: [:document]
                                           }),
    #
    # These fields are created and managed below by `define_field_access`
    # facet_fields
    # index_fields
    # show_fields
    # sort_fields
    # search_fields
    ##
    # === Blacklight behavior configuration
    # Maxiumum number of spelling suggestions to offer
    spell_max: 5,
    # Maximum number of results to show per page
    max_per_page: 100,
    # Options for the user for number of results to show per page
    per_page: [10, 20, 50, 100],
    default_per_page: nil,
    # how many searches to save in session history
    search_history_window: 100,
    default_facet_limit: 10,
    default_more_limit: 20,
    # proc for determining whether the session is a crawler/bot
    # ex.: crawler_detector: lambda { |req| req.env['HTTP_USER_AGENT'] =~ /bot/ }
    crawler_detector: nil,
    autocomplete_suggester: 'mySuggester',
    raw_endpoint: OpenStructWithHashAccess.new(enabled: false),
    track_search_session: true,
    advanced_search: OpenStruct.new(enabled: false),
    enable_search_bar_autofocus: false
    }
  end
  # rubocop:enable Metrics/MethodLength
end

Instance Method Details

#add_facet_fields_to_solr_request! ⇒ Object #add_facet_fields_to_solr_request!(field, field, etc) ⇒ Object

Add any configured facet fields to the default solr parameters hash

Overloads:

  • #add_facet_fields_to_solr_request! ⇒ Object

    add all facet fields to the solr request

  • #add_facet_fields_to_solr_request!(field, field, etc) ⇒ Object

    Parameters:

    • field (Symbol) —

      Field names to add to the solr request



288
289
290
291
292
293
294
 
# File 'lib/blacklight/configuration.rb', line 288

def add_facet_fields_to_solr_request!(*fields)
  if fields.empty?
    self.add_facet_fields_to_solr_request = true
  else
    facet_fields.slice(*fields).each_value { |v| v.include_in_request = true }
  end
end

#add_field_configuration_to_solr_request! ⇒ Object #add_field_configuration_to_solr_request!(field, field, etc) ⇒ Object

Add any configured facet fields to the default solr parameters hash

Overloads:

  • #add_field_configuration_to_solr_request! ⇒ Object

    add all index, show, and facet fields to the solr request

  • #add_field_configuration_to_solr_request!(field, field, etc) ⇒ Object

    Parameters:

    • field (Symbol) —

      Field names to add to the solr request



301
302
303
304
305
306
307
308
309
 
# File 'lib/blacklight/configuration.rb', line 301

def add_field_configuration_to_solr_request!(*fields)
  if fields.empty?
    self.add_field_configuration_to_solr_request = true
  else
    index_fields.slice(*fields).each_value { |v| v.include_in_request = true }
    show_fields.slice(*fields).each_value { |v| v.include_in_request = true }
    facet_fields.slice(*fields).each_value { |v| v.include_in_request = true }
  end
end

#add_nav_action(name, opts = {}) ⇒ Object

Add a partial to the header navbar

Parameters:

  • name (String) —

    the name of the document partial

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :if (Symbol, Proc) —

    render this action if the method identified by the symbol or the proc evaluates to true. The proc will receive the action configuration and the document or documents for the action.

  • :unless (Symbol, Proc) —

    render this action unless the method identified by the symbol or the proc evaluates to true. The proc will receive the action configuration and the document or documents for the action.



388
389
390
 
# File 'lib/blacklight/configuration.rb', line 388

def add_nav_action(name, opts = {})
  add_action(navbar.partials, name, opts)
end

#add_results_collection_tool(name, opts = {}) ⇒ Object

Add a tool for the search result list itself

Parameters:

  • name (String) —

    the name of the document partial

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :if (Symbol, Proc) —

    render this action if the method identified by the symbol or the proc evaluates to true. The proc will receive the action configuration and the document or documents for the action.

  • :unless (Symbol, Proc) —

    render this action unless the method identified by the symbol or the proc evaluates to true. The proc will receive the action configuration and the document or documents for the action.



376
377
378
 
# File 'lib/blacklight/configuration.rb', line 376

def add_results_collection_tool(name, opts = {})
  add_action(index.collection_actions, name, opts)
end

#add_results_document_tool(name, opts = {}) ⇒ Object

Add a partial to the tools for each document in the search results.

Parameters:

  • name (String) —

    the name of the document partial

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :if (Symbol, Proc) —

    render this action if the method identified by the symbol or the proc evaluates to true. The proc will receive the action configuration and the document or documents for the action.

  • :unless (Symbol, Proc) —

    render this action unless the method identified by the symbol or the proc evaluates to true. The proc will receive the action configuration and the document or documents for the action.



382
383
384
 
# File 'lib/blacklight/configuration.rb', line 382

def add_results_document_tool(name, opts = {})
  add_action(index.document_actions, name, opts)
end

#add_show_tools_partial(name, opts = {}) ⇒ Object

Add a partial to the tools when rendering a document.

Parameters:

  • name (String) —

    the name of the document partial

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :if (Symbol, Proc) —

    render this action if the method identified by the symbol or the proc evaluates to true. The proc will receive the action configuration and the document or documents for the action.

  • :unless (Symbol, Proc) —

    render this action unless the method identified by the symbol or the proc evaluates to true. The proc will receive the action configuration and the document or documents for the action.



367
368
369
370
371
 
# File 'lib/blacklight/configuration.rb', line 367

def add_show_tools_partial(name, opts = {})
  opts[:partial] ||= 'document_action'
  add_action(show.document_actions, name, opts)
  klass && ActionBuilder.new(klass, name, opts).build
end

#build(klass) ⇒ Object Also known as: inheritable_copy

builds a copy for the provided controller class



321
322
323
324
325
 
# File 'lib/blacklight/configuration.rb', line 321

def build(klass)
  deep_copy.tap do |conf|
    conf.klass = klass
  end
end

#configure {|_self| ... } ⇒ Object

DSL helper

Yields:

  • (_self)

Yield Parameters:



238
239
240
241
 
# File 'lib/blacklight/configuration.rb', line 238

def configure
  yield self if block_given?
  self
end

#connection_config ⇒ Object 



217
218
219
 
# File 'lib/blacklight/configuration.rb', line 217

def connection_config
  super || Blacklight.connection_config
end

#deep_copy ⇒ Object

Provide a 'deep copy' of Blacklight::Configuration that can be modified without effecting the original Blacklight::Configuration instance.

Note: Rails provides `#deep_dup`, but it aggressively `#dup`'s class names too, turning them into anonymous class instances.



316
317
318
 
# File 'lib/blacklight/configuration.rb', line 316

def deep_copy
  deep_transform_values_in_object(self, &method(:_deep_copy))
end

#default_per_page ⇒ Object 



233
234
235
 
# File 'lib/blacklight/configuration.rb', line 233

def default_per_page
  super || per_page.first
end

#default_search_field ⇒ Object

Returns default search field, used for simpler display in history, etc. if not set, defaults to first defined search field



245
246
247
248
 
# File 'lib/blacklight/configuration.rb', line 245

def default_search_field
  field = super || search_fields.values.find { |f| f.default == true }
  field || search_fields.values.first
end

#default_sort_field ⇒ Object

Returns default sort field, used for simpler display in history, etc. if not set, defaults to first defined sort field



252
253
254
255
 
# File 'lib/blacklight/configuration.rb', line 252

def default_sort_field
  field = super || sort_fields.values.find { |f| f.default == true }
  field || sort_fields.values.first
end

#default_title_field ⇒ Object 



257
258
259
 
# File 'lib/blacklight/configuration.rb', line 257

def default_title_field
  document_model.unique_key || 'id'
end

#document_factory ⇒ Object

A class that builds documents



192
193
194
 
# File 'lib/blacklight/configuration.rb', line 192

def document_factory
  super || Blacklight::DocumentFactory
end

#document_model ⇒ Object 



187
188
189
 
# File 'lib/blacklight/configuration.rb', line 187

def document_model
  super || ::SolrDocument
end

#document_model=(*args) ⇒ Object

only here to support alias_method



197
198
199
 
# File 'lib/blacklight/configuration.rb', line 197

def document_model=(*args)
  super
end

#facet_configuration_for_field(field) ⇒ Blacklight::Configuration::FacetField

Returns Blacklight facet configuration for the solr field.

Parameters:

  • field (String) —

    Solr facet name

Returns:



263
264
265
266
267
268
269
270
 
# File 'lib/blacklight/configuration.rb', line 263

def facet_configuration_for_field(field)
  # short-circuit on the common case, where the solr field name and the blacklight field name are the same.
  return facet_fields[field] if facet_fields[field] && facet_fields[field].field == field

  # Find the facet field configuration for the solr field, or provide a default.
  facet_fields.values.find { |v| v.field.to_s == field.to_s } ||
    FacetField.new(field: field).normalize!
end

#facet_field_names(group = nil) ⇒ Array<String>

Returns a list of the facet field names from the configuration.

Parameters:

  • group (String) (defaults to: nil) —

    (nil) a group name of facet fields

Returns:

  • (Array<String>) —

    a list of the facet field names from the configuration



274
275
276
 
# File 'lib/blacklight/configuration.rb', line 274

def facet_field_names(group = nil)
  facet_fields.select { |_facet, opts| group == opts[:group] }.values.map(&:field)
end

#facet_group_names ⇒ Array<String>

Returns a list of facet groups.

Returns:

  • (Array<String>) —

    a list of facet groups



279
280
281
 
# File 'lib/blacklight/configuration.rb', line 279

def facet_group_names
  facet_fields.map { |_facet, opts| opts[:group] }.uniq
end

#facet_paginator_class ⇒ Object 



229
230
231
 
# File 'lib/blacklight/configuration.rb', line 229

def facet_paginator_class
  super || Blacklight::Solr::FacetPaginator
end

#for_display_type(display_type, &_block) ⇒ Object

Add a section of config that only applies to documents with a matching display type



394
395
396
397
398
399
400
 
# File 'lib/blacklight/configuration.rb', line 394

def for_display_type display_type, &_block
  self.fields_for_type ||= {}

  (fields_for_type[display_type] ||= self.class.new).tap do |conf|
    yield(conf) if block_given?
  end
end

#freeze ⇒ Object 



442
443
444
445
 
# File 'lib/blacklight/configuration.rb', line 442

def freeze
  each { |_k, v| v.is_a?(OpenStruct) && v.freeze }
  super
end

#index_fields_for(document_or_display_types) ⇒ Object

Return a list of fields for the index display that should be used for the provided document. This respects any configuration made using for_display_type



405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
 
# File 'lib/blacklight/configuration.rb', line 405

def index_fields_for(document_or_display_types)
  display_types = if document_or_display_types.is_a? Blacklight::Document
                    Deprecation.warn self, "Calling index_fields_for with a #{document_or_display_types.class} is deprecated and will be removed in Blacklight 8. Pass the display type instead."
                    document_or_display_types[index.display_type_field || 'format']
                  else
                    document_or_display_types
                  end

  fields = {}.with_indifferent_access

  Array.wrap(display_types).each do |display_type|
    fields = fields.merge(for_display_type(display_type).index_fields)
  end

  fields.merge(index_fields)
end

#locate_search_builder_class ⇒ Object 



225
226
227
 
# File 'lib/blacklight/configuration.rb', line 225

def locate_search_builder_class
  ::SearchBuilder
end

#repository ⇒ Object 



213
214
215
 
# File 'lib/blacklight/configuration.rb', line 213

def repository
  repository_class.new(self)
end

#repository_class ⇒ Object 



209
210
211
 
# File 'lib/blacklight/configuration.rb', line 209

def repository_class
  super || Blacklight::Solr::Repository
end

#response_model ⇒ Object 



201
202
203
 
# File 'lib/blacklight/configuration.rb', line 201

def response_model
  super || Blacklight::Solr::Response
end

#response_model=(*args) ⇒ Object 



205
206
207
 
# File 'lib/blacklight/configuration.rb', line 205

def response_model=(*args)
  super
end

#search_builder_class ⇒ Object 



221
222
223
 
# File 'lib/blacklight/configuration.rb', line 221

def search_builder_class
  super || locate_search_builder_class
end

#show_fields_for(document_or_display_types) ⇒ Object

Return a list of fields for the show page that should be used for the provided document. This respects any configuration made using for_display_type



425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
 
# File 'lib/blacklight/configuration.rb', line 425

def show_fields_for(document_or_display_types)
  display_types = if document_or_display_types.is_a? Blacklight::Document
                    Deprecation.warn self, "Calling show_fields_for with a #{document_or_display_types.class} is deprecated and will be removed in Blacklight 8. Pass the display type instead."
                    document_or_display_types[show.display_type_field || 'format']
                  else
                    document_or_display_types
                  end

  fields = {}.with_indifferent_access

  Array.wrap(display_types).each do |display_type|
    fields = fields.merge(for_display_type(display_type).show_fields)
  end

  fields.merge(show_fields)
end

#view_config(view_type = nil, action_name: :index) ⇒ Blacklight::Configuration::ViewConfig

Get a view configuration for the given view type + action. The effective view configuration is inherited from:

  • the configuration from blacklight_config.view with the key `view_type`

  • the configuration from blacklight_config.action_mapping with the key `action_name`

  • any parent config for the action map result above

  • the action_mapping default configuration

  • the top-level index/show view configuration

Parameters:

  • view_type (Symbol, #to_sym) (defaults to: nil)

Returns:



338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
 
# File 'lib/blacklight/configuration.rb', line 338

def view_config(view_type = nil, action_name: :index)
  view_type &&= view_type.to_sym
  action_name &&= action_name.to_sym
  action_name ||= :index

  if view_type == :show
    action_name = view_type
    view_type = nil
  end

  @view_config[[view_type, action_name]] ||= begin
    if view_type.nil?
      action_config(action_name)
    else
      base_config = action_config(action_name)
      base_config.merge(view.fetch(view_type, {}))
    end
  end
end