This section introduces the Custom and Query API and how to use them.
An API gives Custom View designers access to a series of tools to aid the development of their view. In this case each API has a series of methods and events that enables designers to interact with features in Omniscope Views and query data from Data Manager through the Custom View API and Query API.
Each of the APIs have a series of methods, these invoke the Custom View to perform an action. This includes querying the data source, returning information about the views configuration or updating the view. A full explanation of all of the methods for the Custom View and Query API are available in the References.
Events are used to detect when an aspect of the Custom Views state has changed. For instance this could be when a query has been loaded or a view has been resized. The APIs react in different ways to specific events, these are described in detail in the References section of the documentation.
Loading the Custom View and Query API has to be done in the index.html file. Without this, the view will not be able to access the view API which is necessary for the view to work. Whenever you create a new Custom View you will find this done in the initial template for index.html like so:
<script src="/_global_/customview/v1/omniscope.js"></script><!-- Add the Omniscope custom view API -->
You can load other external API’s such as Highcharts, Google Charts and jQuery. This also needs to be done in the index.html in the standard manner.
The Custom View API gives Custom View designers tools to allow their View to interact with other components within Omniscope Views. This is required communication between the View and Omniscope, enabling features such as brushing and selection. The View will display without it, however it will be static and cannot interact with the rest of the application.
When the Custom View API is loaded, communication with the rest of Omniscope is done through the context, where information about the Views options are passed between the View and Omniscope Views. There are also a series of methods such as endpoint(), busy() and updated().
Each of the Custom View API methods are explained in detail in the reference section of the documentation. The context object is a JSON object which describes configuration and other application states which you can use to render your view, for more information see here.
The Custom View API can be accessed within a <script> tag once the Omniscope APIs have been loaded in the index.html. Each of the methods can be called from the object omniscope.view. For example, to get the View context call omniscope.view.context() inside a <script> tag. To access other methods such as busy add omniscope.view.busy(true); inside the <script> tag (example below).
...
// Importing the APIs
<script src="/_global_/customview/v1/omniscope.js"></script><!-- Add the Omniscope custom view API -->
...
<script>
...
// Call the function 'busy()'
omniscope.view.busy(true);
...
</script>
The Query API gives Custom View designers the ability to make queries on their data before handing it over to the Custom View. Queries enable designers to avoid overloading their View with too much data through various aggregation and filtering techniques. This is important, as drawing too many points/bars can lead to difficulty loading the view.
There are a series of methods that allow the designer to query data, most commonly used is table() which returns a single
query result. A detailed description of each of these methods is given in References.
Making a query is slightly more complex than using the Custom View API, many of the methods return a request that itself needs to be handled when certain events have elapsed. Consider this example:
...
// Importing the APIs
<script src="/_global_/customview/v1/omniscope.js"></script><!-- Add the Omniscope custom view API -->
...
<script>
...
// Get the view endpoint using the Custom View API, this is needed to create the query builder.
var endpoint = omniscope.view.endpoint();
// Create a function that states what needs to be done when the data is loaded
var printQuery = function(event) {
document.getElementById("main").textContent = JSON.stringify(event, null,2);
}
// Create method to handle error
var printError = function(error) {
console.log(error);
}
// It is good practice to ensure you handle errors appropriately
try {
// Call the query builder
omniscope.query.builder(endpoint).
// Call the schema function
schema().
// Print the query on load, and execute this process.
on("load", printQuery).
on("error", printError).execute();
// If there is an error, catch it and in this case throw it with the message
} catch (error) {
throw new Error(error.message);
}
...
</script>
The above example will print the data’s schematics such as the Field titles and types as a JSON object in the custom view. This was achieved in the following steps:
omniscope.view.endpoint()printQuery stating what to do upon the event loadomniscope.query.builder(endpoint).schema().on("load", printQuery).execute();". Do so in a try catch in case of error.