7. The Program Details Page

The Program Details Page displays detailed, program-level information for each of the programs that has submitted data to a Bento-based data sharing platform. A Bento Program Details Page has several configurable components. See below for details.

Program Details Page Elements. Displayed are the configurable components of a Bento Program Details Page: Program Details Page Title, Program Details Page Subtitle, Program Details Page Icon, Breadcrumb, Data Labels, Data Fields, Table Title, Table Column Header, Table Column Content, Program-Level Aggregate Count, Program-Level Donut Widget, Program-Level File Count Widget and Embedded External and Internal Links.

7.1. Prerequisites

1. Files that specify the configuration parameters of the Bento Landing Page are stored in 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 all Program Details Page elements can be specified in the file: $(src)/packages/bento-frontend/src/bento/programDetailData.js.

3. All images and icons used in a Bento instance should be accessible via a public url.

4. Please review the list of GraphQL queries to select query type(s) that return the data of interest.

7.2. Page Title Configuration

The Page Title section has three components: (a) Page Title (b) Page Subtitle and (c) Breadcrumb.

7.2.1. Configuring the Page Title, Page Subtitle and Breadcrumb

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

2. Under pageTitle:

   • Set the field label to the Page Title that is desired.

   • Set the field dataField to the GraphQl API query that returns the respective Page Title.

3. Under pageSubTitle:

   • Set the field dataField to the GraphQL API query that will return the Page Subtitle.

4. Under breadCrumb:

   • Set the field label to the Breadcrumb text that is desired.

   • Set the field link to the internal link to be embedded in the Breadcrumb.

5. Add GraphQL API queries to PROGRAM_DETAIL_QUERY.

6. Example:

...
const pageTitle = {
  label: '<Your Page Title>',
  dataField: '<GraphQL API query that returns the Page Title>',
};

const pageSubTitle = {
  dataField: '<GraphQL API query that returns the Page Subtitle>',
};

const breadCrumb = {
  label: '<Your Breadcrumb display text>',
  link: '<Your Breadcrumb embedded link>',
};
...

7.3. Configuring the Aggregate Count

The Program-Level Aggregate Count field displays the total number of Programs in the data sharing platform.

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

2. Under aggregateCount:

   • Set the field labelText to the display text for the aggregate count that is desired.

   • Set the field dataField to the GraphQL API query that returns the respective aggregate count.

   • Set the field ‘link’ to the embedded link for the aggregate count. This is usually a link to an internal page that displays additional detail on the aggregate count.

   • Set the field display to ‘true’ to display an aggregate count, ‘false’ otherwise.

3. Add GraphQL API queries to GET_PROGRAM_DETAIL_DATA_QUERY.

4. Example:

...
const aggregateCount = {
  labelText: '<Display label for your Aggregate Count>',
  dataField: '<GraphQL API query that returns your Aggregate Count>',
  link: '<embedded link for you Aggregate Count>',
  display: '<true|false>',
};
...
const GET_PROGRAM_DETAIL_DATA_QUERY = gql`{
  ...
  '<Your GraphQL API query>'
  ...
}

7.4. Configuring Icons in the Program Details Page

The Progam Details Page supports a Program Details Page Icon, displayed next to the Program Title, and an External Link Icon, that is displayed next to an external link in the page.

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

2. Under programDetailIcon:

   • Set the field ‘src’ to the URL for the Program Details Page Icon that is desired.

   • Set the field ‘alt’ to the ALT tag for the Program Details Page Icon.

3. Under externalLinkIcon:

   • Set the field ‘src’ to the URL for the External Link Icon that is desired.

   • Set the field ‘alt’ to the ALT tag for the External Link Icon.

4. Example:

...
const programDetailIcon = {
  src: '<URL to your Program Details Page Icon>',
  alt: '<ALT tag for your Program Details Page Icon>',
};

const externalLinkIcon = {
  src: '<URL to your External Link Icon>',
  alt: '<ALT tag for your External Link Icon>',
};
...

7.5. Configuring the Program Details Page Panels

The Program Details Page is divided into a Left-Hand Panel and a Right-Hand Panel. The Left Panel displays a set of Program specific details in the form of label-value pairs. The Right Panel displays Program level information as a set of graphics.

7.5.1. Configuring the Left-Hand Panel

The left panel can display a maximum of 6 attributes as label:value pairs. If adding more than 6 attributes, Bento will display only the first 6 attributes without a warning or error message.

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

2. Under leftPanel:

   • Add an object ({ dataField: , label: }) to the attributes list.

   • Set the field dataField to the GraphQL API query that returns the desired data field. This will be displayed as the value of a label:value pair.

   • Set the field label to the display label.

3. Add GraphQL API queries to PROGRAM_DETAIL_QUERY.

4. Embedded links can be added to labels or values, or both. Links can be internal or external.

   • To add a link to a value specify an internal or external link by adding a link attribute to the object.

   • To add a link to a label specify an internal or external link by adding a internalLinkToLabel or externalLinkToLabel attribute, respectively, to the object. Examples of four types of embedded links are given below. See below for additional notes on adding internal and external links.

5. Example:

...
const leftPanel = {
  attributes: [
    {
      //Label:Value pair with an internal link embedded in the Value.
      dataField: '<GraphQL API query that returns the data for this label/value pair>',
      label: '<Label text for this label/value pair>',
      link : '</programs/{program_id}>',
    },
    {
      //Label:Value pair with an external link embedded in the Value.
      dataField: '<GraphQL API query that returns the data for this label/value pair>',
      label: '<Label text for this label/value pair>',
      link : '<https://cancer.sanger.ac.uk/cosmic/mutation/overview?id=113681877>',
    },
    {
      //Label:Value pair with an internal link embedded in the Label.
      dataField: '<GraphQL API query that returns the data for this label/value pair>',
      label: '<Label text for this label/value pair>',
      internalLinkToLabel: '</programs/{program_id}>',
    },
    {
      //Label:Value pair with an external link embedded in the Label.
      dataField: '<GraphQL API query that returns the data for this label/value pair>',
      label: '<Label text for this label/value pair>',
      externalLinkToLabel: '<https://cancer.sanger.ac.uk/cosmic/mutation/overview?id=113681877>',
    },
    ...
    ]
  }
...
  const GET_PROGRAM_DETAIL_DATA_QUERY = gql`{
    ...
    '<Your GraphQL API query>'
    ...
  }

7.5.1.1. Internal Links to Labels and Values

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

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

3. Dynamic links can be generated by passing a valid table filed to ‘{}’. For example, ‘/arm/{study_acronym}’ shall link to ‘arm/A’

7.5.1.2. External Links to Labels and Values

1. External links shall start with ‘http://’ or’https://’

2. External links shall show-up with ‘externalLinkIcon’

3. External link shall 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}’ shall link to ‘https://pubmed.ncbi.nlm.nih.gov/29860917/’

7.5.2. Configuring the Right-Hand Panel

In the current version of Bento, donut widgets can be added to display the counts by value of any key data entity in the data sharing platform and (b) adding a count of files stored for a given program.

7.5.2.1. Configuring the Donut Widgets

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

2. Under rightPanel:

• Under widget:

  • Set the field dataField to the GraphQL API query that returns the counts by value for a data entity.

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

  • Set the field display to true if you want to display the widget and to false, otherwise.

  • Update GET_PROGRAM_DETAIL_DATA_QUERY with yor GraphQL API query.

1. Example:

...
const rightPanel = {
  widget: [
    {
      dataField: '<GraphQl API that returns the counts by value for your data entity>',
      label: '<Widget Label>',
      display: 'true|false',
    },
  ],
  ...
}
...
const GET_PROGRAM_DETAIL_DATA_QUERY = gql`{
    ...
    '<Your GraphQL API query>'
    ...
}
...

7.5.2.2. Configuring the File Count Widgets

The File count graphic displays the number of Program Level files.

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

2. Under files:

   • Set the field dataField to the GraphQL API query that returns the number of program-level files.

   • Set the field label to the display label text for the File Count widget.

   • Set the field fileIconSrc to the URL for the File Icon that is desired.

   • Set the field fileIconAlt to the ALT tag for the File Icon.

   • Set the field display to ‘true’ to display the File Count widget and to ‘false’, otherwise.

   • Update GET_PROGRAM_DETAIL_DATA_QUERY with the API query that returns file counts.

3. Example:

...
const rightPanelAttributes = {
  ...
  files: [
    {
      dataField: '<GraphQL API returning program level file count>',
      label: '<Display label for File Count widget>',
      fileIconSrc: '<URL for File Icon image>',
      fileIconAlt: '<ALT tag for File Icon>',
      display: 'true|false',
    },
  ],
};
...
const GET_PROGRAM_DETAIL_DATA_QUERY = gql`{
    ...
    '<Your GraphQL API query>'
    ...
}
...

7.6. The Program Details Page Table

The Program Details Page Table can be used to display program-level information such as the studies or projects, cases or subjects, and other key metadata that belong to the program.

7.6.1. Configuring the Program Details Page Table

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

2. In table:

• The display field is set to true, by default. Set this field to false to disable the table in the Program Details Page.

• Set the field title to the the title of the table.

• Set the field dataField to the name of the GraphQL API query being used to return data for the Program Details Page. Note: This query should match the GraphQL API query in GET_PROGRAM_DETAIL_DATA_QUERY.

• Set the field defaultSortField to the name of the query field that will be used to sort the Program Details Page Table. Note: this query field should be displayed as one of the columns in the Program Details Page Table.

• Set the field defaultSortDirection to the sort order that is desired. Valid values are ‘asc’ (ascending) and ‘desc’ (descending).

• Add the GraphQL API query to GET_PROGRAM_DETAIL_DATA_QUERY.

1. Example:

...
const table = {
  display: true,
  title: '<Table Title>',
  dataField: '<GraphQL API query returning data for this page.>',
  defaultSortField: '<GraphQL API query field used to sort the table.>',
  defaultSortDirection: '<sort order, asc|desc>',
 ...
const GET_PROGRAM_DETAIL_DATA_QUERY = gql`{
  '<Your GraphQL query>'' {
    '<Data fields returned by your GraphQL API query>'
  ... 
 }
}

7.6.2. Adding Columns to the Program Details Page Table

Up to 10 columns can be added in the Program Details Page Table. If adding more than 10 columns, 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.

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

2. Under table, add an object {dataField: , header: , link: ,} to the columns list:

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

• Set the field header to the column header name.

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

• Add the GraphQL API query data field to GET_PROGRAM_DETAIL_QUERY.

1. Example:

const table = {
  ...
  columns: [
    {
      dataField: '<GraphQL API query field returning data for this column>',
      header: '<Column Header>',
      link: '<link to be embedded in column value>',
    },
    {
      dataField: '<GraphQL API query field returning data for this column>',
      header: 'PubMed ID',
    },
    ...
  ],
};

const GET_PROGRAM_DETAIL_DATA_QUERY = gql`{
  '<Your GraphQL query>'' {
    '<Data fields returned by your GraphQL API query>'
  ... 
 }
}

7.6.2.1. Internal Links in the Program Details Page Table

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

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

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

7.6.2.2. External Links in the Program Details Page Table

1. External links shall start with ‘http://’ or’https://’.

2. External links shall show-up with ‘externalLinkIcon’.

3. External link shall 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}’ shall link to ‘https://pubmed.ncbi.nlm.nih.gov/29860917/’.

7.7. Suggested Best Practices

• Dimension of the Program Details Page Icon= 107 X 107 pixels

• Dimension of the File Icon = 66 X 53 pixels

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