Frontend Implementation

The most common use case for Blingalytics is to be displayed on a web page, so we wanted to provide a pre-baked solution that can get you up and running in minutes. You’re welcome to tweak it or even roll your own, but this is a great starting point.

In the HTML

To implement the Blingalytics frontend on your site, the first thing you’ll need to do is include the appropriate CSS and JavaScript files on the page. These static files are included under blingalytics/statics/css/ and blingalytics/statics/js/ and should be made available by your server.

CSS to include:

<link rel="stylesheet" href="/static/css/blingalytics.css" type="text/css" />

JavaScript to include:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>
<script src="/static/js/jquery.dataTables.min.js"></script>
<script src="/static/js/jquery.blingalytics.js"></script>

Once you’ve included the static dependencies on the page, you can use the blingalytics jQuery plugin to insert a report table anywhere on your page:

<script>
    jQuery('#selector').blingalytics({'reportCodeName': 'report_code_name'});
</script>

For now the plugin only accepts two options:

reportCodeName (optional)

The report class code_name attribute. This specifies which report should be displayed on the page. Defaults to 'report'.

url (optional)

The URL to hit when contacting the server for an AJAX response. Defaults to '/report/'.

On the backend

The blingalytics jQuery plugin inserts a bunch of HTML and JavaScript that talks over AJAX with your server. So your server, at the url you specify in the plugin options, should respond appropriately. To make this easy, a Python helper function is provided.

blingalytics.helpers.report_response(params, runner=None, cache=<LocalCache /tmp/blingalytics_cache>)

This frontend helper function is meant to be used in your request-processing code to handle all AJAX responses to the Blingalytics JavaScript frontend.

In its most basic usage, you just pass in the request’s GET parameters as a dict. This will run the report, if required, and then pull the appropriate data. It will be returned as a JSON string, which your request-processing code should return as an AJAX response. This will vary depending what web framework you’re using, but it should be pretty simple.

The function also accepts two options:

runner (optional)

If you want your report to run asynchronously so as not to tie up your web server workers while processing requests, you can specify a runner function. This should be a function that will initiate your async processing on a tasks machine or wherever. It will be passed two arguments: the report code_name, as a string; and the remaining GET parameters so you can process user inputs. By default, no runner is used.

cache (optional)

By default, this will use a local cache stored at /tmp/blingalytics_cache. If you would like to use a different cache, simply provide the cache instance.