@matdata/yasgui-utils 5.0.1 → 5.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +196 -111
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,111 +1,196 @@
|
|
|
1
|
-
# YASGUI
|
|
2
|
-
|
|
3
|
-
YASGUI (Yet Another SPARQL GUI) is an advanced SPARQL client for querying and exploring RDF data. It provides a user-friendly interface for writing SPARQL queries, executing them against SPARQL endpoints, and visualizing the results in various formats.
|
|
4
|
-
|
|
5
|
-
Go to https://yasgui.matdata.eu/ and use it freely in production. Or fork this repo and extend it yourself. Contributions are certainly welcome!
|
|
6
|
-
|
|
7
|
-
## Table of Contents
|
|
8
|
-
|
|
9
|
-
- [Useful Links](#useful-links)
|
|
10
|
-
- [Features](#features)
|
|
11
|
-
- [Keyboard Shortcuts](#keyboard-shortcuts)
|
|
12
|
-
- [Query Editor (Yasqe)](#query-editor-yasqe)
|
|
13
|
-
- [Fullscreen Mode](#fullscreen-mode)
|
|
14
|
-
- [URI Explorer](#uri-explorer)
|
|
15
|
-
- [Prefix Management](#prefix-management)
|
|
16
|
-
- [Result Visualization Plugins (Yasr)](#result-visualization-plugins-yasr)
|
|
17
|
-
- [Installation](#installation)
|
|
18
|
-
- [npm](#npm)
|
|
19
|
-
- [Yarn](#yarn)
|
|
20
|
-
- [Local Development](#local-development)
|
|
21
|
-
- [License](#license)
|
|
22
|
-
|
|
23
|
-
## Useful Links
|
|
24
|
-
|
|
25
|
-
- Production environment: https://yasgui.matdata.eu/
|
|
26
|
-
- Dev environment: https://yasgui-dev.matdata.eu/
|
|
27
|
-
- User documentation: https://docs.triply.cc/yasgui/
|
|
28
|
-
- Developer documentation: https://docs.triply.cc/yasgui-api/
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
- **
|
|
38
|
-
- **
|
|
39
|
-
- **
|
|
40
|
-
- **
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
- **
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
- **
|
|
59
|
-
- **
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
1
|
+
# YASGUI
|
|
2
|
+
|
|
3
|
+
YASGUI (Yet Another SPARQL GUI) is an advanced SPARQL client for querying and exploring RDF data. It provides a user-friendly interface for writing SPARQL queries, executing them against SPARQL endpoints, and visualizing the results in various formats.
|
|
4
|
+
|
|
5
|
+
Go to https://yasgui.matdata.eu/ and use it freely in production. Or fork this repo and extend it yourself. Contributions are certainly welcome!
|
|
6
|
+
|
|
7
|
+
## Table of Contents
|
|
8
|
+
|
|
9
|
+
- [Useful Links](#useful-links)
|
|
10
|
+
- [Features](#features)
|
|
11
|
+
- [Keyboard Shortcuts](#keyboard-shortcuts)
|
|
12
|
+
- [Query Editor (Yasqe)](#query-editor-yasqe)
|
|
13
|
+
- [Fullscreen Mode](#fullscreen-mode)
|
|
14
|
+
- [URI Explorer](#uri-explorer)
|
|
15
|
+
- [Prefix Management](#prefix-management)
|
|
16
|
+
- [Result Visualization Plugins (Yasr)](#result-visualization-plugins-yasr)
|
|
17
|
+
- [Installation](#installation)
|
|
18
|
+
- [npm](#npm)
|
|
19
|
+
- [Yarn](#yarn)
|
|
20
|
+
- [Local Development](#local-development)
|
|
21
|
+
- [License](#license)
|
|
22
|
+
|
|
23
|
+
## Useful Links
|
|
24
|
+
|
|
25
|
+
- Production environment: https://yasgui.matdata.eu/
|
|
26
|
+
- Dev environment: https://yasgui-dev.matdata.eu/ (GitHub Pages - automatically updated with every commit to main branch)
|
|
27
|
+
- User documentation: https://docs.triply.cc/yasgui/
|
|
28
|
+
- Developer documentation: https://docs.triply.cc/yasgui-api/
|
|
29
|
+
- Docker Hub: https://hub.docker.com/r/mathiasvda/yasgui
|
|
30
|
+
|
|
31
|
+
## Features
|
|
32
|
+
|
|
33
|
+
### Themes
|
|
34
|
+
|
|
35
|
+
Yasgui supports both **light** and **dark** themes with instant switching:
|
|
36
|
+
|
|
37
|
+
- **Theme Toggle Button**: Quickly switch between light and dark modes using the button in the tab bar
|
|
38
|
+
- **Persistent Preference**: Your theme choice is automatically saved
|
|
39
|
+
- **System Detection**: Automatically matches your system's dark/light mode preference
|
|
40
|
+
- **Full Coverage**: Consistent theming across all components (editor, results, modals)
|
|
41
|
+
|
|
42
|
+
See the [Theme Guide](./docs/THEME_GUIDE.md) for detailed configuration options and usage examples.
|
|
43
|
+
|
|
44
|
+
See the [Theme Implementation Guide](./docs/THEME_IMPLEMENTATION_GUIDE.md) for detailed instructions on how to implement theme support in your own Yasgui plugins.
|
|
45
|
+
|
|
46
|
+
### Layout Orientation
|
|
47
|
+
|
|
48
|
+
Yasgui supports two layout orientations to optimize screen space usage:
|
|
49
|
+
|
|
50
|
+
- **Vertical Layout (Default)**: YASQE (query editor) positioned above YASR (results viewer)
|
|
51
|
+
- **Horizontal Layout**: YASQE and YASR positioned side-by-side
|
|
52
|
+
|
|
53
|
+
The horizontal layout is particularly useful for wide monitors, allowing you to dedicate the complete height to both the query editor and results viewer.
|
|
54
|
+
|
|
55
|
+
#### Runtime Toggle
|
|
56
|
+
|
|
57
|
+
Users can switch between vertical and horizontal layouts at any time using the **layout toggle button** in the control bar (next to the endpoint selector). This button shows:
|
|
58
|
+
- **Side-by-side rectangles icon** when in vertical mode (click to switch to horizontal)
|
|
59
|
+
- **Stacked rectangles icon** when in horizontal mode (click to switch to vertical)
|
|
60
|
+
|
|
61
|
+
#### Initial Configuration
|
|
62
|
+
|
|
63
|
+
You can also set the initial layout orientation when creating a Yasgui instance:
|
|
64
|
+
|
|
65
|
+
```javascript
|
|
66
|
+
new Yasgui(document.getElementById("yasgui"), {
|
|
67
|
+
orientation: "horizontal" // or "vertical" (default)
|
|
68
|
+
});
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
#### CSS Customization
|
|
72
|
+
|
|
73
|
+
Customize the header height used in the horizontal layout calculation by setting the CSS custom property:
|
|
74
|
+
|
|
75
|
+
```css
|
|
76
|
+
.yasgui {
|
|
77
|
+
--yasgui-header-height: 120px; /* Adjust based on your header height */
|
|
78
|
+
--yasgui-min-height: 500px; /* Minimum height for horizontal layout panels */
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### Keyboard Shortcuts
|
|
83
|
+
|
|
84
|
+
#### Query Editor (Yasqe)
|
|
85
|
+
- **Ctrl+Enter** / **Cmd+Enter**: Execute the current query
|
|
86
|
+
- **Ctrl+Space**: Trigger autocomplete
|
|
87
|
+
- **Ctrl+S**: Save query to local storage
|
|
88
|
+
- **Shift+Ctrl+F**: Auto-format the query
|
|
89
|
+
- **Ctrl+/**: Comment/uncomment selected lines
|
|
90
|
+
- **Shift+Ctrl+D**: Duplicate the current line
|
|
91
|
+
- **Shift+Ctrl+K**: Delete the current line
|
|
92
|
+
- **Esc**: Remove focus from the editor
|
|
93
|
+
|
|
94
|
+
#### Fullscreen Mode
|
|
95
|
+
- **F11**: Toggle fullscreen mode for the query editor (Yasqe)
|
|
96
|
+
- **F10**: Toggle fullscreen mode for the results viewer (Yasr)
|
|
97
|
+
- **Ctrl+Shift+F**: Switch between Yasqe and Yasr fullscreen modes
|
|
98
|
+
|
|
99
|
+
#### URI Explorer
|
|
100
|
+
- **Ctrl+Click** on any URI in the query editor: Automatically executes a CONSTRUCT query to explore the clicked URI's connections (incoming and outgoing triples). The query runs in the background without modifying your current query in the editor.
|
|
101
|
+
|
|
102
|
+
### Prefix Management
|
|
103
|
+
- **PREFIX Button**: Insert saved prefix declarations into your query (replaces existing PREFIX lines at the beginning)
|
|
104
|
+
- **Settings Modal**: Access via the settings button (⚙) to manage:
|
|
105
|
+
- **Saved Prefixes**: Define reusable PREFIX declarations
|
|
106
|
+
- **Auto-capture**: Automatically captures new prefixes from your queries (enabled by default)
|
|
107
|
+
- **Request Configuration**: Configure HTTP request method, accept headers, arguments, headers, and named/default graphs
|
|
108
|
+
- **Default Prefixes**: Automatically includes `rdf:` and `rdfs:` prefixes for new users
|
|
109
|
+
- **Prefix Autocomplete**: When typing a prefix declaration (e.g., `PREFIX foaf:`), the editor automatically queries [prefix.cc](https://prefix.cc) to suggest and auto-complete the full URI commonly associated with that prefix. This helps you quickly add standard prefixes without needing to remember their full URIs.
|
|
110
|
+
|
|
111
|
+
### Endpoint Quick Switch Buttons
|
|
112
|
+
|
|
113
|
+
Configure predefined SPARQL endpoint buttons for quick switching between different endpoints:
|
|
114
|
+
|
|
115
|
+
- **Predefined Buttons**: Configure a list of endpoint buttons during Yasgui initialization
|
|
116
|
+
- **User-Defined Buttons**: Users can add their own custom endpoint buttons through the Settings modal
|
|
117
|
+
- **One-Click Switching**: Instantly switch to a different SPARQL endpoint with a single button click
|
|
118
|
+
- **Persistent Custom Buttons**: User-defined buttons are saved in local storage
|
|
119
|
+
- **Fully Themed**: Buttons automatically adapt to light and dark themes
|
|
120
|
+
|
|
121
|
+
For detailed configuration options and examples, see the [Endpoint Buttons Guide](./docs/ENDPOINT_BUTTONS.md).
|
|
122
|
+
|
|
123
|
+
### Result Visualization Plugins (Yasr)
|
|
124
|
+
|
|
125
|
+
Yasgui includes several built-in plugins to visualize SPARQL query results:
|
|
126
|
+
|
|
127
|
+
- **Table**: Interactive table view with sorting, filtering, pagination, and column resizing. Ideal for SELECT query results.
|
|
128
|
+
- **Boolean**: Displays boolean results (true/false) with visual indicators. Automatically used for ASK queries.
|
|
129
|
+
- **Response**: Raw response viewer with syntax highlighting and code folding. Shows the original response from the endpoint in JSON, XML, Turtle, or other formats.
|
|
130
|
+
- **Geo**: Geographic visualization plugin for displaying spatial data on interactive maps. Visualizes geospatial triples with coordinates. See [Yasgui Geo TG Plugin](https://github.com/Thib-G/yasgui-geo-tg) for more details.
|
|
131
|
+
- **Graph**: Visual graph representation of RDF data using nodes and edges. Ideal for CONSTRUCT/DESCRIBE query results. See [Yasgui Graph Plugin](https://github.com/Matdata-eu/yasgui-graph-plugin) for more details.
|
|
132
|
+
- **Error**: Displays error messages and diagnostics when queries fail, including CORS troubleshooting guidance.
|
|
133
|
+
|
|
134
|
+
Plugins are automatically selected based on the query type and response format. You can manually switch between available plugins using the view selector in the results pane.
|
|
135
|
+
|
|
136
|
+
## Installation
|
|
137
|
+
|
|
138
|
+
Below are instructions on how to include Yasgui in your project.
|
|
139
|
+
If you only want to install Yasr or Yasqe, replace yasgui in the commands below.
|
|
140
|
+
|
|
141
|
+
### npm
|
|
142
|
+
|
|
143
|
+
```sh
|
|
144
|
+
npm i @matdata/yasgui
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### Yarn
|
|
148
|
+
|
|
149
|
+
```sh
|
|
150
|
+
yarn add @matdata/yasgui
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### Docker
|
|
154
|
+
|
|
155
|
+
Yasgui is also available as a Docker image on Docker Hub. Images are built and published automatically when a new release is created.
|
|
156
|
+
|
|
157
|
+
```sh
|
|
158
|
+
docker pull mathiasvda/yasgui:latest
|
|
159
|
+
docker run -p 8080:8080 mathiasvda/yasgui:latest
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
You can customize the default SPARQL endpoint by setting the `YASGUI_DEFAULT_ENDPOINT` environment variable:
|
|
163
|
+
|
|
164
|
+
```sh
|
|
165
|
+
docker run -p 8080:8080 -e YASGUI_DEFAULT_ENDPOINT=https://your-endpoint.com/sparql mathiasvda/yasgui:latest
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
The application will be available at `http://localhost:8080`.
|
|
169
|
+
|
|
170
|
+
## Local Development
|
|
171
|
+
|
|
172
|
+
#### Installing dependencies
|
|
173
|
+
|
|
174
|
+
Run `npm install`.
|
|
175
|
+
|
|
176
|
+
#### Running Yasgui locally
|
|
177
|
+
|
|
178
|
+
To develop locally, run `npm run dev`
|
|
179
|
+
|
|
180
|
+
Go to `http://localhost:5173/demo` in your browser to see Yasgui in action.
|
|
181
|
+
|
|
182
|
+
#### Compiling Yasgui
|
|
183
|
+
|
|
184
|
+
Run `npm run build`. It'll store the transpiled js/css files in the `build` directory.
|
|
185
|
+
|
|
186
|
+
## License
|
|
187
|
+
|
|
188
|
+
This is a fork from [Zazuko](https://github.com/zazuko/Yasgui) who forked it from [Triply](https://github.com/TriplyDB/Yasgui).
|
|
189
|
+
|
|
190
|
+
This code is released under the MIT license.
|
|
191
|
+
|
|
192
|
+
## Release notes
|
|
193
|
+
|
|
194
|
+
Release notes can be found in the release section of the GitHub repository: [Yasgui Releases](https://github.com/Matdata-eu/yasgui/releases)
|
|
195
|
+
|
|
196
|
+
Instructions on how to write release notes are found in
|