Class: Blacklight::Configuration

Inherits:
OpenStructWithHashAccess show all
Includes:
Fields
Defined in:
lib/blacklight/configuration.rb,
lib/blacklight/configuration/fields.rb,
lib/blacklight/configuration/context.rb,
lib/blacklight/configuration/view_config.rb,
lib/blacklight/configuration/session_tracking_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, NullDisplayField, NullField, SearchField, SessionTrackingConfig, ShowField, SortField, ToolConfig, ViewConfig

Constant Summary collapse

BASIC_SEARCH_PARAMETERS = 
[:q, :qt, :page, :per_page, :search_field, :sort, :controller, :action, :'facet.page', :'facet.prefix', :'facet.sort', :rows, :format, :view, :id, :facet_id,
:query_fragment, :only_values].freeze
ADVANCED_SEARCH_PARAMETERS = 
[{ clause: {} }, :op].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Fields

#add_blacklight_field

Methods inherited from OpenStructWithHashAccess

#deep_dup, #deep_transform_values, #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:



371
372
373
374
375
376
377
378
 
# File 'lib/blacklight/configuration.rb', line 371

def initialize(hash = {})
  self.class.initialize_default_configuration unless self.class.initialized_default_configuration?

  super(self.class.default_values.deep_transform_values(&method(:_deep_copy)).merge(hash))
  yield(self) if block_given?

  @view_config ||= {}
end

Instance Attribute Details

#email_fields ⇒ Hash{Symbol=>Blacklight::Configuration::DisplayField}

Returns:



369
 
# File 'lib/blacklight/configuration.rb', line 369

define_field_access :email_field, Blacklight::Configuration::DisplayField

#facet_fields ⇒ Hash{Symbol=>Blacklight::Configuration::FacetField}

Returns:



351
 
# File 'lib/blacklight/configuration.rb', line 351

define_field_access :facet_field, Blacklight::Configuration::FacetField

#index_fields ⇒ Hash{Symbol=>Blacklight::Configuration::IndexField}

Returns:



354
 
# File 'lib/blacklight/configuration.rb', line 354

define_field_access :index_field, Blacklight::Configuration::IndexField

#search_fields ⇒ Hash{Symbol=>Blacklight::Configuration::SearchField}

Returns:



360
 
# File 'lib/blacklight/configuration.rb', line 360

define_field_access :search_field, Blacklight::Configuration::SearchField

#show_fields ⇒ Hash{Symbol=>Blacklight::Configuration::ShowField}

Returns:



357
 
# File 'lib/blacklight/configuration.rb', line 357

define_field_access :show_field, Blacklight::Configuration::ShowField

#sms_fields ⇒ Hash{Symbol=>Blacklight::Configuration::DisplayField}

Returns:



366
 
# File 'lib/blacklight/configuration.rb', line 366

define_field_access :sms_field, Blacklight::Configuration::DisplayField

#sort_fields ⇒ Hash{Symbol=>Blacklight::Configuration::SortField}

Returns:



363
 
# File 'lib/blacklight/configuration.rb', line 363

define_field_access :sort_field, Blacklight::Configuration::SortField

Class Method Details

.default_configuration(&block) ⇒ Object 



16
17
18
19
20
21
22
23
24
25
26
 
# File 'lib/blacklight/configuration.rb', line 16

def default_configuration(&block)
  @default_configurations ||= []

  if block
    @default_configurations << block

    block.call if @default_configuration_initialized
  end

  @default_configurations
end

.initialize_default_configuration ⇒ Object 



28
29
30
31
 
# File 'lib/blacklight/configuration.rb', line 28

def initialize_default_configuration
  @default_configurations&.map(&:call)
  @default_configuration_initialized = true
end

.initialized_default_configuration? ⇒ Boolean

Returns:

  • (Boolean) 


33
34
35
 
# File 'lib/blacklight/configuration.rb', line 33

def initialized_default_configuration?
  @default_configuration_initialized
end

.property(key, default: nil) ⇒ Object 



12
13
14
 
# File 'lib/blacklight/configuration.rb', line 12

def property(key, default: nil)
  default_values[key] = default
end

Instance Method Details

#add_email_field(config_key, options) ⇒ Blacklight::Configuration::DisplayField #add_email_field(config_key, field) ⇒ Blacklight::Configuration::DisplayField #add_email_field(config_key, array) ⇒ Blacklight::Configuration::DisplayField

Overloads:

Parameters:

  • config_key (Symbol)

Returns:

See Also:



369
 
# File 'lib/blacklight/configuration.rb', line 369

define_field_access :email_field, Blacklight::Configuration::DisplayField

#add_facet_field(config_key, options) ⇒ Blacklight::Configuration::FacetField #add_facet_field(config_key, field) ⇒ Blacklight::Configuration::FacetField #add_facet_field(config_key, array) ⇒ Blacklight::Configuration::FacetField

Overloads:

Parameters:

  • config_key (Symbol)

Returns:

See Also:



351
 
# File 'lib/blacklight/configuration.rb', line 351

define_field_access :facet_field, Blacklight::Configuration::FacetField

#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



457
458
459
460
461
462
463
 
# File 'lib/blacklight/configuration.rb', line 457

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



470
471
472
473
474
475
476
477
478
 
# File 'lib/blacklight/configuration.rb', line 470

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_index_field(config_key, options) ⇒ Blacklight::Configuration::IndexField #add_index_field(config_key, field) ⇒ Blacklight::Configuration::IndexField #add_index_field(config_key, array) ⇒ Blacklight::Configuration::IndexField

Overloads:

Parameters:

  • config_key (Symbol)

Returns:

See Also:



354
 
# File 'lib/blacklight/configuration.rb', line 354

define_field_access :index_field, Blacklight::Configuration::IndexField

#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):

  • :component (Class) —

    draw a component

  • :partial (String) —

    partial to draw if component is false

  • :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.



575
576
577
 
# File 'lib/blacklight/configuration.rb', line 575

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):

  • :component (Class) —

    draw a component

  • :partial (String) —

    partial to draw if component is false

  • :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.



563
564
565
 
# File 'lib/blacklight/configuration.rb', line 563

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):

  • :component (Class) —

    draw a component

  • :partial (String) —

    partial to draw if component is false

  • :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.



569
570
571
 
# File 'lib/blacklight/configuration.rb', line 569

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

#add_search_field(config_key, options) ⇒ Blacklight::Configuration::SearchField #add_search_field(config_key, field) ⇒ Blacklight::Configuration::SearchField #add_search_field(config_key, array) ⇒ Blacklight::Configuration::SearchField

Overloads:

Parameters:

  • config_key (Symbol)

Returns:

See Also:



360
 
# File 'lib/blacklight/configuration.rb', line 360

define_field_access :search_field, Blacklight::Configuration::SearchField

#add_show_field(config_key, options) ⇒ Blacklight::Configuration::ShowField #add_show_field(config_key, field) ⇒ Blacklight::Configuration::ShowField #add_show_field(config_key, array) ⇒ Blacklight::Configuration::ShowField

Overloads:

Parameters:

  • config_key (Symbol)

Returns:

See Also:



357
 
# File 'lib/blacklight/configuration.rb', line 357

define_field_access :show_field, Blacklight::Configuration::ShowField

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

Add a partial to the show page header when rendering a document.

Parameters:

  • name (String) —

    the name of the document partial

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

Options Hash (opts):

  • :component (Class) —

    draw a component

  • :partial (String) —

    partial to draw if component is false

  • :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.



552
553
554
555
556
557
 
# File 'lib/blacklight/configuration.rb', line 552

def add_show_header_tools_partial(name, opts = {})
  opts[:partial] ||= 'document_action'

  add_action(show.header_actions, name, opts)
  klass && ActionBuilder.new(klass, name, opts).build
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):

  • :component (Class) —

    draw a component

  • :partial (String) —

    partial to draw if component is false

  • :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.



537
538
539
540
541
542
 
# File 'lib/blacklight/configuration.rb', line 537

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

#add_sms_field(config_key, options) ⇒ Blacklight::Configuration::DisplayField #add_sms_field(config_key, field) ⇒ Blacklight::Configuration::DisplayField #add_sms_field(config_key, array) ⇒ Blacklight::Configuration::DisplayField

Overloads:

Parameters:

  • config_key (Symbol)

Returns:

See Also:



366
 
# File 'lib/blacklight/configuration.rb', line 366

define_field_access :sms_field, Blacklight::Configuration::DisplayField

#add_sort_field(config_key, options) ⇒ Blacklight::Configuration::SortField #add_sort_field(config_key, field) ⇒ Blacklight::Configuration::SortField #add_sort_field(config_key, array) ⇒ Blacklight::Configuration::SortField

Overloads:

Parameters:

  • config_key (Symbol)

Returns:

See Also:



363
 
# File 'lib/blacklight/configuration.rb', line 363

define_field_access :sort_field, Blacklight::Configuration::SortField

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

builds a copy for the provided controller class

Parameters:

  • klass (Class) —

    configuration host class



491
492
493
494
495
 
# File 'lib/blacklight/configuration.rb', line 491

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

#configure {|config| ... } ⇒ Blacklight::Configuration

DSL helper

Yields:

  • (config)

Yield Parameters:

Returns:



399
400
401
402
 
# File 'lib/blacklight/configuration.rb', line 399

def configure
  yield self if block_given?
  self
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.



485
486
487
 
# File 'lib/blacklight/configuration.rb', line 485

def deep_copy
  deep_transform_values(&method(:_deep_copy))
end

#default_per_page ⇒ Integer

Returns:

  • (Integer) 


391
392
393
 
# File 'lib/blacklight/configuration.rb', line 391

def default_per_page
  super || per_page.first
end

#default_search_field ⇒ Blacklight::Configuration::SearchField

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

Returns:



407
408
409
 
# File 'lib/blacklight/configuration.rb', line 407

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

#default_sort_field ⇒ Blacklight::Configuration::SortField

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

Returns:



414
415
416
417
 
# File 'lib/blacklight/configuration.rb', line 414

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

#default_title_field ⇒ String

Returns:

  • (String) 


420
421
422
 
# File 'lib/blacklight/configuration.rb', line 420

def default_title_field
  document_model.unique_key || 'id'
end

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

Returns Blacklight facet configuration for the solr field.

Parameters:

  • field (String) —

    Solr facet name

Returns:



426
427
428
429
430
431
432
433
 
# File 'lib/blacklight/configuration.rb', line 426

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



437
438
439
 
# File 'lib/blacklight/configuration.rb', line 437

def facet_field_names(group = nil)
  facet_fields_in_group(group).map(&:field)
end

#facet_fields_in_group(group) ⇒ Array<Blacklight::Configuration::FacetField>

Returns a list of facet fields.

Parameters:

  • group (String) —

    (nil) a group name of facet fields

Returns:



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

def facet_fields_in_group(group)
  facet_fields.values.select { |opts| group == opts[:group] }
end

#facet_group_names ⇒ Array<String>

Returns a list of facet groups.

Returns:

  • (Array<String>) —

    a list of facet groups



448
449
450
 
# File 'lib/blacklight/configuration.rb', line 448

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

#for_display_type(display_type) ⇒ Object

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



581
582
583
584
585
586
587
 
# File 'lib/blacklight/configuration.rb', line 581

def for_display_type(display_type, &)
  fields_for_type[display_type] ||= self.class.new

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

#index_fields_for(display_types) ⇒ Object

Deprecated.

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



593
594
595
596
597
 
# File 'lib/blacklight/configuration.rb', line 593

def index_fields_for(display_types)
  Array(display_types).inject(index_fields) do |fields, display_type|
    fields.merge(for_display_type(display_type).index_fields)
  end
end

#logo_link ⇒ String

Returns The destination for the link around the logo in the header.

Returns:

  • (String) —

    The destination for the link around the logo in the header



386
387
388
 
# File 'lib/blacklight/configuration.rb', line 386

def logo_link
  super || Rails.application.routes.url_helpers.root_path
end

#repository ⇒ Blacklight::Repository

Returns:

  • (Blacklight::Repository) 


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

def repository
  Blacklight.repository_class.new(self)
end

#show_fields_for(display_types) ⇒ Object

Deprecated.

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



603
604
605
606
607
 
# File 'lib/blacklight/configuration.rb', line 603

def show_fields_for(display_types)
  Array(display_types).inject(show_fields) do |fields, display_type|
    fields.merge(for_display_type(display_type).show_fields)
  end
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:



508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
 
# File 'lib/blacklight/configuration.rb', line 508

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]] ||= if view_type.nil?
                                               action_config(action_name)
                                             else
                                               base_config = action_config(action_name)
                                               base_config.merge(view.fetch(view_type, {}))
                                             end
end