7. Dashboard

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

Dashboard Elements

Dashboard. Displayed are the configurable elements of a Bento Dashboard. These are: Dashboard Sidebar Filters, Dashboard Widgets and Dashboard Table.

7.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 type(s) that return your data of interest.

7.2. Dashboard Sidebar Filters

The Dashboard Sidebar Filters allow an end user to search for data of interest by applying multiple filters, based on faceted classification, of stored data entities.
You can add a maximum of 12 filters. If you add more than 12 filters, Bento will display only the first twelve filters, without any warning or error message.

7.2.1. Configuring the Dashboard Sidebar Filters

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

  2. Under facetSearchData add an object {label: , field: , api: , datafield: , show: ,} to represent your filter.

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

    • Set the field field to the specific field in the GraphQL API query that is associated with your filter.

    • Set the field api to the GraphQL API query that returns data for your filter.

    • Set the field datafield to cross-reference the API query that responds to your filter. For example, if your filter drives a widget that displays data from responsive_api_query and it drives a column in the Dashboard table that displays data from responsive_api_query, then set the datafield to responsive_api_query.

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

    • Update GET_DASHBOARD_DATA_QUERY with the all GraphQL API queries and fields that are associated with your filters.

  3. Example:

...
export const facetSearchData = [
  {
    label: '<Filter Label>', 
    field: '<API query field>', 
    api: '<GraphQL API query>', 
    datafield: '<responsive_api_query>', 
    show: <'true|false'>,
  },
  ...
  ]
...
export const GET_DASHBOARD_DATA_QUERY = gql`{
 GraphQL API query{
 	API query field
 }
}

7.3. 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 widgets without any error or warning message.

7.3.1. Configuring the Dashboard Widgets

  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
 }
}

7.4. Dashboard Table

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 list the cases (or study subjects) in the program.
You can add a maximum of 10 columns to the Dashboard Table. If you add more than 10 columns, Bento will display only the first ten filters, without any warning or error message.

7.4.2. Configuring the Dashboard Table

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

  2. Under dashboardTable:

    • Set the field tableTitle to a Table Title of your choice.

    • To add a column, add an object {dataField: ,header: ,sort: ,link: ,primary: ,display: ,} to tableData.

      • Set the field dataField to the GraphQL API query field that returns the data for your column.

      • Set the field header to the column header for your column.

      • Add a sort field, if the Dashboard Table is to be sorted by the values of this column.Set the field set to ‘asc’ to sort table by ascending order on the column values, ‘desc’ to sort in the descending order.

      • Set the field link to an internal or external link that needs to be embedded into the column value. See below for additional information on adding internal and external links. Links are optional.

      • Add a primary field and set it to ‘true’ if values in this column are to be used to add the listed data entities to the Cart. For example, if you wish to select cases, in a Dashboard Table displaying cases, by the Case ID column to add to the cart, then the column storing case ids should have a primary field and it should be set to ‘true’.

      • Set the field display to ‘true’ if you wish to display the column and to ‘false’, otherwise.

    • Add your GraphQL API queries to GET_DASHBOARD_TABLE_DATA_QUERY.

  3. Example:

...
export const dashboardTable = {
  tableTitle: 'Cases',
  tableData: [
    // A maximum of 10 columns (tableData) are allowed
    {
      dataField: 'subject_id',
      header: 'Case ID',
      sort: 'asc',
      link: '/case/{subject_id}',
      primary: true,
      display: true,
    },
    ...
    ]
  }
  ...
export const GET_DASHBOARD_TABLE_DATA_QUERY = gql`{

}

7.5. Suggested Best Practice

  • 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.