Extending the Platform: Adding New Bio Apps
Relevant source files
The following files were used as context for generating this wiki page:
The platform architecture is designed to be highly extensible, allowing developers to integrate new biological analysis tools (Bio Apps) by following a standardized widget-based framework. New applications leverage a base inheritance model that provides common functionalities such as workspace integration, job submission, input validation, and user authentication.
Integrating a new Bio App primarily involves creating a specialized JavaScript widget that inherits from AppBase.js, defining a corresponding HTML template for the UI, and configuring the data payload required by the backend service. This architecture ensures consistency across different tools like BLAST, MSA, and RNA-Seq analysis while minimizing code duplication.
Core Architecture and Inheritance
The foundation of every Bio App is the AppBase class. This class handles the lifecycle of an application, from rendering the login interface for authenticated services to managing file uploads and submitting job parameters to the AppService.
The AppBase Framework
All Bio Apps inherit from p3/widget/app/AppBase. This base widget provides standardized attach points and methods for:
- Authentication: Using
requireAuthto gate access. - Workspace Selection: Integrating
WorkspaceObjectSelectorfor inputs and outputs. - Job Lifecycle: Managing the transition between
Working,Submitted, andErrorstates. - Form Handling: Utilizing
dijit/form/Formmixins for validation and value retrieval.
Sources: public/js/p3/widget/app/AppBase.js:1-30, public/js/p3/widget/app/BLAST.js:81-85
Application Lifecycle Flow
The following diagram illustrates the typical initialization and submission flow for a new Bio App widget.
The startup function is critical for initializing default workspace paths and setting up event listeners for advanced options toggles.
Sources: public/js/p3/widget/app/AppBase.js:150-180, public/js/p3/widget/app/BLAST.js:95-110
Implementation Components
To add a new application, developers must implement several key methods and properties within their inherited widget.
1. Configuration Properties
Developers define metadata that identifies the app to the backend and provides documentation links.
| Property | Description | Example |
|---|---|---|
applicationName | Unique ID used by the backend service. | "RNASeq" |
applicationLabel | Human-readable title for the UI. | "RNA-Seq Analysis" |
requireAuth | Boolean indicating if a login is required. | true |
templateString | The HTML template defining the form fields. | Template |
Sources: public/js/p3/widget/app/Rnaseq.js:24-30, public/js/p3/widget/app/MSA.js:24-30
2. Data Ingestion and Payload Formatting
The getValues() method is the most important override. It collects data from the UI widgets and formats it into the JSON structure expected by the specific Bio App service.
getValues: function () {
var values = this.inherited(arguments); // Standard form values
var json_payload = {};
// Example: Custom logic for Primer Design
if (this.startWithWorkspace.checked) {
json_payload['sequence_input'] = values['sequence_workspace'];
json_payload['input_type'] = 'workspace_fasta';
}
// Standardize output paths
json_payload = this.checkBaseParameters(values, json_payload);
return json_payload;
}
Sources: public/js/p3/widget/app/PrimerDesign.js:100-115, public/js/p3/widget/app/ComprehensiveGenomeAnalysis.js:105-125
3. Validation Logic
While AppBase provides basic validation, apps like MSA and BLAST implement custom logic to ensure FASTA formats are correct or that genome selections meet specific biological criteria (e.g., maximum genome length).
Common Service Patterns
Library and Read Management
Many bio apps (RNA-Seq, Genome Assembly) require handling paired-end or single-end sequencing reads. The platform provides helper methods like addLibraryRow and ingestAttachPoints to manage these complex inputs.
| Feature | Support Method | Purpose |
|---|---|---|
| Read Ingestion | ingestAttachPoints | Maps UI components to data objects. |
| Table Management | increaseRows / decreaseRows | Manages dynamic lists of input files. |
| SRA Integration | onAddSRR | Validates and fetches metadata from NCBI SRA. |
Sources: public/js/p3/widget/app/Rnaseq.js:180-205, public/js/p3/widget/app/AppBase.js:435-450
Rerun Support
Applications should implement intakeRerunForm to allow users to reload parameters from a previous job. This uses window.sessionStorage or localStorage to populate form fields automatically.
Sources: public/js/p3/widget/app/MSA.js:510-530, public/js/p3/widget/app/AppBase.js:555-570
Summary
Adding a new Bio App involves extending the AppBase class to leverage the platform's job submission and workspace infrastructure. By defining specific configuration properties, custom validation (especially for genomic sequences), and a tailored getValues method, developers can create complex analysis interfaces that maintain a unified user experience and seamless integration with DXKB backend services.