@matdata/yasgui

v5.14.0

Published

18 days ago

Yet Another SPARQL GUI

Downloads

865

0High
0Medium
0Low

mathiasvda

JavaScript SPARQL Editor Semantic Web Linked Data

YASGUI

Yet Another SPARQL GUI (YASGUI) is a powerful, user-friendly web-based interface for querying and exploring RDF data using SPARQL. It combines a feature-rich query editor (YASQE) with a versatile results viewer (YASR) to provide a comprehensive SPARQL IDE.

🌐 Try it now: https://yasgui.matdata.eu/

Quick Links

📖 User Guide - Complete guide for end users
🛠️ Developer Guide - API reference and integration guide
🚀 Production Environment - Live instance
📦 npm Package
🐳 Docker Hub
📝 Releases & Changelog
💻 GitHub Repository

Documentation

The documentation for YASGUI is hosted on GitHub Pages:

📚 Documentation Website: https://yasgui-doc.matdata.eu/
- User Guide, Developer Guide, API Reference
- Built with Docusaurus
- Version-tagged with the repository
🚀 Development Build: https://yasgui-doc.matdata.eu/dev/main/
- Live build from the main branch
- Updated automatically with every commit
- Test latest features before release

The documentation is version-tagged with the repository, ensuring consistency between code and documentation across releases.

Features

YASGUI provides a complete SPARQL development environment with powerful features:

✏️ Advanced Query Editor

SPARQL Syntax Highlighting - Color-coded SPARQL with error detection
Smart Autocomplete - Context-aware suggestions for keywords, prefixes, and URIs
Query Formatting - One-click query beautification with configurable formatters
Prefix Management - Auto-capture and reuse PREFIX declarations
URI Explorer - Ctrl+Click URIs to explore connections
Keyboard Shortcuts - Efficient query development workflow

📊 Powerful Visualizations

Table Plugin - Sortable, filterable, paginated result tables
Graph Plugin - Interactive RDF graph visualization
Geo Plugin - Geographic data on interactive maps
Response Plugin - Raw response viewer with syntax highlighting
Boolean Plugin - Visual true/false indicators for ASK queries
Error Plugin - Detailed error diagnostics

🎨 Themes & Layouts

Light & Dark Themes - Seamless theme switching with persistent preferences
Flexible Layouts - Vertical or horizontal editor/results arrangement

🔧 Expert Features

Multiple Tabs - Work on multiple queries simultaneously
Endpoint Management - Quick-switch between SPARQL endpoints
Authentication Support - Basic Auth, Bearer Token, API Key, OAuth2
Persistent Storage - Auto-save queries and preferences
URL Sharing - Share queries via URL parameters
Fullscreen Mode - Maximize editor or results viewer
Export Results - Download results in various formats
Configuration Import/Export - Backup and restore settings

For detailed feature documentation, see the User Guide.

Browser Support

YASGUI works on all modern browsers:

✅ Chrome / Edge (latest)
✅ Firefox (latest)
✅ Safari (latest)
✅ Opera (latest)

Requirements:

JavaScript enabled
Cookies/LocalStorage enabled (for query persistence)
Modern ES6+ support

Installation

npm

npm install @matdata/yasgui

Yarn

yarn add @matdata/yasgui

CDN

<link rel="stylesheet" href="https://unpkg.com/@matdata/yasgui/build/yasgui.min.css" />
<script src="https://unpkg.com/@matdata/yasgui/build/yasgui.min.js"></script>

Docker

Run with default endpoint:

docker pull mathiasvda/yasgui:latest
docker run -p 8080:8080 mathiasvda/yasgui:latest

Access at: http://localhost:8080

Custom endpoint:

docker run -p 8080:8080 \
  -e YASGUI_DEFAULT_ENDPOINT=https://your-endpoint.com/sparql \
  mathiasvda/yasgui:latest

For detailed installation instructions and usage examples, see the Developer Guide and User Guide - Docker.

Quick Start

Basic HTML Usage

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/@matdata/yasgui/build/yasgui.min.css" />
</head>
<body>
  <div id="yasgui"></div>
  
  <script src="https://unpkg.com/@matdata/yasgui/build/yasgui.min.js"></script>
  <script>
    const yasgui = new Yasgui(document.getElementById("yasgui"), {
      requestConfig: {
        endpoint: "https://dbpedia.org/sparql"
      }
    });
  </script>
</body>
</html>

ES Modules / React / Vue / Angular

import Yasgui from '@matdata/yasgui';
import '@matdata/yasgui/build/yasgui.min.css';

const yasgui = new Yasgui(document.getElementById('yasgui'), {
  requestConfig: {
    endpoint: 'https://query.wikidata.org/sparql'
  },
  theme: 'dark',
  orientation: 'horizontal'
});

Authentication

YASGUI supports multiple authentication methods for secure SPARQL endpoints:

Basic Authentication:

const yasgui = new Yasgui(document.getElementById('yasgui'), {
  requestConfig: {
    endpoint: 'https://secure-endpoint.com/sparql',
    basicAuth: {
      username: 'myuser',
      password: 'mypassword'
    }
  }
});

Bearer Token (OAuth2/JWT):

const yasgui = new Yasgui(document.getElementById('yasgui'), {
  requestConfig: {
    endpoint: 'https://api.example.com/sparql',
    bearerAuth: {
      token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
    }
  }
});

API Key (Custom Headers):

const yasgui = new Yasgui(document.getElementById('yasgui'), {
  requestConfig: {
    endpoint: 'https://api.example.com/sparql',
    apiKeyAuth: {
      headerName: 'X-API-Key',
      apiKey: 'your-api-key-here'
    }
  }
});

Authentication can also be configured through the UI via the Settings modal (gear icon). For detailed authentication documentation including dynamic auth and OAuth2, see the Developer Guide - Authentication.

For framework-specific examples and advanced usage, see the Developer Guide.

Configuration Options

YASGUI is highly configurable. Here are some common configuration options:

const yasgui = new Yasgui(document.getElementById('yasgui'), {
  // Request configuration
  requestConfig: {
    endpoint: 'https://dbpedia.org/sparql',
    method: 'POST',                        // GET or POST
    headers: { 'Custom-Header': 'value' }, // Custom HTTP headers
    args: [{ name: 'param', value: 'val' }] // URL parameters
  },
  
  // UI configuration
  theme: 'dark',                           // 'light' or 'dark'
  orientation: 'horizontal',               // 'horizontal' or 'vertical'
  showSnippetsBar: true,                   // Show code snippets
  
  // Persistence
  persistenceId: 'my-yasgui-instance',     // Custom storage ID
  persistencyExpire: 7 * 24 * 60 * 60,     // Storage expiration (7 days)
  
  // Default query
  yasqe: {
    value: 'SELECT * WHERE { ?s ?p ?o } LIMIT 10'
  }
});

For complete configuration options, see the Developer Guide - Configuration.

Troubleshooting

CORS Issues

If you encounter CORS errors when querying remote endpoints:

Use a CORS proxy - Set up a proxy server that adds CORS headers
Configure the endpoint - Some endpoints support CORS with proper configuration
Server-side queries - Execute queries server-side and display results client-side

See the User Guide - CORS Errors for detailed solutions.

Local Endpoint Access

To query local SPARQL endpoints from YASGUI:

# Example: Running a local endpoint accessible to YASGUI
docker run -p 3030:3030 stain/jena-fuseki

Access at: http://localhost:3030/dataset/sparql

For more details, see User Guide - Querying Local Endpoints.

Contributing

We welcome contributions! To get started:

Fork the repository
Clone and install: PUPPETEER_SKIP_DOWNLOAD=1 npm ci
Run dev server: npm run dev
Make your changes
Run tests: npm test
Submit a pull request

📋 For detailed contribution guidelines, including our plugin development policy, see CONTRIBUTING.md.

Additional resources:

Developer Guide - API reference and integration guide
Plugin Development - How to create plugins

Support & Community

Getting Help

📖 User Guide - Comprehensive usage documentation
🛠️ Developer Guide - API reference and integration
🐛 Issue Tracker - Report bugs or request features
💬 Discussions - Ask questions and share ideas

Reporting Issues

When reporting issues, please include:

Browser version and operating system
Steps to reproduce the problem
Expected vs. actual behavior
Console errors (if any)
Minimal example query demonstrating the issue

License

MIT License - see LICENSE file for details.

Credits

This is a fork from Zazuko who forked it from Triply.

Maintained by: Matdata

Release Notes & Changelog

Release notes and changelog are available in the Releases section.

For instructions on writing release notes, see release-note-instructions.md.