Widget Basics

There are two anatomical parts of a widget

  • a JavaScript block
  • one or more DOM elements marking where the widget will be placed
<!-- Place this anchor tag where you want the button to go -->
<a href="https://foursquare.com/intent/venue.html" class="fourSq-widget" data-variant="wide">Save to foursquare</a>

<!-- Place this script somewhere after the anchor tag above. If you have multiple buttons, only include the script once. -->
<script type='text/javascript'>
  (function() {
    window.___fourSq = {"uid":"606"};
    var s = document.createElement('script');
    s.type = 'text/javascript';
    s.src = 'http://platform.foursquare.com/js/widgets.js';
    s.async = true;
    var ph = document.getElementsByTagName('script')[0];
    ph.parentNode.insertBefore(s, ph);
  })();
</script>
          

Each of these two parts contain configuration information. Global configurations in the JavaScript block apply to all widgets on the page. Instance configurations in a marker element only apply that specific widget.

Widget rendering can be deferred and initiated later. For even finer control, widgets can be programmatically constructed using the JavaScript API.

Https vs Http

If your site uses https, you need to make two small changes to the configuration block.

  1. Change the source of the JavaScript file to https://platform-s.foursquare.com/js/widgets.js
  2. Add {"secure":true} to the global configuration block (window.___fourSq)

Deferred Construction

If you want to search for marker elements to create widgets after the page has loaded or repeat the search after a DOM change, you can call:

fourSq.widget.Factory.go()

If deferring widget creation, consider setting explicit=false in the global configuration to avoid an initial pass at page load.

Programmatic Instantiation

Widgets can be initialized directly by calling the JavaScript class constructor. For example:

var widget = new fourSq.widget.SaveTo(optionalConfig);

If constructing a widget programmatically, once instantiated it needs to be added to the DOM. This can be done by calling one of three methods:

  • widget.append(domTarget) -- The visible widget will be appended to the DOM container
  • widget.replace(domTarget) -- The visible widget will be added the DOM as a replacement for the target node
  • widget.attach(domTarget) -- The widget’s onclick behavior will be attached to an existing DOM element but will not change the visible DOM. This is an optional method that not all widgets support

Events

Client applications can bind to widget events. All event listeners can be bound either during widget instantiation, as configuration parameters, or by calling the bind method on a widget instance. For example:

Widget DOM marker:

<a …. data-on-load=”globalFunctionName”> …</a>

Programmatic widget initialization option:

new fourSq.widget.SaveTo({
  onLoad: function() {}
});
          

Binding to a widget instance:

var widget = new fourSq.widget.SaveTo();
widget.bind(‘load’, function() {});
          

See the "Events" section of each widget's documentation for a list of that widget's bindable events

Global Configuration Parameters

The global configuration block should appear only once per page and is assigned to the global namespace variable window.___fourSq. Every widget that is instantiated on the page will read this configuration and, during instantiation, will append any local configuration to the global configuration. The three possible global configuration fields are:

  • uid - foursquare user or page id
  • onReady - A function to be called when the foursquare JavaScript library is completely loaded
  • explicit -- {true|false} -- A boolean indicating if the widgets should be initialized on page load. Defaults to true. If you intend to use the JavaScript API to instantiate widgets on demand, set this to false.

Instance Configuration Parameters

Individual configuration parameters can be passed to the widgets either as data attributes on the marker DOM elements or in JSON objects passed directly to the widget’s constructor if instantiating programmatically. Parameter keys are constructed using “-” when using data attributes and camel case when passing directly to the constructor. For example: data-user-name=”” vs. {userName: ‘’}. See the “Configuration Parameters” section of each widget’s documentation for a list that widget’s parameters.

Save to foursquare Widget

Class: fourSq.widget.SaveTo

Configuration Parameters

Key Required Default Values Description
vid no undefined any foursquare venue id configures the widget to directly point to an existing venue, no venue detection is used
variant no undefined undefined, 'wide' which size button to render
hideTooltip no false true, false to show description tooltip on hover
replaceButton no false true, false binds click behavior to DOM marker, does not replace or alter -- only for configuration via marker node
context no document element ID, self scopes the DOM search for vcard elements -- if self, assumes widget is an any-level child of a containing element with class vcard, otherwise looks up DOM element by ID.

Events

Event Argument(s) to callback function Description
load widget instance (this) a callback fired when the widget is rendered in the DOM
open widget instance (this) a callback fired when the widget is clicked and/or opened
close widget instance (this) a callback fired when an opened widget is clsoed
added none a callback fired when the user adds a venue/tip to their list through the widget

Methods

Method Argument(s) and Return value Description
open none triggers the widget to open (usually trigged by user click)

Follow Widget

Class: fourSq.widget.Follow

Configuration Parameters

Key Required Default Values Description
fuid yes none foursquare page or brand id configures the foursquare page or brand that this button will follow once clicked
userName false undefined string optional display name for the user that will show in tooltip and next to the button
variant false undefined undefined, 'wide' which size button to render
hideTooltip false false true, false to show description tooltip on hover
replaceButton no false true, false binds click behavior to DOM marker, does not replace or alter -- only for configuration via marker node

Events

Event Argument(s) to callback function Description
load widget instance (this) a callback fired when the widget is rendered in the DOM
open widget instance (this) a callback fired when the widget is clicked and/or opened
close widget instance (this) a callback fired when an opened widget is clsoed

Methods

Method Argument(s) and Return value Description
open none triggers the widget to open (usually trigged by user click)