Page widgets

Spotlight uses the sir-trevor framework to build feature pages. We've created several custom widgets to meet some needs of Spotlight users, including widgets that allow you to embed search results, create carousels, and link to other Spotlight pages.

Configuring Spotlight widgets

Item Embed

The item embed widget uses your Blacklight configuration to render items into your page. It expects the blacklight_config.view.embed.partials configuration to list the partials that it should render. Out-of-the-box, Spotlight provides the same openseadragon viewer that it uses on the catalog#show page. As it uses the Blacklight document rendering pipeline, you can even customize the partials based on document type.

oEmbed

Spotlight uses ruby-oembed to render the oEmbed widget. Out-of-the-box, the oembed gem configures a large number of providers, but you can easily customize this list in your application's initializers (e.g. in config/initializers/oembed_providers.rb).

Adding new widgets

Adding new types of widgets is easy, and just takes a little code. It starts with adding the widget to the Sir-Trevor UI by creating a new type of block in javascript. Here is a simple example block that just adds a horizontal rule:

SirTrevor.Blocks.Rule = (function(){

  return SirTrevor.Block.extend({
    type: "rule",

    title: function() { return "Horizontal Rule"; },

    icon_name: "rule",
    
    editorHTML: function() {
      return _.template(this.template, this)(this);
    },

    template: '<hr />'
  });
})();

To display this block, we also need to create a Rails partial (in app/views/spotlight/sir_trevor/blocks) to tell Rails what to do with that block. sir-trevor look up for the partial using the block type ("rule") and the suffix "_block.html", e.g. _rule_block.html.erb. As block is very simple, we just need to add:

<hr />

formable

Blocks can also contain form inputs. While sir-trevor can handle basic forms itself, we've added a formable plugin for serializing and deserializing form data using jQuery, allowing it to work as expected in many scenarios. For example, let's create a block to add <h2> elements.

SirTrevor.Blocks.H2 = (function(){

  return SirTrevor.Block.extend({
    type: "h2",

    title: function() { return "H2"; },

    icon_name: "h2",

    formable: true, // <-- this enables the formable plugin.
    
    editorHTML: function() {
      return _.template(this.template, this)(this);
    },

    template: '<input type="text" name="title" />'
  });
})();

As before, we need to create a Rails partial, this time called _h2_block.html.erb. Sir-trevor provides a local variable containing the block data. We can use it to extract the title data from the block:

<h2><%= h2_block.title %></h2>

If you look at the class of h2_block, you'll see sir-trevor created a new class for us: SirTrevorRails::Blocks::H2Block. If you had domain logic you wanted to use, you could create this class within your application (at e.g. app/models/sir_trevor_rails/blocks/h2_block.rb) and use this logic within your partial.

Item based widgets

Spotlight provides some building blocks for building widgets based on items in your collection. We've provided Spotlight.Block.Resources and SirTrevor.Blocks.SolrDocuments as a framework for creating these widgets. You can see several variations of those base classes in the Spotlight blocks (js / ruby) directories.