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://secure.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">×</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: https://alexbilbie.com/2013/09/securely-store-access-tokens-in-single-page-web-app/