NAV Navbar
Logo
html

Introduction

Welcome to the Wink Reports Browser Library. When embedded in an HTML page, the library allows reports to be embedded into your own website.

At present, the browser library is in beta and must be explicitly enabled for your account by out support staff. Send us an email at contact@winkreports.com and we’ll get you up and running.

Installation

Use of the browser library requires a Javascript library and CSS file to be included in your page.

Prerequisites

The script library requires jQuery. Any recent version should be fine.

Styles

<head>
  <link rel="stylesheet" type="text/css" href="https://secure.winkreports.com/static/css/browser-lib/wink.css" />
</head>

Include a link to https://secure.winkreports.com/static/css/browser-lib/wink.css.

Scripts

<body>
  ...

  <script type="text/javascript" src="https://secure.winkreports.com/static/js/browser-lib/wink.js"></script>
  <script type="text/javascript">
    WinkReports.configure({
        apiToken: '-API token-',
    });
    jQuery(WinkReports.init);
  </script>
</body>

Include the script https://staging.winkreports.com/static/js/browser-lib/wink.js. It is recommended this be done at the very bottom of the <body> and after jQuery is included.

Include a script block which calls WinkReports.configure and sets up WinkReports.init to run on page load.

HTML Stubs

<div class="wink-dashlet" data-wink-dashlet="" data-report-name="Cashflow Forecast">
    <!-- loading image here - this will be replaced with dashlet contents -->
</div>

When the init function runs at page load, it will find any report stub elements and replace with report contents.

Create an html element (div is recommended) with the following attributes:

Attribute Description
data-wink-dashlet Required - used to identify report stubs
data-report-name Required - defines which report is placed here
class Recommended - use wink-dashlet to get default styles

Configuration

<script type="text/javascript">
  WinkReports.configure({
    apiToken: '-API token-',
    baseUrl: 'https://my-website.com/wink-proxy',
    organisationId: 'ABCD1234',
    hoverHandler: 'inside-datum'
  });
</script>

The script library takes a few configuration options via the configure function.

Option Description
apiToken Optional - if the library is reading directly from secure.winkreports.com, this is used to identify the user. It is recommended that a server side proxy is used to provide authentication tokens instead.
baseUrl Optional - defaults to https://secure.winkreports.com/api/v1. Use this to direct requests through a request proxy.
organisationId Optional - if a user based token is used, this specifies which organisation should be used for reports. This is automatically determined if using an OAuth token (which are applied to single organisations)
hoverHandler Optional - defines what happens when the user hovers the mouse over graph elements. Value should be one of none, inside-datum or fixed-position. Defaults to inside-datum.

Customisation

The look and feel of the dashlets and reports can be customised using CSS.

Dashlets

/* Change axis label colour */
.wink-dashlet .toyplot-coordinates-Axis text { fill: green; }

/* Change axis line colour */
.wink-dashlet .toyplot-coordinates-Axis line { stroke: blue; } 

Most dashlets render a graph as SVG. This allows the look of graph elements to be customised via CSS.

Reports

<body>
  <!-- Markup generated by browser library: -->
  <div id="wink-overlay"></div>
  <div id="wink-container">
    <a class="close" href="#close">&times;</a>
    <div id="wink-report-body" class="wink-report" data-report-name="Cashflow Forecast">
      <table class="responsive">
        <tbody>
          <tr>
            <td data-ref="A1">Cell value</td>
          </tr>
        </tbody>
      </table>
    </div>
  </div>
</body>
<style type="text/css">
    /* Make cell E1 in the Cashflow Forecast report blue */
    #wink-report[data-report-name="Cashflow Forecast"] [data-ref="E1"] {
        color: blue;
    }
</style>

When a user clicks a dashlet, the full report body will be shown fullscreen in the browser. The browser library will create a few elements to make this happen.

<div id="wink-overlay"> to dim the area around the report body.

<div id="wink-container"> to fill the browser screen.

<div id="wink-report-body" class="wink-report"> with the actual report body.

<a class="close" href="#close"> to allow the user to close the full report.

Normal CSS can be used to customise the report body. Individual reports and cells can be targetted using data-report-name and data-ref attributes, but it is recommended that most customisations are done by requesting the report design to be changed.

Security

It is recommended that authorisation tokens are not sent to the browser by including the value in the HTML. If an attacker intercepts the token in transit or discovers the token via some malicious Javascript, the token can be used to make API requests on behalf of the user.

Instead, it is recommended that API requests are proxied through your own server. The proxy will redirect the request to https://secure.winkreports.com, but including the correct auth token for the user. The request results are then piped back to the user.

Reference: http://alexbilbie.com/2014/11/oauth-and-javascript/