7. Program Detail Page

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

Program Detail Page Elements. Displayed are the configurable components of a Bento Program Detail Page: Program Detail Page Title, Program Detail Page Subtitle, Program Detail 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. The files that specify the configuration parameters of the Bento Landing Page 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 all Program Detail Page elements can be specified in the file: $(src)/bento-frontend/blob/master/src/bento/programDetailData.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. 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)/bento-frontend/src/bento/programDetailData.js.

2. Under pageTitle:

   • Set the field label to the Page Title of your choice.

   • Set the field datafield to the GraphQl API query that returns the 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 of your choice.

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

5. Add your 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 allows you to display a Program level count for an key data entity in your data sharing platform.

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

2. Under aggregateCount:

   • Set the field labelText to the display text for the aggregate count of your choice.

   • Set the field dataField to the GraphQL API query that returns your 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’ if you want to display an aggregate count, ‘false’ otherwise.

3. Add your 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 Detail Page

The Progam Detail Page supports a Program Detail 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)/bento-frontend/src/bento/programDetailData.js.

2. Under programDetailIcon:

   • Set the field ‘src’ to the URL for the Program Detail Page Icon of your choice.

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

3. Under externalLinkIcon:

   • Set the field ‘src’ to the URL for the External Link Icon of your choice.

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

4. Example:

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

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

7.5. Configuring the Program Detail Page Panels

The Program Detail 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 you add more than 6 attributes, Bento will display only the first 6 attributes without a warning or error message.

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

2. Under leftPanel:

   • Add an object ({dataField: ; label: })to the attribute list.

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

   • Set the field label to a display label of your choice.

3. Add your GraphQL API queries to PROGRAM_DETAIL_QUERY.

4. You can add an embedded link to your label or your value, or both. Links can be internal or external.

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

   • To add a link to your label specify an internal or external link by adding a internalLinkToLabel or externalLinkToLabel attribute, respectively, to your 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 = {
  attribute: [
    {
      //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.6. Configuring the Right Hand Panel

In the current version of Bento, you can (a) add a donut widget that displays the counts by value of a key data entity in your data sharing platform and (b) add a count of files stored for the given program.

7.6.1. Configuring the Donut widget

1. Open $(src)/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 your 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.6.2. Configuring the File Count widget

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

1. Open $(src)/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 of your choice.

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

   • Set the field display to ‘true’ if you want 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.7. The Program Detail Page Table

The Program Detail Page table can be used to display program-level information such as the studies or projects that belong to the program.

7.7.1. Configuring the Program Detail Page Table.

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

2. In table:

• The display field is set to true, by default. Set this field to false if you do not wish to display a table in the Program Detail Page.

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

• Set the field dataField to the name of the GraphQL API query being used to return data for the Program Detail 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 Detail Page Table. Note: this query field should be displayed as one of the columns in the Program Detail Page Table.

• Set the field defaultSortDirection to the sort order of your choice. Valid values are ‘asc’ (ascending) and ‘desc’ (descending).

• Add your 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.7.2. Adding columns to the Program Detail Page Table.

You can add up to 10 columns in the Program Detail Page Table. If you add 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)/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 your 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.7.2.1. Internal Links in the Program Detail 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.7.2.2. External Links in the Program Detail 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.8. Suggested Best Practice

• Dimension of the Program Detail 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.