You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+83-48Lines changed: 83 additions & 48 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,6 +3,21 @@
3
3
This Web app allows users to easily execute queries over multiple data sources (including Solid pods) and
4
4
inspect the corresponding results.
5
5
6
+
Table of contents:
7
+
<!-- TOC -->
8
+
*[Getting Started](#getting-started)
9
+
*[Static build](#static-build)
10
+
*[Logging in](#logging-in)
11
+
*[Configuration file](#configuration-file)
12
+
*[Adding variable type](#adding-variable-type)
13
+
*[Templated queries](#templated-queries)
14
+
*[Query icons](#query-icons)
15
+
*[Representation Mapper](#representation-mapper)
16
+
*[Testing with local pods](#testing-with-local-pods)
17
+
*[Using a local http proxy](#using-a-local-http-proxy)
18
+
*[Testing](#testing)
19
+
<!-- TOC -->
20
+
6
21
## Getting Started
7
22
8
23
After installing, the following steps suffice to install the application:
@@ -17,63 +32,70 @@ after this you can execute
17
32
npm run dev
18
33
```
19
34
20
-
Which will start the web application
35
+
which will start the web application. Now you can browse the displayed URL.
36
+
37
+
If you want to test the default configuration however, you first need to complete the steps
38
+
described in [testing with local pods](#testing-with-local-pods) and [using a local http proxy](#using-a-local-http-proxy).
39
+
Do each of these in their own separate terminal window.
21
40
22
41
## Static build
23
42
24
-
If you want a static build of the application execute
43
+
If you want a static build of the application, execute:
25
44
26
45
```bash
27
46
npm run build
28
47
```
29
48
30
49
This will create a static build in the `dist` folder.
31
50
32
-
###Logging in
51
+
## Logging in
33
52
34
-
To log in you need to provide an Identity Provider or a WebID.
53
+
Some queries access data sources that are only readable by authenticated users. This requires you to log in.
54
+
To log in, you need to provide an Identity Provider or a WebID.
35
55
The application will detect which one you use and redirect you to the login page of your Identity Provider.
36
56
If you use your WebID, the first OIDC issuer on your WebID is used when there are multiple.
37
57
38
-
###Configuration file
58
+
## Configuration file
39
59
40
60
The configuration file follows a simple structure.
41
61
42
-
```js
62
+
```json
43
63
{
44
-
"title":"Title shown at the top of the app.",
45
-
"logoLocation":"Image location of the logo shown at the top of the app (relative to public folder.).",
46
-
"logoRedirectURL":"The URL the Web application redirects to when a user clicks on the logo.",
47
-
"mainAppColor":"The main colors used in the app, can be any CSS color.",
48
-
"backgroundColor":"Background color of the app, can be any CSS color.",
49
-
"titleColor":"The color of the title, can be any CSS color",
50
-
"textColor":"The color of all the text in teh app body, this means all text except header and footer.",
51
-
"footer":"HTML components or text that will function as the footer (will be placed in the footer div.)",
52
-
"defaultIDP":"The default value used for IDP when logging in, this IDP can be manually changed in the Web app as well. ",
53
-
"queryFolder":"The base location of the queries, all query locations will start from this folder (relative to public folder.)",
54
-
"httpProxy":"The http proxy through which the requests will be rerouted. When left empty, the Comunica query engine will handle it. This is useful when CORS headers are not set (correctly) on the queried source.",
55
-
"introductionText":"The text that the app shows on the dashboard, which the app also shows when you first open it.",
56
-
"queries": [
57
-
{
58
-
"queryLocation":"path to the query location, relative to "queryFolder"",
59
-
"name":"A name for the query",
60
-
"description":"Description of the query",
61
-
"id":"A unique ID for the query",
62
-
"icon":"The key to the icon for to represent the query (see Icon Provider below). This is optional and a default menu icon will be used when left empty.",
63
-
"comunicaContext": {
64
-
"sources":"Sources over which the query should be executed",
65
-
"useProxy":"True or false, whether the query should be executed through the proxy or not. This field is optional and defaults to false.",
66
-
...{"any other field that can be used in the Comunica query engine https://comunica.dev/docs/query/advanced/context/"}
67
-
},
68
-
},
69
-
"askQuery": {
70
-
"trueText":"The text that is to be shown when the query result is true, only useful for ASK queries.",
71
-
"falseText":"The text that is to be shown when the query result is true, only useful for ASK queries."
72
-
}
73
-
74
-
}
75
-
...
76
-
]
64
+
"title": "Title shown at the top of the app.",
65
+
"logoLocation": "Image location of the logo shown at the top of the app (relative to public folder.).",
66
+
"logoRedirectURL": "The URL the Web application redirects to when a user clicks on the logo.",
67
+
"mainAppColor": "The main colors used in the app, can be any CSS color.",
68
+
"backgroundColor": "Background color of the app, can be any CSS color.",
69
+
"titleColor": "The color of the title, can be any CSS color",
70
+
"textColor": "The color of all the text in teh app body, this means all text except header and footer.",
71
+
"footer": "HTML components or text that will function as the footer (will be placed in the footer div.)",
72
+
"defaultIDP": "The default value used for IDP when logging in, this IDP can be manually changed in the Web app as well. ",
73
+
"queryFolder": "The base location of the queries, all query locations will start from this folder (relative to public folder.)",
74
+
"httpProxy": "The http proxy through which the requests will be rerouted. When left empty, the Comunica query engine will handle it. This is useful when CORS headers are not set (correctly) on the queried source.",
75
+
"introductionText": "The text that the app shows on the dashboard, which the app also shows when you first open it.",
76
+
"queries": [
77
+
{
78
+
"queryLocation": "path to the query location, relative to "queryFolder"",
79
+
"name": "A name for the query",
80
+
"description": "Description of the query",
81
+
"id": "A unique ID for the query",
82
+
"icon": "The key to the icon for the query . This is optional and a default menu icon will be used when left empty.",
83
+
"comunicaContext": {
84
+
"sources": "Sources over which the query should be executed",
85
+
"useProxy": "True or false, whether the query should be executed through the proxy or not. This field is optional and defaults to false.",
86
+
...{"any other field that can be used in the Comunica query engine https://comunica.dev/docs/query/advanced/context/"}
"trueText": "The text that is to be shown when the query result is true, only useful for ASK queries.",
94
+
"falseText": "The text that is to be shown when the query result is true, only useful for ASK queries."
95
+
}
96
+
}
97
+
...
98
+
]
77
99
}
78
100
```
79
101
@@ -88,25 +110,39 @@ we can fully interpret how we can display and represent the result.
88
110
You can specify the type of a variable by extending its name with the type in the query as such: `variableName_variableType`.
89
111
The underscore `_` here is crucial to make a clear distinction between name and type.
90
112
91
-
### Query Icons
113
+
### Templated queries
114
+
115
+
This application supports queries whose contents are not completely fixed upfront: they contain variables whose value can be set interactively.
116
+
117
+
To change a query into a templated query:
118
+
- replace the fixed portion(s) of the query with (a) variable(s); a variable is an identifier preceded by a `$` sign, e.g. `$genre`
119
+
- add a `variables` object in the query's entry in the configuration file
120
+
- in the `variables` object, for each variable, add a property with name equal to the variable's identifier
121
+
- set each such property's value to an array of possible values for the corresponding variable
122
+
123
+
Note that variables' values are not restricted to strings: URIs for example are alo possible.
124
+
As a consequence, for strings the surround double quotes `"` must be added to the values in the list.
125
+
This is shown in the configuration structure above.
126
+
127
+
### Query icons
92
128
93
129
In the selection menu the name of the query is proceeded by an icon.
94
130
You configure this icon per query in the configuration file.
95
131
For this to work you need to add the icon to the exports in [IconProvider.js](./src/IconProvider/IconProvider.js).
96
132
We advise to use the [Material UI icons](https://material-ui.com/components/material-icons/) as this is what's used internally in `react-admin` and it is also included in the dependencies.
97
133
Nevertheless, you can use any React component you want, just make sure it's a functional component.
98
134
99
-
###Representation Mapper
135
+
## Representation Mapper
100
136
101
137
If you want to add your own type representations
102
-
you can do this by adding your representation to the [representationProvider.jsx](./src/representationProvider/representationProvider.jsx) file.
138
+
you can do this by adding your representation to the [representationProvider.js](./src/representationProvider/representationProvider.js) file.
103
139
This can be useful for example when querying images.
104
140
The result of the query is a reference to the image.
105
141
By mapping a representation we can show the actual image instead of the reference.
106
142
107
143
The mapper follows a structure:
108
144
109
-
```js
145
+
```json
110
146
{
111
147
"typeName": mapperComponent,
112
148
...
@@ -117,7 +153,7 @@ With `typeName` being the name of the variable as defined in the `query`
117
153
which is defined in [the configuration file](#configuration-file).
118
154
The function `mapperComponent` takes the query result for the corresponding variable and
119
155
returns either a [React](https://react.dev/) component (see below).
120
-
Examples of how you can do this can already be found in the [representationProvider/components folder](./src/representationProvider/components/).
156
+
Examples of how you can do this can already be found in the [representationProvidercomponents folder](./src/representationProvider/components/).
121
157
122
158
The components get the following props:
123
159
@@ -136,13 +172,12 @@ To create a local pod with which you can test for example authentication you can
136
172
137
173
- Add your data and `.acl` files in the `initial-pod-data` folder.
138
174
These files will be available in the pod relative to `http://localhost:8080/example/`.
139
-
We already added files for the resource `favourite-books`.
175
+
We already added files to support the example queries in the configuration file.
140
176
- Prepare the pods by executing `npm run prepare:pods`.
141
177
- Start the pods by executing `npm run start:pods`.
142
178
- Add your query as described in [the configuration file section](#configuration-file).
143
-
We already added a query to list books based on the resource `favourite-books` to `src/config.json`.
144
-
- Log in with the IDP `http://localhost:8080` and
145
-
the credentials in the file `seeded-pod-config.json`.
179
+
We already added some example queries in the default configuration file `src/config.json`.
180
+
- Log in with the IDP `http://localhost:8080` and the credentials for the user owning the pod named `example` in the file `seeded-pod-config.json`.
0 commit comments