Vue 3 + TypeScript + Vite

PennsieveDashboard

The PennsieveDashboard is a web application that provides a user interface for interacting with Pennsieve data, visualizing metrics, and managing dashboards relevant to scientific datasets.

Table of Contents

• Features

• Getting Started

  • Prerequisites
  • Installation

• Usage

• Contributing

• Contact / Support

Features

• Dashboard views for Pennsieve, Sparc, and Percision
• Visual metrics and charts (e.g. usage, growth)
• Authentication and role-based access
• Publishing and versioning support
• Tag filtering and search

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (version ≥ 14)
• npm or Yarn
• Element Plus (^2.11.0)
• Pinia (^3.0.3)

Installation

1. Clone the repository:

   git clone https://github.com/Pennsieve/PennsieveDashboard.git
   cd PennsieveDashboard
   

2. Install

   npm install
   # or
   yarn install

3. App.vue For install and testing copy and paste this into your App.vue

//App.vue
<script setup>
import { computed, ref } from 'vue';
import {PennsieveDashboard, MarkdownWidget, TextWidget} from 'pennsieve-dashboard'
import 'element-plus/dist/index.css';
import 'pennsieve-dashboard/style.css'

/*
Computed
*/
const publicationStatus = computed(() => {
  return "foobar"
});

const filesCount = computed(() => {
  return "b"
});

const collaboratorCounts = computed(()=>{
  return "a"
})


const availableWidgets = [
  //name must match componentKey
  { name: 'TextWidget', component: TextWidget },
  {name:'MarkdownWidget',component:MarkdownWidget}
]
const defaultLayout = [
        {
          id: 'MarkdownWidget-6',
          x: 0, y: 0, w: 3, h: 9,
          componentKey: 'MarkdownWidget',
          componentName: 'Markdown Widget',
          component: MarkdownWidget,   
          Props:{
            markdownText:[
          '# Human DRG Dataset Dashboard',
          '',
          'This is a dashboard associated with the **NIH HEAL PRECISION Human Pain** consortium project. It aggregates data from several U19 centers in a standardized way. Using the different widgets, you can view, query and export the data in various ways:',
          '',
          '## Widgets',
          '',
          '### UMAP Viewer',
          'This widget provides the UMAP representation of the entire dataset, you can select the color mapping based on different metadata elements.',
          '',
          '### The Data Explorer',
          'Directly query over the data using SQL and export the results as a CSV file.',
          '',
          '### Proportion Viewer',
          'Explore metrics between the different datasets that comprise the aggregated data.'
        ].join('\n')
          }
        },
        { 
          id: "TextWidget-1", 
          x: 0, y: 0, h: 1, w:4, 
          componentName:"Text",
          componentKey:"TextWidget",
          component:TextWidget,
          hideHeader:true, 
          Props:{displayText:"Dataset Overview",hideHeader:true}
        },
        { 
          id: "TextWidget-2", 
          x: 0, y: 1, h: 2, w:1, 
          componentName:"Files",
          componentKey:"TextWidget",
          component:TextWidget,
          Props:{bindedKey:"FileCount"} 
        },
        { 
          id: "TextWidget-3", 
          x: 1, y: 1, h: 2, w:2, 
          componentName:"Status",
          componentKey:"TextWidget",
          component:TextWidget,
          Props:{bindedKey:"Status"}
        },
        { 
          id: "TextWidget-4", 
          x: 3, y: 1, h: 2, w:2, 
          componentName:"Collaborator Counts",
          componentKey:"TextWidget",
          component:TextWidget,
          Props:{bindedKey:"CollaboratorCounts"}
        }
      ]

const dashboardOptions = ref({
  globalData: {
    FileCount: filesCount.value,
    Status: publicationStatus.value,
    CollaboratorCounts: collaboratorCounts.value
  },
  availableWidgets,
  defaultLayout,
})

</script>
<template>
      <PennsieveDashboard class="dashboard-app" :options="dashboardOptions"></PennsieveDashboard>

</template>

<style scoped>
/* set style vars from outside the dashboard > customize to match your application */
.dashboard-app{
    --el-color-primary: #243d8e;
    --el-color-primary-light-3: #fbfdff;
    --el-color-primary-dark-2: #546085;
    --color:#243d8e;
    --el-dialog-width: 90%;
    --dash-secondary: #243d8e;
  }

</style>

4. Run

npm run dev

Usage

Using the Dashboard and Widgets

The Pennsieve Dashboard can be used in two ways:

1. Standalone – with its built-in widgets.
2. Extended – by integrating with external widget libraries, such as the SPARC Widgets Library.
   • You can see a demo of the SPARC dashboard in action here: SPARC Dashboard Demo.

Built-in Widgets

The dashboard ships with a small set of widgets out of the box. These can be used immediately to create dashboards without adding external libraries.

• Markdown Widget
  Displays formatted text using Markdown syntax. Useful for adding documentation, context, or descriptive notes directly in the dashboard.

• Text Widget
  Displays plain or bound text values (e.g., counts, statuses, labels). Useful for lightweight metrics and quick information displays.

Adding Widgets to the Dashboard

Widgets are registered in the availableWidgets array, and their default layout is defined in the defaultLayout configuration. Each widget requires:

• A unique id
• Position and size (x, y, w, h)
• componentKey (must match the widget’s registration name)
• componentName
• Props (e.g., displayText, markdownText, bindedKey)

Example: Embedding the Dashboard in Your Application

The following example shows how to embed the Pennsieve Dashboard into a Vue 3 application.
The example is broken down into six key parts so developers can understand how each piece works and how to extend it.

1. Imports

import { computed, ref } from 'vue';
import { PennsieveDashboard, MarkdownWidget, TextWidget } from 'pennsieve-dashboard';
import 'element-plus/dist/index.css';
import 'pennsieve-dashboard/style.css';

• Vue imports:
  • ref – for reactive state.
  • computed – for derived or dynamic values you want to expose to widgets.
• Dashboard & widgets: import the core PennsieveDashboard component along with any widgets you want to use (in this case, MarkdownWidget and TextWidget).
• Styles:
  • element-plus/dist/index.css – required styles for the Element Plus UI library.
  • pennsieve-dashboard/style.css – base dashboard styling.

Without these, the dashboard and widgets will not render correctly.

2. Available Widgets

const availableWidgets = [
  { name: 'TextWidget', component: TextWidget },
  { name: 'MarkdownWidget', component: MarkdownWidget }
];

• This array registers which widgets the dashboard can use.
• Each widget entry must define:
  • name – must match the widget’s componentKey in the layout.
  • component – the imported Vue component.
• You can extend this list with custom widgets or external widget libraries.

3. Default Layout

const defaultLayout = [
  {
    id: 'MarkdownWidget-6',
    x: 0, y: 0, w: 3, h: 9,
    componentKey: 'MarkdownWidget',
    componentName: 'Markdown Widget',
    component: MarkdownWidget,
    Props: {
      markdownText: "# Human DRG Dataset Dashboard\n..."
    }
  },
  {
    id: "TextWidget-1",
    x: 0, y: 0, h: 1, w: 4,
    componentName: "Text",
    componentKey: "TextWidget",
    component: TextWidget,
    hideHeader: true,
    Props: { displayText: "Dataset Overview" }
  }
  // additional TextWidget entries...
];

• Controls how widgets are arranged on the grid.
• Each widget requires:
  • id – unique identifier for the widget instance.
  • x, y, w, h – grid position and size.
  • componentKey – must match the name from availableWidgets.
  • componentName – display label for the widget.
  • Props – configuration for the widget (text content, markdown, or bound keys).
• Developers can define multiple widgets and fine-tune their placement.

4. Dashboard Options

const publicationStatus = computed(() => "foobar");
const filesCount = computed(() => "b");
const collaboratorCounts = computed(() => "a");

const dashboardOptions = ref({
  globalData: {
    FileCount: filesCount.value,
    Status: publicationStatus.value,
    CollaboratorCounts: collaboratorCounts.value
  },
  availableWidgets,
  defaultLayout,
});

• Computed values: hold live data you want to expose inside the dashboard. These could come from an API call or another reactive source.
• globalData: key/value pairs accessible to widgets. For example, a TextWidget can bind to FileCount or Status.
• dashboardOptions: combines global data, available widgets, and layout into a single configuration object that powers the dashboard.

5. Template

<template>
  <PennsieveDashboard class="dashboard-app" :options="dashboardOptions" />
</template>

• Renders the PennsieveDashboard component.
• The :options prop passes in the configuration created above.
• Any widget defined in defaultLayout will be rendered automatically.

6. Styles

<style scoped>
.dashboard-app {
  --el-color-primary: #243d8e;
  --el-color-primary-light-3: #fbfdff;
  --el-color-primary-dark-2: #546085;
  --color: #243d8e;
  --el-dialog-width: 90%;
  --dash-secondary: #243d8e;
}
</style>

• Dashboard styling can be overridden using CSS variables.
• Customize colors, spacing, and UI elements to match your application’s theme.

Contributing

Contributing

We welcome contributions from developers and the community. There are two main ways you can get involved:

1. Reporting Bugs or Issues

If you encounter a bug, performance problem, or unexpected behavior in the dashboard:

• Please report it through the official support channels.
• Include as much detail as possible (steps to reproduce, screenshots, browser/OS version, etc.) so we can investigate and resolve quickly.

2. Building Custom Widget Libraries

The dashboard is designed to be extensible. Developers can build their own widget libraries and plug them into the dashboard.

For reference, check out the SPARC Dash Widgets Library, which provides an example of how to build custom widgets. You can also see it in action at the SPARC Dashboard Demo.

Sample Component

Here’s a minimal example of a custom widget component:

//vue
<template>
  <!-- Child icons show up in the widget header -->
  <slot :widgetName="widgetName" :childIcons="childIcons"></slot>

  <div class="my-widget-name-wrap" v-bind="$attrs">
    <!-- Component body goes here -->
  </div>
</template>

<script setup lang="ts">
import { ref, watch, computed, shallowRef } from 'vue'
import { Edit } from '@element-plus/icons-vue'

defineOptions({ inheritAttrs: false })

// Props can be passed in from the defaultLayout in dashboard options or set programmatically.
const props = defineProps<{
  property1?: string
}>()

const emit = defineEmits<{
  (e: 'updateComponent', value: string): void
}>()

// Provide values for your scoped slot so it doesn't error
const widgetName = 'example widget'
const childIcons = shallowRef([
  { comp: Edit, event: toggleMode, tooltip: 'click to open edit mode' }
])

function toggleMode() {
  // Custom code for toggling edit mode
}
</script>

Contact Support

There are several ways to get in contact with our support team. support page https://discover.pennsieve.io/about/support