We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
FIWARE.OpenSpecification.Apps.WidgetAPI - FIWARE Forge Wiki


From FIWARE Forge Wiki

Jump to: navigation, search


Introduction to the Widget API

Please check the following FI-WARE Open Specification Legal Notice (implicit patents license) to understand the rights to use this open specification.

UPM strives to make the specifications of this Generic Enabler available under IPR rules that allow for a exploitation and sustainable usage both in Open Source as well as proprietary, closed source products to maximize adoption.

This Open Specification is exploitable for proprietary 3rd party products and is exploitable for open source 3rd party products. This GE specification should be implementable without requiring patent pledges. However, the Copyright Holder of this spec (UPM) is not responsible for identifying patents for which a license may be required for any implementation of this specification.

Widget API Core

The Application Mashup GE offers two separate APIs that cannot be combined because of their different nature: The Widget API (the subject of this entry) is a JavaScript API, while the ApplicationMashupAPI is a RESTful one. You can find the Application Mashup Open RESTful API in this separate entry:

The Widget API is a JavaScript API that allows deployed widgets in a Mashup Execution Engine to gain access to its functionalities. It does not make sense to expose it as a RESTful API since it needs to be consumed by a widget in its own local execution environment. Amongst other functionalities, this API allows the widgets to gain access to remote resources. For example, in order to gain access to a remote REST API or to resolve cross-domain problems, a widget needs to use a proxy through the Widget API.

Intended Audience

This specification is intended for service front-end (aka gadget/widget) developers. This document provides a full specification of how to make widgets interoperate with the Mashup Execution Engine. To use this information, the reader should firstly have a general understanding of the Generic Enablers for Composition and Mashup.

You should also be familiar with:

  • JavaScript

API Change History

Revision Date Changes Summary
Apr 27, 2012
  • Initial version

How to Read This Document

It is assumed that reader is familiarized with JavaScript. Along the document, some special notations are applied to differentiate some special words or concepts. The following list summarizes these special notations.

  • A bold font is used to represent method names.
  • Function parameters are represented in italic font.

For a description of some terms used along this document, see ApplicationMashup.

Widget API


request options

Generic options:

  • contentType (String; default application/x-www-form-urlencoded): The Content-type header for a request. This header must be changed if data in another format (like XML) have to be sent.
  • encoding (String; default UTF-8): The encoding for the contents of a request. It is best left as-is, but should weird encoding issues arise, it might be necessary tweaking this.
  • method (String; default POST): The HTTP method to use for the request.
  • parameters (Object): The parameters for the request, which will be encoded into the URL for a get method, or into the request body for the other methods.
  • postBody (String): Specific contents for the request body on a post method. If it is not provided, the contents of the parameters option will be used instead.
  • requestHeaders (Object): A set of key-value pairs, with properties representing header names.
  • forceProxy (Boolean; default false): Sends the request through the proxy regardless of the other options passed.
  • context (Object; default null): this is the value to be passed as this parameter to the callbacks.

Callback options:

  • onSuccess: Invoked when a request completes and its status code belongs in the 2xy family. This is skipped if a code-specific callback is defined (e.g., on200), and happens before onComplete.
  • onFailure: Invoked when a request completes and its status code exists but it does not belong in the 2xy family. This is skipped if a code-specific callback is defined (e.g. on403) and happens before onComplete.
  • onXYZ (with XYZ representing any HTTP status code): Invoked just after the response is complete if the status code is the exact code used in the callback name. Prevents execution of onSuccess and onFailure. Happens before onComplete.
  • onComplete: Triggered at the very end of a request's life-cycle, after the request completes, status-specific callbacks are called, and possible automatic behaviors are processed. Guaranteed to run regardless of what happened during the request.


MashupPlatform.http.buildProxyURL(url, options)

Builds a URL suitable for working around the cross-domain problem. This usually is handled using the Mashup Execution Engine proxy but it also can be handled using the access control request headers if the browser has support for them. If all the needed requirements are meet, this function will return a URL without using the proxy.

  • url - Target URL.
  • options - Optional object with request options (see the request options section for more details).

MashupPlatform.http.makeRequest(url, options)

Sends an HTTP request. This method internally calls the buildProxyURL method for working around any possible problem related with the same-origin policy followed by browser (allowing CORS requests).

  • url - Target URL of the request.
  • options - Optional object with request options (see the request options section for more details).



MashupPlatform.wiring.pushEvent(outputName, data)

Sends an event through the wiring.

  • outputName - Name of the output endpoint as defined in the GDL.
  • data - Event content.

MashupPlatform.wiring.registerCallback(inputName, callback)

Registers a callback for a given input endpoint. If the given endpoint already has registered a callback, it will be replaced by the new one.

  • inputName - Name of the input endpoint as defined in the GDL.
  • callback - Callback function to use when an event reaches the given input endpoint.


Widgets may use the methods defined in this module to retrieve and to be notified of changes in the values of their preferences.



Retrieves the value of a preference.

  • key - Name of the preference to fetch.


Registers a callback for listening preference changes.

  • callback - Callback function that will be called when widget's preferences are changed.
Personal tools
Create a book