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.

Breaking Changes

v1.0.0 — s3Url and apiUrl removed from dashboard:globalVars

The dashboard no longer provides s3Url or apiUrl as top-level properties in the injected dashboard:globalVars context. These values now live exclusively in services (e.g. services.s3Url, services.ApiUrl).

Widget libraries must update useGlobalVars.ts to remove s3Url/apiUrl from GlobalVarsShape and read them from services instead.

| PennsieveDashboard | SparcDashWidgets | PrecisionDashWidgets | |--------------------|------------------|----------------------| | >= 1.0.0 | >= 1.0.0 | >= 1.0.0 |

Pre-1.0 versions of these packages are not compatible with 1.0+. If you're building a custom widget library, use the services pattern described in Building a Component Library.

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

import { markRaw } from ‘vue’

const availableWidgets = [
  { name: ‘TextWidget’, component: markRaw(TextWidget) },
  { name: ‘MarkdownWidget’, component: markRaw(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.
• Wrap components with markRaw() to prevent Vue reactivity warnings. This is needed because Vue will attempt to make component objects reactive when they’re stored in reactive state (like ref() or reactive()), which is unnecessary and triggers console warnings. markRaw() tells Vue to skip reactivity for these objects.
• 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 services = {
  s3Url: "https://your-bucket.s3.amazonaws.com/your-data",
  ApiUrl: "https://api.pennsieve.net",
  // Add any other configurables your widgets need (API keys, endpoints, etc.)
};

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

• 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.
• services: key/value map of configurables (data URLs, API endpoints, API keys) that the dashboard provides to all widgets via useDashboardGlobalVars().services. Widgets read values like services.s3Url or services.ScicrunchApiKey from this object.
• dashboardOptions: combines global data, available widgets, layout, and services 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.

URL Parameters (Multi-Dashboard)

When using DashboardWrap (the multi-tab dashboard), you can pass URL query parameters to deep-link to a specific tab and pre-select genes. This is useful for sharing direct links to a particular view.

| Parameter | Required | Description | |-------------|----------|-------------| | dashboard | No | Name of the dashboard tab to activate (matched case-insensitively, spaces ignored) | | gene | No | Initial gene for widgets that accept initialGene / initialGene1 | | gene2 | No | Initial second gene for widgets that accept initialGene2 (e.g. co-expression) |

Examples:

# Open the "Side By Side" tab (spaces are ignored, so all of these work)
?dashboard=SideBySide
?dashboard=sidebyside
?dashboard=Side%20By%20Side

# Pre-select a gene across all widgets
?gene=TAC1

# Open a specific tab with a pre-selected gene
?dashboard=GeneDistribution&gene=SCN10A

# Pre-select two genes for co-expression views
?gene=SCN10A&gene2=TRPV1

When no URL parameters are present, behavior is unchanged — the dashboard uses its default tab and widget configuration.

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. Adding a Custom Component to an Existing Widget Library

Each widget library (e.g. SparcDashWidgets, PrecisionDashWidgets) follows the same component convention. Below is a real-world example — the BiolucidaViewer from SparcDashWidgets — showing how a component connects to the dashboard’s shared state via useDashboardGlobalVars().

<template>
  <!-- Scoped slot exposes the widget name and header icons to the dashboard shell -->
  <slot :widgetName="widgetName" :childIcons="childIcons"></slot>

  <div v-bind="$attrs" class="tw-flex tw-flex-col">
    <div v-if="selectedImage" class="bv-metadata">
      <div><b>Sex:</b> {{ selectedImage.sex }}</div>
      <div><b>Age:</b> {{ selectedImage.ageRange }}</div>
      <div><b>Sample Path:</b> {{ selectedImage.relativePath }}</div>
    </div>
    <div class="tw-h-screen tw-flex tw-justify-center">
      <iframe class="tw-p-1 tw-w-screen" :src="biolucidaPath"></iframe>
    </div>
  </div>
</template>

<script setup>
import { ref, computed, watch, shallowRef } from "vue";
import { useDashboardGlobalVars } from ‘../../useGlobalVars’
import { InfoFilled } from "@element-plus/icons-vue";

const widgetName = ref(‘MBF Image Viewer’);
const childIcons = shallowRef([
  { comp: InfoFilled, tooltip: "Lock Biolucida Viewer" }
]);

const props = defineProps({
  imageID: 0,
  isLocked: { default: false, type: Boolean }
});

// Access the dashboard’s injected global vars (services, filters, etc.)
const GlobalVars = useDashboardGlobalVars();

// Read a filter value reactively
const selectedImage = computed(() => {
  return GlobalVars?.filters?.SELECTED_IMAGE;
});

const biolucidaPath = ref("");

watch(selectedImage, (newVal, oldVal) => {
  if (newVal?.biolucidaID !== oldVal?.biolucidaID) {
    biolucidaPath.value = `https://sparc.biolucida.net/image?c=${newVal?.biolucidaID}`;
  }
}, { immediate: true });
</script>

The key takeaway: call useDashboardGlobalVars() in your component to access the dashboard’s shared state — services (data URLs, API keys), filters, and filter-setting methods — without any extra wiring. See the Building a Component Library section below for a full explanation of this composable.

3. Building a Component Library

If you’re building a new widget library (rather than adding to an existing one), you need to understand how the PennsieveDashboard communicates with widget components.

How the Dashboard Provides Context

When the PennsieveDashboard component mounts, it calls provide("dashboard:globalVars", ...) to inject a shared context object into the component tree. Any descendant component — including widgets from external libraries — can access this context using Vue’s inject.

The useGlobalVars.ts Composable

To access the injected context, your library should include a useGlobalVars.ts file (you can copy this directly from SparcDashWidgets):

// src/useGlobalVars.ts
import { inject } from ‘vue’

export const DASHBOARD_GLOBAL_VARS_KEY = ‘dashboard:globalVars’ as const
export type FilterValue = string | number | boolean | null | string[] | number[]
export type Filters = Record<string, FilterValue>
export type Services = Record<string, any>

export type GlobalVarsShape = {
  services: Services | import(‘vue’).Ref<Services>  // All configurables (URLs, API keys, etc.)
  filters: Filters | import(‘vue’).Ref<Filters>     // Shared reactive filter state
  setFilter: (key: string, value: FilterValue, isDisplayed?: boolean) => void
  clearFilter: (key: string) => void
  resetFilters?: (next?: Filters) => void
}

export function useDashboardGlobalVars(required = false) {
  const gv = inject<GlobalVarsShape | null>(DASHBOARD_GLOBAL_VARS_KEY, null)
  if (!gv && required) {
    console.warn(‘[Widget] dashboard:globalVars not provided.’)
  }
  return gv
}

What Each Property Does

| Property | Description | |----------|-------------| | services | Key-value map of configurables passed in from the host application — data URLs, API endpoints, API keys, etc. For example: services.s3Url, services.ApiUrl, services.ScicrunchApiKey. | | filters | Reactive key-value object representing the current dashboard filter state. Widgets read from this to stay in sync. | | setFilter(key, value, isDisplayed?) | Set a filter value. isDisplayed controls whether the filter chip appears in the dashboard header. | | clearFilter(key) | Remove a single filter by key. | | resetFilters(next?) | Clear all filters, optionally replacing them with next. |

Using Filters for Cross-Widget Communication

Filters are the primary mechanism for widgets to communicate. One widget sets a filter, and other widgets react to the change:

const GlobalVars = useDashboardGlobalVars();

// Read a service configurable (e.g. data URL, API key)
const dataUrl = unref(GlobalVars?.services)?.s3Url;
const apiKey = unref(GlobalVars?.services)?.ScicrunchApiKey;

// Set a filter (other widgets will see this reactively)
GlobalVars?.setFilter(‘SELECTED_GENE’, ‘CDH9’, true);

// Read a filter
const gene = GlobalVars?.filters?.SELECTED_GENE;

// Clear a filter
GlobalVars?.clearFilter(‘SELECTED_GENE’);

// Reset all filters
GlobalVars?.resetFilters();

Library Structure

A typical widget library follows this structure:

your-widget-library/
├── src/
│   ├── components/          # Widget components (public API)
│   │   ├── MyWidget/
│   │   │   └── MyWidget.vue
│   │   └── index.js         # Barrel export
│   ├── useGlobalVars.ts     # Copy from SparcDashWidgets
│   └── main.ts              # Dev entry point
├── package.json
└── vite.config.ts           # Build in library mode

Your vite.config.ts should build in library mode with vue, pinia, and element-plus as externals. See SparcDashWidgets or PrecisionDashWidgets for working examples.

Contact Support

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