10. Dashboard

The Dashboard provides the end user with several capabilities (a) filter data entities of interest via faceted filtering (b) view graphical summaries of data entities and (c) select data entities for further exploration.

Dashboard. Displayed are the configurable elements of a Bento Dashboard: widgets, faceted filtering, table, and tabs.

10.1. Prerequisites

1. The files that specify the configuration parameters of the Dashboard are stored in the GitHub https://github.com/CBIIT/bento-frontend (representing your GitHub username as YOUR-USERNAME). Create a local clone of your fork into a local directory, represented in these instructions as $(src).

2. Configuration parameters for Dashboard elements can be specified in the file: $(src)/bento-frontend/src/bento/dashboardData.js.

3. All images and icons that you use in your Bento instance should be accessible via a public url.

4. Please review the list of GraphQL queries to select query types that return your data of interest.

10.2. Configuring the Dashboard Widgets

Dashboard Widgets provide a graphical summary of the key data entities in your data sharing platform. In this version of Bento, you can add 3, 4 or 6 widgets. If you add more than 6 widgets, Bento will display the first 6 widgets without any error or warning message.

1. Open $(src)/bento-frontend/src/bento/dashboardData.js.

2. Under widgetsData add an object {type,label, dataName, datatable_field, show} to represent your widget.

   • Set the field type to the type of widget you want to display. Valid values are ‘donut’ and ‘sunburst’.

   • Set the field label to the display label for your widget.

   • Set the field dataName to the name of the GraphQL API query that returns data for your widget.

   • If your widget is of type ‘donut’, set the field datatable_field to the specific field in the GraphQL API query that returns data for your widget.

   • Sunburst widgets display two types of data within a single plot. If your widget is of type ‘sunburst’, set the fields datatable_level1_field and datatable_level2_field to the specific fields in the GraphQL API query that returns data for your sunburst. The field datatable_level1_field drives the inner ring of of the sunburst. The field datatable_level2_field drives the outer ring of of the sunburst.

   • Set the field show to ‘true’ to display the widget or to ‘false’, otherwise.

   • Enter all GraphQL API queries that drive the widgets in GET_DASHBOARD_DATA_QUERY.

3. Example:

...
export const widgetsData = [
  {
    type: 'sunburst',
    label: '<Widget Label>',
    dataName: '<GraphQL API query that returns data for widget>',
    datatable_level1_field: '<GraphQl API query field that returns data for inner ring of sunburst>',
    datatable_level2_field: '<GraphQl API query field that returns data for outer ring of sunburst>',
    show: '<true|false>',
  },
  {
    type: 'donut',
    label: 'Diagnosis',
    dataName: '<GraphQL API query that returns data for widget>',
    datatable_field: '<GraphQl API query field that returns data for donut>',
    show: '<true|false>',
  },
  ...
  ]
...
export const GET_DASHBOARD_DATA_QUERY = gql`{
 GraphQL API query{
 	API query field
 }
}  

10.3. Configuring Faceted Filtering

The dashboard’s facet filters allow an end user to search for data of interest by applying multiple filters, based on faceted classification of stored data entities.

The faceted filtering on the dashboard’s side bar can be organized into into facet sections, each with a maximum count of 15 facets that are associated with facet values that can be used for filtering data upon selecting the respective checkboxes.

To configure the facets:

• Open the configuration file located at bento-frontend/src/bento/dashboardData.js (in the “CBIIT/bento-frontend” git repo)

• To represent your facet, edit or create a facet object under the facetSearchData object

• Each facet is defined as follows:

  • label: the display label for your facet that appears in the sidebar

  • field: the specific field in the GraphQL API query, as the api

  • api: the GraphQL api query: GET_DASHBOARD_DATA_QUERY returns data for your facet. (It is in the same file: dashboardData.js)

• datafield: the variable used to cross-reference/pass data to widgets and dashboard data tables, see: bento-frontend/src/bento/dashboardTabData.js (described in Dashboard: Tabs and Tables)

• section: the facet section that the facet should appear in the sidebar

• show: controls if the facet is displayed or hidden (must be true or false)

• Note that the order of the facet sections and individual facets nested in each facet section is controlled by the order of the entries of the facets in the facetSearchData object

For Example:

  export const facetSearchData = [
{
  label: 'Program', 
  field: 'group', 
  api: 'subjectCountByProgram', 
  apiForFiltering: 'filterSubjectCountByProgram', 
  datafield: 'programs', 
  section: 'Cases', 
  show: true,
},
{
  label: 'Tissue Composition', 
  field: 'group', 
  api: 'subjectCountByTissueComposition', 
  apiForFiltering: 'filterSubjectCountByTissueComposition', 
  datafield: 'composition', 
  section: 'Samples', 
  show: true,
},

NOTE: Update the GraphQL API Query in GET_DASHBOARD_DATA_QUERY as needed; it should contain all queries and fields that are associated with your facets

To enable sort:

• Open the configuration file located at bento-frontend/src/bento/dashboardData.js (in the “CBIIT/bento-frontend” git repo)

• Edit the values in sortLabels to enable or disable For example:

  export const sortLabels = {
  sortAlphabetically: 'Sort alphabetically',
  //sortByCount: 'Sort by counts',
  showMore: '...expand to see all selections',
  };
  

To set the maximum number of active selections displayed when a facet is collapsed:

• Open the configuration file located at bento-frontend/src/bento/dashboardData.js (in the “CBIIT/bento-frontend” GitHub repo)

• Edit the value of showCheckboxCount For example:

export const showCheckboxCount = 6;

10.3.1. Faceted Search Styling

The style of each facet section of the side bar can be easily configured.

• Open the configuration file located at bento-frontend/src/bento/dashboardData.js (in the “CBIIT/bento-frontend” git repo)

• Edit the value for corresponding ‘section’ under facetSectionVariables object

  For example:

  export const facetSectionVariables = {
  Cases: {
    color: '#10A075',
    backgroundColor: '#C0E9D7',
    checkBoxColorsOne: '#E8F7DC',
    checkBoxColorsTwo: '#F5FDEE',
    height: '5px',
    isExpanded: true,
  },
  

10.4. Configuring Dashboard Tables & Tabs

The dashboard is structured to organize the data tables using tabs beneath the widgets. The Dashboard Table can be configured to list key data entities in your data sharing platform along with a list of key data entity attributes. In the Bento reference implementation the Dashboard Table lists the cases (or study subjects) in the program.

The tabs can be configured as follows:

1. Open $(src)/bento-frontend/src/bento/dashboardTabData.js

2. To change Properties of tab go to tabs object:

• name : Text to show on tab

• dataField: specifies what data appears in the column, field must be from the GraphQL API query

NOTE: the order of the entries in tabs should match the order in the tabsIndex object. This is the order that the tabs will be displayed left to right on the UI.

To change the style of the tabs go to tabIndex object:

• title : Text to shown on tab

• primaryColor : background color when tab is selected

• selectedColor : font color when tab is selected

NOTE: the order of the entries in tabIndex should match the order in the tabs object. This is the order that the tabs will be displayed left to right on the UI.

The tables displayed in each tab can be configured as follows:

1. Open $(src)/bento-frontend/src/bento/dashboardTabData.js

2. The tabContainers object is an array of tables, with each table object having the following fields:

• dataField : field name in “Data” object to get values for table.

NOTE: This field should be in the GraphQL API query specified in the api field.

• defaultSortField: Value must be one of the ‘dataField’ in columns.

• defaultSortDirection: Sort default column in Ascending or Descending order (value must be asc or desc)

• buttonText: Text to appear on Add to cart button

• saveButtonDefaultStyle: Style of on Add to cart button, with fields such as

      color: '#fff',
      backgroundColor: '#09A175',
      opacity: '1',
      border: '0px',
      cursor: 'pointer',
  

• ActiveSaveButtonDefaultStyle: Style of on Add to cart button when it is active mode

• DeactiveSaveButtonDefaultStyle: Style of on Add to cart button when it is disabled mode

• columns: a list of column objects. There is a maximum limit of 10 columns. If more than 10 columns are added, Bento will display the first 10 columns without an error or warning message. The top-down order of columns will be displayed left to right on the UI. Each column object is described by the following fields:

  • dataField: specifies what data appears in the column, field must be from the GraphQL API query

  • header: Heading Text for column

  • sort: sort order for column

    • must be asc or desc

  • primary: applies to primary field of table like “sample_ID” or “File_ID” based on which files will be added in to cart.

    • must be true or false

  • display: Show or Hide column

    • must be true or false

  • dataFromRoot: Get data from parent element.

    • must be true or false

  • link: Hyperlink to internal or external page. The value can be injected in link dynamically using {datafield}, for example:

    // Internal Link 
    link: '/arm/{dataField}',
    
    // External Link
    link: 'https://example.com/{dataField}',
    

10.4.1. Internal Links in the Dashboard Table

1. links starting with / are considered as internal links.

2. Internal links will be opened in the same tab.

3. Dynamic links can be generated by passing a valid table field to {}. For example, /program/{program_id} will link to program/NCT00310180.

10.4.2. External Links in the Dashboard Table

1. External links should start with http:// or https://.

2. External links should show-up with externalLinkIcon.

3. External link will be opened in a new tab.

4. Dynamic links can be generated by passing a valid table filed to {}. For example, https://pubmed.ncbi.nlm.nih.gov/{pubmed_id} will link to https://pubmed.ncbi.nlm.nih.gov/29860917/

10.4.3. Tool Tips

To change Properties of tool tip for each tab, table go to tooltipContent object:

• icon: The help tip icon that appears next to the ‘add button’

• alt: alt for the tooltip image

• 0,1,2: tooltip content for first tab, second tab and third tab.

10.4.4. GraphQL Queries

The GraphQL Query used in the Dashboard page is defined in DASHBOARD_QUERY. For example:

// GraphQL query to retrieve detailed info for a case
export const DASHBOARD_QUERY = gql`{
  numberOfPrograms
  numberOfStudies
  numberOfSubjects
  numberOfSamples
  numberOfLabProcedures
  numberOfFiles
  subjectCountByProgram{
        group
        subjects
      }
...
    fileOverview {
        file_id
        file_name
        association
        file_description
        file_format
        file_size
        program
        arm
        subject_id
        sample_id
        diagnosis
    }
  }`;

10.4.5. Suggested Best Practices

• Dimension of the External Link Icon = 16 X 16 pixels.

• All images should have a resolution >= 72 ppi and should be in the PNG format.

:warning: WARNING: You can add a maximum of 10 columns to the dashboard tab table. If you add more than 10 columns, Bento will display only the first ten columns, without any warning or error message