mitlibraries / timdex-ui

A discovery interface backed by the TIMDEX API.

TIMDEX UI

A discovery interface backed by the TIMDEX API.

Architecture decision records (ADRs)

This repository contains ADRs in the docs/architecture-decisions directory.

adr-tools should allow easy creation of additional records with a standardized template.

TIMDEX UI Flow Diagram

Note: this is a logical flow diagram and not a direct representation of object relationships. It is also a guide, not a set of rules to follow. If implementation is done differently, please update this diagram to reflect that intentional change as part of the work.

  flowchart TD
    UserInput --> Enhancer
    UserInputAdvanced --> Enhancer

    Enhancer --> QueryBuilder

    QueryBuilder --> Timdex

    Timdex --> Results --> Analyzer
    Timdex --> Errors
    Errors --> UI

    Analyzer --> Records --> UI
    Analyzer --> Facets --> UI
    Analyzer --> Pagination --> UI
    Analyzer --> Info --> UI

    Enhancer --> Actions
    
    Actions --> Info

    Analyzer("Analyzer 🔎")
    Enhancer("Enhancer 🔎")
    Errors("Errors ‼️")
    Info("Info ℹ️")
    Pagination("Pagination 🔢")
    Records("Records 📚")
    UI("Results UI 🤩")
    UserInput("User Input 🤷🏽‍♀️")
    UserInputAdvanced("User Input Advanced 🦸‍♀️")

Loading

Developer notes

Confirming functionality after dependency updates

This application has test coverage >95%, so running the test suite is likely sufficient to confirm functionality in most cases. Some click testing is also useful, particularly if there have been updates to graphql-ruby or graphql-client:

1. Confirm that basic and advanced searches do not error and return results.
2. Confirm that geospatial searches (bounding box and distance) do not error and return results. (Note that this requires testing against an index that contains geospatial records.)
3. Confirm that filters from multiple categories can be applied and removed, both on the sidebar and the panel beneath the search form.

If the flipflop gem has been updated, check that the :gdt feature is working by ensuring that UI elements specific to GDT (e.g., geospatial search fields or the 'Ask GIS' link) appear with the feature flag enabled, and do not when it is disabled.

Required Environment Variables

• TIMDEX_GRAPHQL: Set this to the URL of the GraphQL endpoint. There is no default value in the application.

Optional Environment Variables

• ABOUT_APP: If populated, an 'about' partial containing the contents of this variable will render on basic_search#index.
• ACTIVE_FILTERS: If populated, this list of strings defines which filters are shown to the user, and the order in which they appear. Values are case sensitive, and must match the corresponding aggregations used in the TIMDEX GraphQL query. Extraneous values will be ignored. If not populated, all filters will be shown.
• BOOLEAN_OPTIONS: comma separated list of values to present to testers on instances where BOOLEAN_PICKER feature is enabled.
• BOOLEAN_PICKER: feature to allow users to select their preferred boolean type. If set, feature is enabled. This feature is only intended for internal team testing and should never be enabled in production (mostly because the UI is a mess more than it would cause harm).
• FACT_PANELS_ENABLED: Comma separated list of enabled fact panels. See /views/results.html.erb for implemented panels/valid options. Leave unset to disable all.
• FILTER_ACCESS_TO_FILES: The name to use instead of "Access to files" for that filter / aggregation.
• FILTER_CONTENT_TYPE: The name to use instead of "Content type" for that filter / aggregation.
• FILTER_CONTRIBUTOR: The name to use instead of "Contributor" for that filter / aggregation.
• FILTER_FORMAT: The name to use instead of "Format" for that filter / aggregation.
• FILTER_LANGUAGE: The name to use instead of "Language" for that filter / aggregation.
• FILTER_LITERARY_FORM: The name to use instead of "Literary form" for that filter / aggregation.
• FILTER_PLACE: The name to use instead of "Place" for that filter / aggregation.
• FILTER_SOURCE: The name to use instead of "Source" for that filter / aggregation.
• FILTER_SUBJECT: The name to use instead of "Subject" for that filter / aggregation.
• GDT: Enables features related to geospatial data discovery. Setting this variable with any value will trigger GDT mode (e.g., GDT=false will still enable GDT features). Note that this is currently intended only for the GDT app and may have unexpected consequences if applied to other TIMDEX UI apps.
• GLOBAL_ALERT: The main functionality for this comes from our theme gem, but when set the value will be rendered as safe html above the main header of the site.
• PLATFORM_NAME: The value set is added to the header after the MIT Libraries logo. The logic and CSS for this comes from our theme gem.
• SENTRY_DSN: Client key for Sentry exception logging.
• SENTRY_ENV: Sentry environment for the application. Defaults to 'unknown' if unset.
• TIMDEX_INDEX: Name of the index, or alias, to provide to the GraphQL endpoint. Defaults to nil which will let TIMDEX determine the best index to use. Wildcard values can be set, for example rdi* would search any indexes that begin with rdi in the underlying OpenSearch instance behind TIMDEX.
• TIMDEX_SOURCES: Comma-separated list of sources to display in the advanced-search source selection element. This overrides the default which is set in ApplicationHelper.

Test Environment-only Variables

• SPEC_REPORTER: Optional variable. If set, enables spec reporter style output from tests rather than minimal output.
• TIMDEX_HOST: Test Env only. Used to ensure the VCR cassettes can properly scrub specific host data to make sure we get the same cassettes regardless of which host was used to generate the cassettes. This should be set to the host name that matches TIMDEX_GRAPHQL. Ex: If TIMDEX_GRAPHQL is https://www.example.com/graphql then TIMDEX_HOST should be www.example.com.

Generating VCR Cassettes

When generating new cassettes for timdex-ui, update .env.test to have appropriate values for your test for TIMDEX_GRAPHQL and TIMDEX_HOST. This will allow the cassettes to be generated from any TIMDEX source with the data you need, but be sure to set them back to the original values after the cassette are generated. When the values are not set to the "fake" values we normally store, many tests will fail due to how the cassettes re-write values to normalize what we store.

.env.test should be commited to the repository, but should not include real values for a TIMDEX source even though they are not secrets. We want to use fake values to allow us to normalize our cassettes without forcing us to always generate them from a single TIMDEX source.

Updating GraphQL Schema

The schema for the GraphQL endpoint can be found at /config/schema/schema.json. This schema is used by the graphql-client gem, and so must be kept in sync with the Timdex GraphQL API. Updating the schema can be accomplished via the following command in the console:

GraphQL::Client.dump_schema(TimdexBase::HTTP, 'config/schema/schema.json')

timdex-ui's Issues

Configure CodeClimate

Success Criteria

• CodeClimate is configured similarly to our other Rails apps

Out of Scope

• Fixing any issues

Results Analyzer

Success criteria

• Initial model to handle various future analyzers
• Error Handler module: check for TIMDEX error state and bypass Result Extract if it makes sense to just Display error context in UI

Out of scope

• Any non-TIMDEX error state analyzers

Results Extraction

Success Criteria

• Convert TIMDEX response into Facets, Records, Pagination blocks
• Display extracted information in UI

Out of scope

• Error handling (we'll handle that in Analyzers maybe?)

Configure rubocop

Success Criteria

• Rubocop is installed and configured similarly to our other Rails Apps
• Rubocop is run to auto-cleanup all safe fixes on the current codebase

Out of Scope

• Code Climate
• Running listing in CI

TimdexQueryBuilder

Success Criteria

• Transforms simple Query to a call that can be sent to TIMDEX V2 API
• Pagination

Out of scope

• Advanced queries, including faceting, targeting specific collections, targeting specific fields

Basic Search Form

Success Criteria

• Search form
• Controller that does nothing initially
• View that shows "empty" results and what the initial search term was
• Handle empty query

Out of scope

• Querying TIMDEX to get results
• Fancy results records (we won't have records yet, so we'll handle displaying records, facets, pagination, info boxes later)

Add EnhancerPattern for DOI

This may be helpful context to base our detection on.
https://www.crossref.org/blog/dois-and-matching-regular-expressions/

For our purposes we can likely use either just the first pattern or the first two noted in that article. I don't think we need to account for the few they note towards the end but we'll want to ensure we add a few tests for non-CrossRef DOIs to ensure they are appropriately captured or we may need additional rules.

Wire Enhancer into BasicSearchController

Success Criteria

• search form input is sent to Enhancer from the controller
• controller sends the output of Enhancer to QueryBuilder (instead of the search term directly)
• QueryBuilder is updated to use the search term from Enhancer instead of param
• The UI Info panel should display the ISSN/ISBN if detected in the search.

Out of Scope

• QueryBuilder using ISSN/ISBN data from Enhancer
• Any actionable links in the UI panel when ISSN/ISBN is detected

Implement MIT Libraries Theme Gem

TimdexQueryWrapper

Success Criteria

• Takes a pre-built TIMDEX query as input
• Calls TIMDEX V2 API
• Handles Fatal Errors
• Returns Reponse

Out of scope

• Analyzing results
• Converting results into Facets, Records
• Pagination (this is handled in the QueryBuilder and UI components)

Enhancer

Success Criteria

• Initial model for Enhancer

Out of scope

• Actually checking for any patterns