Join GitHub today
Clone this wiki locally
NOTE: This wiki provides developer documentation for the latest Blacklight release. For documentation of older releases, see the end of this page.
Blacklight is an open source, Ruby on Rails Engine that provides a basic discovery interface for searching an Apache Solr index, and provides search box, facet constraints, stable document urls, etc., all of which is customizable via Rails (templating) mechanisms. Blacklight accommodates heterogeneous data, allowing different information displays for different types of objects.
Some other features include:
- Stable URLs for search and record pages allow users to bookmark, share, and save search queries for later access
- Every Blacklight search provides JSON, RSS, and Atom Responses of search results
- For certain types of solr documents, an OpenURL/Z39.88 COinS object is embedded in each document, which allows plugins like Zotero to easily extract data from the page.
- Blacklight supports OpenSearch, a collection of simple formats for the sharing of search results.
- Faceted searching
- Search queries can be targeted at specific sets of fields
- Results sorting
- Tools for exporting records to Refworks or Endnote, sending records via Email or SMS, or as a formatted citation.
About this guide
This wiki provides high-level documentation of Blacklight and supplements the low-level RubyDocs. It is structured to address a broad spectrum of needs, ranging from new developers getting started to well-experienced developers extending their application or troubleshooting. It should be of use at any point in the application life cycle.
This wiki assumes you have prior experience with Ruby and Ruby on Rails. If you have no prior experience with either, you will find a very steep learning curve diving straight into Blacklight. There are some good free resources on the internet for learning Ruby, including:
And resources for learning Rails, including:
In order to fully understand this guide, you should also familiarize yourself with Apache Solr, ways to index data into Solr, how to configure request handlers, and the Solr schema format. Those topics are covered in the official Apache Solr Tutorial.
- Basic features
- Internationalization: Translating (or simply customizing) the Blacklight copy
- APIs: Atom Responses, JSON API
- Directory of Blacklight Plugins, Add-ons, and Customizations
Blacklight tries to address the "80% use case" out of the box and through some simple configuration can be adapted to work with your data. The available Blacklight configuration, and their default values, is shown in
The Blacklight configuration is an
OpenStruct; in addition to the Blacklight-defined configuration discussed in the sections below, you may also add application-specific configuration (e.g. for controlling behavior in overridden partials) or plugin-specific configuration.
There are many ways to override specific behaviors and views in Blacklight. Because Blacklight is distributed as a Rails engine-based gem, all customization of Blacklight behavior should be done within your application by overriding Blacklight-provided behaviors with your own.
- Understanding Rails and Blacklight How the Blacklight engine integrates with your application
- Extending or Modifying Blacklight Search Behavior How to change the way the Blacklight discovery feature works.
- Adding new document actions How to extend the document actions with application-specific behavior
- Customizing value rendering
Customizing the UI
- Theming: Overriding the Blacklight CSS
- Providing your own view templates: Overriding the out-of-the-box Blacklight templates the Rails way.
- Pagination: Advice on how to customize pagination with Kaminari
- User Authentication: Connecting Blacklight with an existing Authentication system
- Configuring Rails Routes
- Indexing your data into Solr
- Additional Blacklight-specific Solr documentation
Don't be scared to ask a question on the Blacklight mailing list. We appreciate you checking the documentation first and asking an educated question, but don't beat your head against the wall -- sometimes the existing documentation may be out of date and inaccurate.
In order to reduce spam, the first time you post your email will be held in a moderation queue, but as soon as your first message is approved your posts won’t be held for moderation any longer.
Some Blacklight developers also hang out on our IRC channel, usually during North American office hours. On
#blacklight. Stop in and say hi, we're happy to help with questions when we have time. http://freenode.net/faq.shtml.
Contributing to Blacklight
This wiki provides developer documentation for the
master branch of Blacklight, which may include documentation of features not present in every Blacklight version. For documentation of specific Blacklight releases, see also: