Overriding view components

Blacklight provides many ways to override its ViewComponents with your own custom templates or view logic.

To determine which view component you wish to override

If you're overriding a deprecated partial, and want to migrate it to a ViewComponent:

1. Go to the partial's path in the Blacklight gem and see which view component it renders. For example, if you wanted to move away from using the deprecated app/views/catalog/_facets.html.erb partial, you could check the Blacklight source and see that it is now using config.sidebar_component. Further searching would indicate that the default value for config.sidebar_component is Blacklight::Search::SidebarComponent.
2. Search for that component in the Blacklight code base to see how it is used.
3. If its configuration options are not sufficient for your customization needs, you may wish to override it.

Creating your own custom component

1. Use the ViewComponent generator: bundle exec rails g component YourNamespace::Search::SidebarComponent
2. Edit the newly generated app/components/your_namespace/search/sidebar_component.rb to inherit from Blacklight::Search::SidebarComponent.
3. Write your test and make your changes. 😀

Overriding the upstream Blacklight component

In configuration

Several components can be configured in the CatalogController. For example, if you want to override Blacklight's search bar with your own, you can specify it in your catalog controller:

config.index.search_bar_component = MyApp::SearchBarComponent

You can also specify a component for displaying a particular facet field. For example,

config.add_facet_field 'format', label: 'Format', component: MyFormatComponent

Or for a particular display field:

config.add_show_field 'author_tsim', label: 'Author', component: MyAuthorComponent

By editing the component or partial that renders the component in question

For example, if you want to create a custom advanced search form, you could change your app/views/catalog/_advanced_search_form.html.erb from this:

<%= render(Blacklight::AdvancedSearchFormComponent.new(
      url: search_action_url,
      classes: ['advanced', 'form-horizontal'],
      params: search_state.params_for_search.except(:qt),
      response: @response
    )) %>

To this:

<%= render(MyOwnComponent.new(my_params: params[...])) %>

By placing your custom component in the same path as the Blacklight-provided component

For example, if you wanted to override Blacklight::System::ModalComponent everywhere it is called, you could:

1. Confirm that, in the blacklight release your app is using, Blacklight::System::ModalComponent is defined at [blacklight_path]/app/components/blacklight/system/modal_component.rb
2. In your app, create your desired ruby code at app/components/blacklight/system/modal_component.rb. Note that, if you choose this option, you will have to implement the entire component class; you can't just override a single method using this strategy.
3. In your app, create your desired template at app/components/blacklight/system/modal_component.html.erb

By placing only an .erb in the same path as the Blacklight-provided .erb

If you only want to override the .html.erb in the example above, and you are using Blacklight 7.25 or higher, you can follow these steps. However, note that by doing this, you are essentially overriding a private method. If the upstream component changes substantially, your partial override would be quite a bit more fragile than a full, cohesive component.

1. Confirm that, in the blacklight release your app is using, Blacklight::System::ModalComponent is defined at [blacklight_path]/app/components/blacklight/system/modal_component.rb
2. Confirm that, in the blacklight release your app is using, Blacklight::System::ModalComponent inherits from Blacklight::Component
3. In your app, create your desired template at app/components/blacklight/system/modal_component.html.erb