YASGUI works on any SPARQL endpoint, even endpoints installed on the computer you are using (i.e. using localhost). This means regular users won't need to follow this guide. This guide is meant for people who would like to deploy YASGUI as GUI interface for their dataset/endpoint.

There are two ways of deploying YASGUI on your server. Via an iframe, or by installing it on your server. Choose a method depending on your use-case. An overview of advantages and disadvantages:

html page with iframeinstallation on server
 Less configuration options  Greater configuration
 Requires just an html page, no web server  Requires a web server (with optionally a DB as well)
 No version management. YASGUI automatically gets updated whenever the main branch changes. Requires no effort, but you won't receive notifications before YASGUI is updated (i.e. you won't have the chance to test the new version)  You are in control of managing the YASGUI version. Takes more effort, but allows you to test new versions before updating.
 Dependent on other server (including possible downtimes)  You control the YASGUI server

The code below show how to use YASGUI via an iframe. (view a running example here)

<iframe src="http://yasgui.laurensrietveld.nl" style="border:0" width="100%" height="100%"></iframe>

Including YASGUI on your website via an iframe still offers you a certain amount of configurability. To configure YASGUI, you need to change the src attribute of the iframe. Add a jsonSettings argument to the url, with as value the url encoded json configuration. (use this online URL encoder). E.g. src="http://yasgui.laurensrietveld.nl?jsonSettings=%7B%0A%22singleEndpointMode%22%3A%20true%0A%7D.

Important things to consider

  • Only pass the settings via the URL which you would like to change. I.e., you probably won't need to change the default tab title, or the default content type for construct queries. Most probably, you are only interested in changing the default query, default endpoint, and the 'single endpoint mode' setting. Therefore, only pass those.
  • Internet Explorer has a maximum URL length of 2083 characters. Make sure the URL does not exceed this.
  • Not all configuration settings are supported when using the iframe method. Only settings solely used on the client-side are allowed. In other words, the following options won't work:
    • All bitly settings
    • All MySQL settings
    • The default bookmarks settings

Prerequisites

  • Prerequisites: A java webserver, e.g. tomcat
  • MySQL Database (optional, required for query bookmarking functionality)

Installation

  • Download the zip file here, or clone the github repository
  • Package the .war file
    mvn package
  • Deploy the war file to your java webserver. For tomcat, you would issue this command
    sudo cp target/yasgui-*.war /var/lib/tomcat7/webapps/yasgui.war; 
  • After deployment to the web server, go to the root of the YASGUI directory (for tomcat, this would be /var/lib/tomcat7/webapps/yasgui/)
  • If needed, edit the configuration file located in config/config.json (check this page for configuration settings)
After making your changes, make sure the json configuration is valid, by validating it using JSON Lint

Example configuration file

{
    "defaults": {
        "endpoint": "http://dbpedia.org/sparql",
        "query": "PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>\nPREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>\nSELECT * {\n\t?sub ?pred ?obj\n} LIMIT 10\n",
        "tabTitle": "Query",
        "contentTypeSelect": "application/sparql-results+xml",
        "contentTypeConstruct": "text/turtle",
        "outputFormat": "table",
        "requestMethod": "POST",
        "extraArgs": []
    },
    "enabledFeatures": {
        "endpointSelection": true,
        "queryParameters": true,
        "namedGraphs": true,
        "defaultGraphs": true,
        "acceptHeaders": true,
        "requestMethod": true,
        "propertyCompletionMethods": {
            "lov": true,
            "query": true,
            "queryResults": true
        },
        "classCompletionMethods": {
            "lov": true,
            "query": true,
            "queryResults": true
        }
    },
    "downloadOfflineCache": true,
    "showDownloadProgressBar": true,
    "googleAnalyticsId": "UA-11111111-1",
    "bitlyApiKey": "R_xxxxxxxxxxxxxxxxxxxxxxxxx",
    "bitlyUsername": "SomeUserName",
    "mysqlDb": "YASGUI",
    "mysqlUsername": "YASGUI",
    "mysqlPassword": "S0M3P4ssW0rd",
    "mysqlHost": "localhost",
    "githubUsername": "githubUserName",
    "githubOathToken": "oathToken",
    "githubRepo": "repository",
    "defaultBookmarks": [
        {
            "title": "Get 10 triples",
            "endpoint": "",
            "query": "SELECT * WHERE {\n    ?s ?p ?o.\n}\nLIMIT 10"
        }
    ]
}

Fields in config file

Defaults

The main part of the config file contains all the possible default values. When opening YASGUI for the first time, or when opening a new tab, these values are used as defaults. Most are self explanatory.

endpoint
query
tabTitle
Default name of a yasgui query tab
contentTypeSelect
Default content type to use for SPARQL SELECT queries
contentTypeConstruct
Default content type to use for SPARQL CONSTRUCT queries
outputFormat
Default output to visualize query results in. Possible values are:
rawResponse
The result as we received it from the endpoint (i.e. something like json or xml)
table
Sortable table (not suitable for large resultsets)
simpleTable
Simple table (suitable for larger resultsets)
requestMethod
Either POST or GET
extraArgs
Any extra url arguments you'd like to pass on to the endpoint. The following example will at &bla=bla2&bl3=bla4 to the request send to the endpoint: "extraArgs": [{"bla":"bla2"}, {"bla3":"bla4"}]

Enabled Features

This part of the settings allow you to disable YASGUI functionality: Not including these in your json file will enable this features by default. All items take as input a boolean value. Setting a value to false,
endpointSelection
Set fo false to only use the specified default endpoint. The user won't see the endpoint text input form, and won't be able to search for endpoints. An example of YASGUI working in single endpoint mode is available here
queryParameters
Set to false to hide the option to add query parameters
namedGraphs
Set to false to hide option to specify named graphs for a given query
defaultGraphs
Set to false to hide option to specify default graphs for a given query
acceptHeaders
Set to false to hide option to specify the accept headers for a given query
requestMethod
Set to false to hide option to specify the request method (e.g. GET or POST) for a given query
offlineCaching
Set to false to disable offline caching (this feature is disabled anyway for browsers not supporting it). Disabling this also hides the 'Offline Availability' item in the 'Configure YASGUI' menu
propertyCompletionMethods
To disable property autocompletion, remove this option from the json file, or set to null. For more info about the three completion methods, see the help page. Setting a method to true or false will enable/disable that method. However, a user is still allowed to turn this method on or off. To completely disable a method, without the option for a user to change it, remove the method from this json object.
classCompletionMethods
idem, but for class autocompletion

Other options

downloadOfflineCache
Automatically download YASGUI to the offline cache, so clients will be able to use YASGUI offline as well
showDownloadProgressBar
Show the download progressbar each time the offline cache needs to be updated (i.e. on first view, or whenever YASGUI receives an update)
googleAnalyticsId*
Google analytics ID
bitlyUsername*
Username for bitly url shortener service. Used for the query permalink feature.
bitlyApiKey*
API key for the bitly shortener service. Request one at bitly.com
mysqlDb*
Name of database to store YASGUI data in. Using 'YASGUI' will often suffice. This setting is useful when multiple instances of YASGUI are installed on the same server
mysqlUsername*
Username for SQL backend. Used for user management and query bookmark functionality. Required permissions for user:
  • all data access permissions
  • YASGUI automatically creates the DB table structure (and may modify it when needed in future YASGUI updates). Therefore we need these permissions as well: CREATE / ALTER / INDEX
mysqlPassword*
Password of SQL user
mysqlHost*
Host where SQL backend is running
githubUsername*
Username of your github account. Used for creating github issues from within the YASGUI interface
githubRepo*
Github repository where you'd like to create the issues (e.g. a fork of YASGUI). The github user specified above should have push rights to this repository
githubOathToken*
Github oath token (click on 'create new token' here here
defaultBookmarks*
When bookmark functionality is supported (i.e. sql settings are valid), these bookmarks are added as example queries.
* removing this setting or using an empty value will disable this functionality