Join GitHub today
Understanding Rails and Blacklight
In order to understand how Blacklight works, you should have a basic knowledge about how Rails works. In the previous section, we offered resources to develop a general understanding of Rails. In this section, we'll look at the most important concepts that contribute to the way Blacklight functions.
blacklight:install generator (see Installing).
Blacklight generates a
CatalogController into your application. This controller adds discovery and single-item "show" actions. This controller is where you can perform the majority of your Blacklight configuration and customization. The configuration options are discussed in future chapters.
Blacklight also provides several controllers to the host application. These controllers respect the
Engine model and controller classes can be extended by open classing them in the main Rails application (since model and controller classes are just Ruby classes that inherit Rails specific functionality).
As with the
CatalogController above, Blacklight generates a
SolrDocument model into your application. This model is used to translate Solr response documents into Rails models. Unlike many Rails models, the
SolrDocument is not backed by an ActiveRecord row, but is merely a read-only, Ruby-friendly representation of Solr's response.
SolrDocument model, you can provide custom model methods, accessors, and behaviors to the documents returned from Solr.
SolrDocument also provides an extension framework for conditionally adding additional behavior to documents. The extension framework is discussed in greater detail later.
Blacklight views can be customized by simply creating a new view within your application with the same name as the Blacklight view you want to override. If you wanted to override the view provided by the Blacklight
app/views/catalog/_per_page_widget.html.erb partial, you could create the file
app/views/catalog/_per_page_widget.html.erb in your own application.
When Rails looks for a view to render, it will first look in the app/views directory of the application. If it cannot find the view there, then it will check in the app/views directories of all engines which have this directory.
Blacklight provides a generic layout to the application.
If you're integrating Blacklight into an existing Rails application, Blacklight also expects the host application's layout to be responsible for rendering Rails flash messages and a shared Bootstrap modal. In addition, the layout should include:
A place for Blacklight views (and, mainly, plugins) to inject content into the:
<head> ... <%= content_for(:head) %> ... </head>
The layout should also provide a Bootstrap container and row wrapper:
<div class="container"> ... <div class="row"> <%= yield %> </div> </div>
Many Rails engines are "mounted" and are entirely isolated from the main application's routes. Blacklight routes, however, are injected directly into your application. Blacklight routes are added by a generator, and add this line to your
Mostly legacy. Allows for some greater flexibility.