LocalFocus Widget API

Introduction

Users can create iframe based widgets with LocalFocus. The Widget API is a small javascript function that helps developers to add simple functionalities, like a loading spinner. It uses postMessage.

This script, code examples and documentation are licenced under MIT Licence.

Getting started

Download the latest localfocusapi.js and copy the function or include the script in your webpage:

                    
<script src="path-to-the-script/localfocusapi.js"></script>

Append ?api=1 to the widget's links to force widgets to listen to commands:

                    
<iframe class="localfocusvisual" scrolling="no" frameborder="0" style="width:100%;height:550px;overflow:hidden" src="https://localfocus2.appspot.com/5846cde78fdeb?api=1"></iframe>

Listen

Use case: create a loading spinner

This example demonstrates a loading spinner. Widgets send signals to your webpage about their current state. This example listens to the "ready" signal with the widgetObject.on() function. It then hides the spinner and fades in the chart.

The code

Control

Use case: create custom interaction buttons

LocalFocus visualisations can have interactive options. Use the widgetObject.activate() function to activate an item from the dropdown menu. Want to create your own interaction buttons? With the noui=1 parameter you can hide the chart's default dropdown menu.

The code

In depth

Link parameters

You can (and must) append parameters to the iframe links:

`api=1` (required! This activates the Widget API)	It forces the widget to listen to API commands.
`noui=1`	Disable the widget's default interaction panel. Now you can create your custom control panel. Maps and tables are not supported.

The LocalFocusAPI Object

With the LocalFocusAPI you can select iframes that contain LocalFocus widgets.

LocalFocusAPI.select(selector)

Select one widget that you want to control.

Arguments

selector: element or string. When string, it is a string containing one or more CSS selectors separated by commas. It returns only the first matched element wrapped with a new widgetObject.

Returns

A new object widgetObject

                            
// Select first iframe and activate '2015'
LocalFocusAPI.select('iframe').activate('2015');

// Select by iframe element and activate '2015'
var element = document.getElementById('#mywidget');
LocalFocusAPI.select(element).activate('2015');

A widgetObject Object

Commands specific widgets using the widgetObject object.

widgetObject.on(event, callback)

Only the "ready" event is supported. This event will be broadcast when the widget finishes loading and rendering.

Arguments

event: string. Only "ready" is supported.
callback: function. The current widgetObject will be passed as this

Returns

Current widgetObject

                            
// Get a widgetObject
var widgetObject = LocalFocusAPI.select("iframe");

// Wait for a widget to be loaded and activate "2014"
widgetObject.on('loaded',function(){
    this.activate("2014");
});

// Wait for widget to be ready and activate "2015"
widgetObject.on('ready',function(){
    this.activate("2015");
});

// Watch for user click events
widgetObject.on('click',function(item){
    console.log(item);
});

widgetObject.activate(label)

Visualisations can have interactive features. To activate one of the labels using the API, use this method. Maps and tables are not supported.

Arguments

label: string. Must correspond with the label of the interactive feature, case-sensitive.

Returns

Current widgetObject

                            
// Get a widgetObject
var widgetObject = LocalFocusAPI.select("iframe");

// Wait for a widget to be loaded and activate "2014"
widgetObject.on('loaded',function(){
    this.activate("2014");
});

widgetObject.element()

Get the iframe element.

Arguments

None

Returns

iframe element

                            
// Get a widgetObject
var widgetObject = LocalFocusAPI.select("iframe");

// Get the iframe element
widgetObject.element();