Giter Club home page Giter Club logo

projectblacklight / spotlight Goto Github PK

View Code? Open in Web Editor NEW
157.0 36.0 64.0 7.34 MB

Spotlight enables librarians, curators, and others who are responsible for digital collections to create attractive, feature-rich websites that highlight these collections.

License: Other

JavaScript 31.40% CSS 0.01% HTML 10.26% Ruby 54.53% SCSS 2.55% Shell 0.04% Dockerfile 0.07% XSLT 1.15%
solr rails ruby discovery-interface rails-application rails-engine exhibit

spotlight's Introduction

spotlight

CI | Gem Version | Release Notes | Design Documents

Spotlight is open source software that enables librarians, curators, and other content experts to easily build feature-rich websites that showcase collections and objects from a digital repository, uploaded items, or a combination of the two. Spotlight is a plug-in for Blacklight, an open source, Ruby on Rails Engine that provides a basic discovery interface for searching an Apache Solr index.

Read more about what Spotlight is, our motivations for creating it, and how to install and configure it in the wiki pages. You might also want to take a look at our demo videos, especially the tour of a completed Spotlight exhibit and the walkthrough of building an exhibit with Spotlight.

Requirements

  1. Ruby (2.7 or greater)
  2. Rails (5.2 or greater)
  3. Java (7 or greater) for Solr
  4. ImageMagick (http://www.imagemagick.org/script/index.php) due to carrierwave

Installation

To bootstrap a new Rails application:

$ SKIP_TRANSLATION=1 rails new app-name -m https://raw.githubusercontent.com/projectblacklight/spotlight/main/template.rb

or from an existing Rails application:

$ SKIP_TRANSLATION=1 rails app:template LOCATION=https://raw.githubusercontent.com/projectblacklight/spotlight/main/template.rb

During this process you will be prompted to enter an initial administrator email and password (this is a super-admin that can administer any exhibit in the installation). If you choose not to create one, the first user will be given administrative privileges.

Change directories to your new application:

$ cd app-name

Run the database migrations:

$ SKIP_TRANSLATION=1 rake db:migrate

Start Solr (possibly using solr_wrapper in development or testing):

$ solr_wrapper

and the Rails development server:

$ rails server

Go to http://localhost:3000 in your browser.

Configuration

Default ActionMailer configuration

Spotlight introduces functionality that depends on being able to send emails to exhibit curators and contacts. Be sure to configure your application's environments appropriately (see the Rails Guide for Action Mailer Configuration).

See the Spotlight wiki for more detailed information on configuring Spotlight.

Developing Spotlight

Spotlight:

  • is a Rails engine and needs to be used in the context of a Rails application. We use engine_cart to create an internal test application at .internal_test_app/
  • uses Solr as part of its integration tests. We use solr_wrapper to manage the Solr instance used for development and test.

Our $ rake ci and $ rake spotlight:server tasks utilize Solr and the testing rails app automatically.

See more detailed instructions for development environment setup at "Contributing to Spotlight"

With Docker

# because of how docker-compose handles named images, running `docker-compose up --build` will error when the Rails images have not been built locally
docker-compose build
docker-compose up

Tests

Run all the tests:

$ rake

This utilizes Solr and the testing rails app automatically.

Translations

Spotlight ships with i18n-tasks to help manage translations. To run a translation health check:

$ bundle exec i18n-tasks health

See developer-facing instructions for enabling translation on the wiki.

Community

  • Join us on the code4lib Slack
    • #spotlight-development - a developer-focused channel for Spotlight
    • #blacklight - a developer-focused channel for discussing implementation, customization, and other software concerns in the larger Blacklight community
    • #spotlight-service - a service-focused channel for people who support exhibit-builders at institutions already using Spotlight
  • Google Groups

Building the javascript

The javascript is built by npm from sources in app/javascript into a bundle in app/assets/javascripts/spotlight/spotlight.js. This file should not be edited by hand as any changes would be overwritten. When any of the javascript components in the gem are changed, this bundle should be rebuilt with the following steps:

  1. Install npm
  2. run npm install to download dependencies
  3. make sure that the version in package.json matches your intended release version
  4. commit the new package-lock.json that reflects the desired version number
  5. run npm run prepare to build the bundle
  6. run npm publish to push the javascript package to https://npmjs.org/package/spotlight-frontend

spotlight's People

Contributors

aaron-collier avatar aeschylus avatar atz avatar bess avatar camillevilla avatar cbeer avatar corylown avatar dunn avatar elrayle avatar ggeisler avatar hudajkhan avatar jacobthill avatar jchristo4 avatar jcoyne avatar jkeck avatar jmartin-sul avatar justinlittman avatar jzimpel avatar marlo-longley avatar mcritchlow avatar mejackreed avatar mephillips-durham avatar mjgiarlo avatar ndushay avatar peetucket avatar phil-plencner-hl avatar ronan-mch avatar taylor-steve avatar thatbudakguy avatar tpendragon avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

spotlight's Issues

Create Browse Category show/results page

When the user clicks one of the browse categories (saved search items) on the Browse landing page (#66), they should be shown a results page for that browse category, as shown below.

exhibits-wireframes-2014-01-30_pdf__page_13_of_39_

Create exhibit site model

(See also, #3)

Initial Fields:

  • title
  • subtitle
  • description (plain text only; should sanitize value before storing)
  • contact email (multi-valued; could just be a serialized field)

The email field should be syntax-validated.

Curation : Manage Facets

All(?) facet-eligible fields should be displayed here, with default labels.

User should be able to drag and drop facets to specify desired display order.

In a future sprint, we should add support for e.g. range select facets, single-valued facets, etc.

screen shot 2013-12-16 at 14 01 08

Create Exhibit settings page

(See also, #4 )

The exhibits setting page should be restricted to users with an admin role.

screen shot 2013-12-16 at 13 16 23
(Wireframes: page 24)

Exhibits setting should be stored somewhere in the database, and displayed where appropriate.

For Sprint 1, we should just support the title, subtitle, contact email, and description.

Add site header with links to Admin and Curator pages

Need site header so there are links to the Admin and Curator index pages (via the logged in username dropdown menu).

Curator index page is page 27 of wireframes (Items).

Admin index page is page 24 of the wireframes (Settings page with exhibit title, subtitle, etc.).

Main menu navigation

Main menu navigation should be dynamically created based on characteristics of the exhibit. That is, not every exhibit will necessarily have the same main menu links. If the curator for a given exhibit doesn't create any features pages (or doesn't have any defined feature pages checked to be visible), for example, we shouldn't show the "Curated Feature" link. If the curator has not saved any searches to use as browse categories (or doesn't have any saved searches checked to be visible), there shouldn't be a "Browse" main menu item.

There should always be a Home link.

See below for more details.

exhibits-wireframes-2013-12-17_pdf__page_5_of_39_

Curation: Feature Page Administration

Curator should be able to create and title new feature pages.

Feature pages should be sortable and nestable using some javascript-y widget.

Pages only need to be nestable one level deep; parent pages can have zero or more child pages, no further nesting.

The Add New Page button should add a new row to the list (similar to adding a new About page; see screenshot in #27).

exhibits-wireframes-2013-12-17 pdf__page_32_of_39_

Create item-image widget

Create a widget that takes an item id and displays the image and title (from the indexed title), displayed as a caption) for that item.

Use thumbnail associated with item document.

Ensure reasonable display when image is not available with item, and when the title is not available.

Curation metadata field display

Curators should be able to choose the fields that are displayed on a search index or search result page.

Mapping solr fields to display labels will be provided (in some ticket yet to be created).

screen shot 2013-12-16 at 13 49 07

(ignoring sortable, exhibit-specific fields, etc)

User administration screen

(any chance we can get away with third-party libraries here?)

Administrators should be able to find existing users or create new users. If a new user is created or roles are changed, an email should be sent to the user to let them know that their account was created (for Stanford's use case, this does not need to include a password set/reset prompt; maybe for others it will?)

exhibits-wireframes-2014-01-31_pdf__page_25_of_39_

(The screenshot implies usernames vs emails; for Stanford, these can be one and the same.)

Wireframes : Page 25

Create index page for Browse Categories (saved searches)

If the curator has saved searches that are selected to be visible on the Curation: Browse page (#11), those saved searches should be presented on a Browse Exhibit landing page, as shown below.

This page is the index page for the Browse main menu link. If there are no saved searches selected to be visible on the Curation: Browse page, the Browse main menu link should not be displayed (#35).

exhibits-wireframes-2014-01-30_pdf__page_12_of_39_-8

build out a good saved search blacklight plugin

Blacklight 5.x might drop saved searches from core. Some features here use that behavior, so we should build it out.

Erik and the lucid project may have similar requirements and we should make sure to get their feedback.

Curator: Capture and store exhibit contact details

The second part of the Curation: About Pages page is a section for capturing details for the contact person(s) for the site. (These details are to be displayed in the About page sidebar; see #40).

A contact is not required. But for each contact that is entered, the Name and E-mail fields should be present; e-mail should be a valid email address.

Clicking the Add additional contact button should add an additional set of name, e-mail, title, and location fields. Each set of fields also has a "Show in sidebar" checkbox associated with it.

exhibits-wireframes-2013-12-17_pdf__page_34_of_39_

Creating Exhibit-specific fields

As I curator, I should be able to create exhibit-specific fields for items. These fields should (eventually) be indexed as text into Solr.

These exhibit-specific fields will be populated from item edit pages, and will be configured for displayed as in #7.

"Share" functionality

Share and follow links are now in footer. Links here are global; they are for sharing the exhibit title and link to the site itself, not a specific item.

exhibits-wireframes-2014-01-31_pdf__page_6_of_39_

Curation: About Page Administration

Curator should be able to go to an About Pages page to add and change titles of about pages.

Curator should also be able to reorder the pages to indicate the desired order in the About pages sidebar menu.

exhibits-wireframes-2014-01-28_pdf__page_33_of_39_

Curation index page

Curators should be able to see a compact list of all items in the index.

screen shot 2013-12-16 at 13 38 46

For Sprint 1, we just need a list (of title, type and date added, I guess). The functionality, included Filter, will happen in a future sprint.

Display contact information in about page sidebar

If there is at least one contact defined and checked to be shown in the Curator: About Pages contacts section (#39), show the Contact heading in the About page sidebar with the fields for each contact that has been selected to be shown.

exhibits-wireframes-2013-12-17_pdf__page_21_of_39_

Create hierarchical page model for feature pages

Pages need to be re-orderable.

Pages may have a parent page.

If a page has a parent page (or child pages), the curator may want to show a sidebar with that hierarchy for navigating between pages.

exhibits-wireframes-2013-12-17 pdf__page_32_of_39_

Pages have some administrative configuration (whether having a sidebar is an option, etc)

Manage tags

Tags are created and edited only by curators; they can be used by curators effectively group arbitrary items that can then be saved as a saved search and used as a browse category.

Tags can also be used by end-users to search on all items with a given tag.

exhibits-wireframes-2014-01-28_pdf__page_29_of_39_

Add sidebar to About pages

All About pages should have a sidebar with links to all About pages that are checked to be visible.

exhibits-wireframes-2013-12-17_pdf__page_21_of_39_-7

Order of pages in the menu should be based on the order of the pages in the Curator: About Pages page.

exhibits-wireframes-2013-12-17_pdf__page_33_of_39_

Create sidebar navigation for About pages

All About pages should have a sidebar with navigation links to other About pages.

For all About pages that are checked to be visible, create a link in the About page sidebar, using the titles defined in the Curation: About Pages page.

exhibits-wireframes-2013-12-17_pdf__page_21_of_39_

Method missing 'opensearch_catalog_path'

Showing /Users/justin/.rbenv/versions/2.1.0/lib/ruby/gems/2.1.0/gems/blacklight-5.0.0.pre2/app/views/layouts/blacklight.html.erb where line #17 raised:

undefined method `opensearch_catalog_path' for #<#Class:0x007fb1b4ad9568:0x007fb1b4ef9580>
Extracted source (around line #17):

       <![endif]-->

       <title><%= h(@page_title || application_name) %></title>
       <link href="<%= opensearch_catalog_path(:format => 'xml', :only_path => false) %>" title="<%= application_name%>" type="application/opensearchdescription+xml" rel="search"/>
       <%= favicon_link_tag asset_path('favicon.ico') %>
       <%= stylesheet_link_tag    "application" %>
       <%= javascript_include_tag "application" %>

Create a Spotlight::User model/mixins for querying and managing roles

Spotlight needs to provide a user model and/or mixin to provide access roles for the application. Ideally this would be a mixin (to the extent it does anything?) and migration.

Initially, we expect Spotlight users to be either a "Curator" or an "Administrator".

The application (we expect) will use cancan to provide abilities to check for these roles.

Users may also have a user profile with affiliation, title, etc.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.