# 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/](https://yasgui.matdata.eu/)

[![npm version](https://img.shields.io/npm/v/@matdata/yasgui)](https://www.npmjs.com/package/@matdata/yasgui)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## Quick Links

- 📖 **[User Guide](./docs/user-guide.md)** - Complete guide for end users
- 🛠️ **[Developer Guide](./docs/developer-guide.md)** - API reference and integration guide
- 🚀 **[Production Environment](https://yasgui.matdata.eu/)** - Live instance
- 📦 **[npm Package](https://www.npmjs.com/package/@matdata/yasgui)**
- 🐳 **[Docker Hub](https://hub.docker.com/r/mathiasvda/yasgui)**
- 📝 **[Releases & Changelog](https://github.com/Matdata-eu/Yasgui/releases)**
- 💻 **[GitHub Repository](https://github.com/Matdata-eu/Yasgui)**

---

## Documentation

The **documentation for YASGUI is hosted on GitHub Pages**:

- **📚 Documentation Website**: [https://yasgui-doc.matdata.eu/](https://matdata-eu.github.io/Yasgui/)
  - User Guide, Developer Guide, API Reference
  - Built with Docusaurus
  - Version-tagged with the repository

- **🚀 Development Build**: [https://yasgui-doc.matdata.eu/dev/main/](https://matdata-eu.github.io/Yasgui/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](./docs/user-guide.md#yasqe-query-editor)** - Color-coded SPARQL with error detection
- **[Smart Autocomplete](./docs/user-guide.md#prefix-management)** - Context-aware suggestions for keywords, prefixes, and URIs
- **[Query Formatting](./docs/user-guide.md#query-formatting)** - One-click query beautification with configurable formatters
- **[Prefix Management](./docs/user-guide.md#prefix-management)** - Auto-capture and reuse PREFIX declarations
- **[URI Explorer](./docs/user-guide.md#uri-explorer)** - Ctrl+Click URIs to explore connections
- **[Keyboard Shortcuts](./docs/user-guide.md#keyboard-shortcuts)** - Efficient query development workflow

### 📊 Powerful Visualizations
- **[Table Plugin](./docs/user-guide.md#table-plugin)** - Sortable, filterable, paginated result tables
- **[Graph Plugin](./docs/user-guide.md#graph-plugin)** - Interactive RDF graph visualization
- **[Geo Plugin](./docs/user-guide.md#geo-plugin)** - Geographic data on interactive maps
- **[Response Plugin](./docs/user-guide.md#response-plugin)** - Raw response viewer with syntax highlighting
- **[Boolean Plugin](./docs/user-guide.md#boolean-plugin)** - Visual true/false indicators for ASK queries
- **[Error Plugin](./docs/user-guide.md#error-plugin)** - Detailed error diagnostics

### 🎨 Themes & Layouts
- **[Light & Dark Themes](./docs/user-guide.md#themes)** - Seamless theme switching with persistent preferences
- **[Flexible Layouts](./docs/user-guide.md#layout-orientation)** - Vertical or horizontal editor/results arrangement

### 🔧 Expert Features
- **[Multiple Tabs](./docs/user-guide.md#query-tabs)** - Work on multiple queries simultaneously
- **[Endpoint Management](./docs/user-guide.md#endpoint-quick-switch)** - Quick-switch between SPARQL endpoints
- **[Authentication Support](./docs/developer-guide.md#authentication)** - Basic Auth, Bearer Token, API Key, OAuth2
- **[Persistent Storage](./docs/user-guide.md#query-history-and-persistence)** - Auto-save queries and preferences
- **[URL Sharing](./docs/user-guide.md#share-queries)** - Share queries via URL parameters
- **[Fullscreen Mode](./docs/user-guide.md#fullscreen-mode)** - Maximize editor or results viewer
- **[Export Results](./docs/developer-guide.md#yasr-class)** - Download results in various formats
- **[Configuration Import/Export](./docs/user-guide.md#configuration-importexport)** - Backup and restore settings

For detailed feature documentation, see the **[User Guide](./docs/user-guide.md)**.

---

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

```bash
npm install @matdata/yasgui
```

### Yarn

```bash
yarn add @matdata/yasgui
```

### CDN

```html
<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:**
```bash
docker pull mathiasvda/yasgui:latest
docker run -p 8080:8080 mathiasvda/yasgui:latest
```

Access at: `http://localhost:8080`

**Custom endpoint:**
```bash
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](./docs/developer-guide.md#installation)** and **[User Guide - Docker](./docs/user-guide.md#running-yasgui-with-docker)**.

## Quick Start

### Basic HTML Usage

```html
<!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

```javascript
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:**
```javascript
const yasgui = new Yasgui(document.getElementById('yasgui'), {
  requestConfig: {
    endpoint: 'https://secure-endpoint.com/sparql',
    basicAuth: {
      username: 'myuser',
      password: 'mypassword'
    }
  }
});
```

**Bearer Token (OAuth2/JWT):**
```javascript
const yasgui = new Yasgui(document.getElementById('yasgui'), {
  requestConfig: {
    endpoint: 'https://api.example.com/sparql',
    bearerAuth: {
      token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
    }
  }
});
```

**API Key (Custom Headers):**
```javascript
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](./docs/developer-guide.md#authentication)**.

For framework-specific examples and advanced usage, see the **[Developer Guide](./docs/developer-guide.md#usage-examples)**.

---

## Configuration Options

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

```javascript
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](./docs/developer-guide.md#configuration)**.

---

## Troubleshooting

### CORS Issues

If you encounter CORS errors when querying remote endpoints:

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

See the **[User Guide - CORS Errors](./docs/user-guide.md#cors-errors)** for detailed solutions.

### Local Endpoint Access

To query local SPARQL endpoints from YASGUI:

```bash
# 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](./docs/user-guide.md#querying-local-endpoints)**.

---

## Contributing

We welcome contributions! To get started:

1. Fork the repository
2. Clone and install: `PUPPETEER_SKIP_DOWNLOAD=1 npm ci`
3. Run dev server: `npm run dev`
4. Make your changes
5. Run tests: `npm test`
6. Submit a pull request

**📋 For detailed contribution guidelines, including our plugin development policy, see [CONTRIBUTING.md](./CONTRIBUTING.md).**

Additional resources:
- **[Developer Guide](./docs/developer-guide.md)** - API reference and integration guide
- **[Plugin Development](./docs/developer-guide.md#plugin-development)** - How to create plugins

---

## Support & Community

### Getting Help

- 📖 **[User Guide](./docs/user-guide.md)** - Comprehensive usage documentation
- 🛠️ **[Developer Guide](./docs/developer-guide.md)** - API reference and integration
- 🐛 **[Issue Tracker](https://github.com/Matdata-eu/Yasgui/issues)** - Report bugs or request features
- 💬 **[Discussions](https://github.com/Matdata-eu/Yasgui/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](./LICENSE) file for details.

### Credits

This is a fork from [Zazuko](https://github.com/zazuko/Yasgui) who forked it from [Triply](https://github.com/TriplyDB/Yasgui).

**Maintained by:** [Matdata](https://matdata.eu)

---

## Release Notes & Changelog

Release notes and changelog are available in the [Releases](https://github.com/Matdata-eu/Yasgui/releases) section.

For instructions on writing release notes, see [release-note-instructions.md](./docs/release-note-instructions.md).