Vivo Scholar UI

A possible front-end to the Scholars Discovery GraphQL endpoint. NOTE This project does nothing without a running instance of scholars-discovery. To get that running see Getting Started

Technology

• Go Buffalo - for server side rendering, and asset pipeline
• Web Components - for UI components as well as search
• LitElement - for generating web components

Development Dependencies

Native

• Go (>= version 1.12)
• Go Buffalo (>= version 0.14.10)
• Yarn

OR: Docker Only

• Docker
• Docker Compose

Getting Started

Get the scholars-discovery project running. This can be done in docker or using a local install of java

Scholars Discovery

Vivo Scholar UI is a meant to be run atop a running instance of scholars-discovery, which in turn imports data from a VIVO instance

See Scholars Discovery for more details about importing data and getting started

Vivo Scholar UI

 cp .env.example .env

Update the value of GRAPHQL_ENDPOINT_BASE to the base address (before /graphql) of a running instance of Scholars Discovery. The default value of one running locally has been prepopulated in .env.example

Set the SITE_NAME, SITE_LOGO to a general name and logo for the entire site

Set the SITE_ORGANIZATION_ID value to the institution's root organization id

Native

 buffalo dev

Docker Only

 docker-compose up

The app will be available at: http://localhost:4200

Background

The underlying motivation of this project is to make it easier to customize the UI of VIVO. It should be easy to add and/or customize pages with basic knowledge of HTML, GraphQL and Javascript - no Sparql, freemarker templates, listview-config etc...

Pages are represented by a template file and corresponding GraphQL query file. Adding new or editing existing templates and queries are the expected means of customization.

Web Components are the primary method of encapsulating core styles and behaviors. They can be used to build new templates and will also provide embeddable 'widgets' for use on other sites. They are not generally not re-usable in a wholly separate context, except the Embeddable Components

Server side rendering should be used for most pages where primary content is part of the document and then progressively enhanced with javascript. Searches and other complex UIs will be an exception.

Pages and Queries

URL routing determines what content to serve. It is highly flexible, but the core idea is sending the results of a GraphQL query as data into a template. What query and what template are determined by the route

Routes

Base

• "/"
  • Template: templates/index.html
  • Query: no query

Entity Pages

Such as for a person, publication, grant etc...

• "/entities/{type}/{id}" - fetches data for the given entity by 'id'
  • Template: templates/entity_pages/{type}.html
  • Query: templates/entity_pages/{type}.graphql
  • Query Parameters: id

Search

The search is essentially an SPA. It is not designed to run without javascript enabled. Since the entity pages are server-side rendered, and there is a sitemap, it is assumed SEO for the site content is handled by that

• "/search/{type}" - search pages, any html/javascript
  • Template: templates/search_pages/{type}.html
  • Query: assumes javascript will query GraphQL endpoint directly

List Pages

Although the purpose is already served by the search, there is also the capability of adding a browseable list of all entities that are server-side rendered. The examples here are rudimentary, since our demo site does not use them

• "/lists/{type}" - search pages, any html/javascript
  • Template: templates/list_pages/{type}/{type}.html
  • Query: templates/list_pages/{type}/{type}.graphql

This will send also accept paging parameters

Any Pages

Very flexible pages that can contain anything

• "/pages/{name}" - generic pages, any/html javascript with optional GraphQL query
  • Template: templates/any_pages/{name}.html
  • Query (optional): templates/any_pages/{name}.graphql
  • Query Parameters: Dynamic, derived from query string
  • Adding an Any Page

Sitemaps

Sitemaps for SEO purposes - so that search indexing services have a list of links to work with.

• "sitemap_pages/sitemap.xml" - main page that is a link to other (buildable) sitemaps
  • Template: templates/sitemap_pages/sitemap.xml
• "sitemap_pages/{type}/{type}.xml" - a sitemap file per specifications. It will run the backing GraphQL query and send data to the template
  • Template: templates/sitemap_pages/{name}/{name}.xml
  • Query: templates/sitemap_pages/{name}/{name}.graphql

Theme (Customizing)

Theme variables are set using the environment. The default values are populated in .env.example

Configurable theme variables include (note images would go in 'assets/images' directory):

• SITE_NAME - Site Name
• SITE_LOGO - Site Logo (image)
• THEME_BACKGROUND_IMAGE - Home Page Background (image or color)
• DEFAULT_PROFILE_IMAGE- Default profile image (to show if profile has no thumbnail) -
• GRAPHQL_ENDPOINT- Graphql endpoint (wherever scholars-discovery is running) -

Several colors are set by environmental variables as well:

• Color Palette: http://localhost:4200/docs/elements/color-palette

Additionally, custom styles may be added to:

assets/css/theme.scss

This file will be pre-processed with SASS and imported after all default stylesheets to allow specific overrides.

Embeddable Components

See Embedded list examples - most useful to use browser view source function

Advanced

Since all entity pages, and the searches, are merely templates matched up with GraphQL queries - it is fairly easy to customize what data is retrieved and shown on a page.

The search works the same, but to explain further - if you wanted to add your own facets TODO

if you wanted to add your own search ... TODO