Website integration is simple and relies on including a single JS file within your webpage and instructing Joola how it should compose the visualizations on page.

Include the SDK

Joola's SDK helps you query, visualize and manage your data stored within your Joola application. In order to get started, you will need to include the SDK within your webpage/project, like this:

<script src="<APPLICATION_URL>/joola.min.js?APIToken=<READER_API_TOKEN>" />

Copy, modify and paste the statement above within your webpage. Replace and with values specific to your application. When the script runs, it: - Connects to the application. - Ensures valid credentials were used. - Makes the SDK ready for your use.

Initialization can also be done manually by calling joola.init(options, callback):

<html>
  <head>
    <script src="<APPLICATION_URL>/joola.min.js"></script>
    <script type="text/javascript">
      joola.init({"APIToken": "<READER_API_TOKEN>"}, function(err) {
        if (err) 
          throw err;
        console.log('Joola initialized', joola.VERSION);
      });
    </script>
  </head>
  <body>
    ...
  </body>
</html>

That's it, your SDK is available and ready for use.

Query

Joola's query "language" is simple, easy and straightforward and visualizations rely on the developer providing a valid query to be visualized on screen.

In this example we will drawing a Timeline showing the number of rounds.played over the last 30 days.

var query = {
  timeframe: 'last_30_days',
  interval: 'day',
  metrics: ['rounds.played'],
  collection: 'Gameplay'
};

Visualize

So far, we have prepared an HTML file by embedding the JS in it, we've also designed a query to be visualized.

Lastly, we need to instruct Joola to draw the Timeline, here's how the final HTML should look like:

<html>
  <head>
    <script src="<APPLICATION_URL>/joola.min.js?APIToken=<READER_API_TOKEN>"></script>
    <script type="text/javascript">
      joola.on('ready', function(){
        console.log('Joola is ready', joola.VERSION);
        var query = {
          timeframe: 'last_30_days',
          interval: 'day',
          metrics: ['rounds.played'],
          collection: 'Gameplay'
        };
        $('#timeline').Timeline({
          caption: 'Movie views over last 30 days', 
          query: query
        });
      });
    </script>
  </head>
  <body>
    <div id="timeline"></div>
  </body>
</html>

Look & Feel

Joola's SDK allows you to control every detail of the embedded visualization's look & feel.

The Default Theme

Joola ships with a custom default theme to give developers a nice look & feel out-of-the-box. Developers can choose either to use the default theme and build on top of it with their own custom CSS classes or to not load the default theme at all and design their data application from scratch by setting:

<script src="<APPLICATION_URL>/joola.min.js?APIToken=<READER_API_TOKEN>&includecss=false"></script>

Or if initializing manually:

<script src="https://<APPLICATION_URL>/joola.min.js"></script>
<script type="text/javascript">
  joola.init({
    APIToken: "<READER_API_TOKEN>", 
    includecss: false
  }, function(err) {
    if (err) 
      throw err;
    console.log('Joola initialized', joola.VERSION);
  });
</script>

Twitter Bootstrap

We use Twitter Bootstrap as basis for the default theme, so to get best results make sure you include Twitter Bootstrap on the webpage.

<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.3.1/css/bootstrap.min.css">

Events

Joola's SDK uses Events for communication with the hosting webpage. Here are the available events:

Event Description Signature
ready Fires once when Joola is ready for use. function(err, ref)- err includes any error experienced.- ref holds reference to the Joola object.
connected Fires when Joola is (re)connected to the application.
disconnected Fires when Joola is disconnected from the application. function(reason)- reason holds the reason for the disconnection, if known.
error Fires when an unhandled general exception is thrown. function(err)- err holds the error.

Here's an example of how Events can be used as part of your HTML page.

<html>
  <head>
    <script src="https://<APP_URL>.app.joo.la/joola.min.js"></script>
    <script type="text/javascript">
      joola.init({"APIToken": "<YOUR_API_TOKEN>"}, function(err) {
        if (err) 
          throw err;
        console.log('Joola initialized', joola.VERSION);
      });
      joola.on('ready', function(err, ref){
        if (err)
          throw err;
        console.log('Joola is ready for work');
      });
      joola.on('connected', function(){
        console.log('Joola connected.');
      });
      joola.on('disconnected', function(reason){
        console.log('Joola disconnected.');
      });
      joola.on('error', function(error){
        console.log('Joola general error occured.');
      });
    </script>
  </head>
  <body>
    ...
  </body>
</html>