Sgvizler has moved to github. This site and its repository will no longer be maintained.
wiki:Sgvizler/0.6/Using

This page conserns Sgvizler/0.6.
Other available versions:

Using Sgvizler 0.6

There are three intended ways to use Sgvizler:

  1. Query stored in HTML container
  2. Query Form
  3. Using Sgvizler's API

(In any case you will need to setup Sgvizler by including required javascripts.)

Query stored in HTML container

Add <div> elements, or other suitable HTML containers, including special (HTML5 compatible) "sgvizler attributes", e.g., containers of the following format:

<div id="myExample"
     data-sgvizler-endpoint="http://sws.ifi.uio.no/sparql/npd"
     data-sgvizler-query="SELECT ?class (count(?instance) AS ?noOfInstances)
                          WHERE{ ?instance a ?class }
                          GROUP BY ?class
                          ORDER BY ?class"
     data-sgvizler-chart="google.visualization.PieChart"
     data-sgvizler-chart-options="is3D=true|title=Number of instances"
     style="width:800px; height:400px;"></div>

... and call Sgvizler to draw the chart. This is normally best done by loading all such HTML containers on page load with:

$(document).ready(
    function (){ sgvizler.containerDrawAll(); }
);

... or individual containers can be drawn with the call

sgvizler.containerDrawAll(containerID);

... where containerID is the id attribute value of the container to be drawn, e.g., "myExample".

See the  documentation for available functions.

Explanation of HTML element attributes that Sgvizler require and recognize (Required attributes are marked by *):

id*
Value: some string, e.g., "myExample"
Description: The identifier for the <div> element. Necessary for Sgvizler to locate where to put the chart. The value must be unique to all elements on the same page.
data-sgvizler-query*
Value: SRARQL query string
Description: The SPARQL SELECT query specifying a query result to fit the chosen diagram. The query result set must fit the format required by the chosen chart to draw; find the chart and description here Sgvizler/Chart.
data-sgvizler-endpoint
Value: a URL string, e.g., "http://dbpedia.org/sparql"
Description: URL to SPARQL endpoint.
Note: There must of course exist a designated SPARQL endpoint, but this might be better set in the initialization of Sgvizler; see Setup.
data-sgvizler-endpoint_output
Value: json, jsonp or xml
Description: The format Sgvizler shall ask the endpoint to return query results as. Default is json.
data-sgvizler-rdf
Value: a string of URLs to RDF files
Description: List of URLs to RDF files. The list must be separated by |-characters, and the configured SPARQL endpoint must allow FROMs in the query.
Note that data-sgvizler-rdf is just a shorthand way of telling Sgvizler to include a list of FROMs in the query. The configured endpoint reads the listed RDF files and executes the query on them; this means that the files must be accessible to the endpoint and the endpoint must be setup to allow FROM in queries.
data-sgvizler-chart
Value: chart id
Description: The chart type to draw. The value is the name of the chart object, e.g., google.visualization.LineChart or sgvizler.visualization.Table. Find the value for the chart you want on its Sgvizler/Chart page.
data-sgvizler-chart-options
Value: string
Description: List of options which are sent to the chart function. Each option is given as option=value and each option-value-pair is separated with a vertical bar, e.g. option1=value1|option2=value2. See the relevant Sgvizler/Chart page for available options.
data-sgvizler-loglevel
Note: This is not yet fully implemented.
Description: To what extent Sgvizler shall give feedback to the user.
style
Value: a string of css
Description: This is just the normal way of adding css style to your elements, but width and height will also be picked up by Sgvizler to determine the size of the chart. The default values are respectively 800px and 400px.
data-sgvizler-endpoint_query_url
Value: part of URL
Description: Part of URL to append to SPARQL endpoint URL such that (URL to SPARQL endpoint) + (this variable) + (query) = (query results (in a web browser)). Default is ?output=text&amp;query=.
data-sgvizler-validator_query_url
Value: URL
Description: URL to some SPARQL validator such that (the value of this attribute) + (query) = (a url to the validation results for query). Default value is http://www.sparql.org/query-validator?languageSyntax=SPARQL&amp;outputFormat=sparql&amp;linenumbers=true&amp;query=.

Query Form

This form closely resembles the query forms of  SPARQLer and  Snorql.

A live example of the form is found here Sgvizler/QueryForm.

Add the form to your site by using the function sgvizler.drawForm(elementID), where elementID is the HTML element ID of where to put the form---if no argument is provided, then the body element is used, e.g.,

<div id="myForm"></div>
<script type="text/javascript">
  $(document).ready(function() { sgvizler.formDraw("myForm"); });
</script>

Using Sgvizler's API

Use the available public functions for the sgvizler and Query object when you need a different configuration than the two above. See the  documentation and give attention to  Query object. Here is an example of how to use the API to draw charts:

var sparqlQueryString = "SELECT * {?s ?p ?o} LIMIT 10",
    Q = new sgvizler.Query();                           // Create a Query instance

// Note that default values may be set in the sgvizler object.
Q.query(sparqlQueryString)
    .endpointURL("http://dbpedia.org/sparql")
    .endpointOutputFormat("json")                      // Possible values 'xml', 'json', 'jsonp'.
    .chartFunction("google.visualization.BarChart")    // The name of the function to draw the chart.
    .draw("myElementID");                              // Draw the chart in the designated HTML element.

If you want to directy access and manipulate the query results, use the function Query.getDataTable(success, fail) and register functions that are applied to the resulting query results  datatable on success and on failure:

var sparqlQueryString = "SELECT * {?s ?p ?o} LIMIT 10",
    Q = new sgvizler.Query(),
    mySuccessFunc = function (datatable) {
      /* Do what you want with the datatable */
    },
    myFailFunc = function (datatable) {
      /* Handle the failue */
    };

Q.query(sparqlQueryString)
    .endpointURL("http://dbpedia.org/sparql")
    .getDataTable(mySuccessFunc, myFailFunc);

(The function getDataTable does not return a datatable (but instead registers functions, as shown above) since retrieving the query results from the SPARQL endpoint is done asynchronously.)