Skip to main content
Documentation & User Guides | Fotoware

Using the widgets

Learn how to implement the widgets in your custom integration.

Selection Widget

The selection widget is typically embedded into an iFrame as follows:

<iframe src="..."></iframe>

where src is set to the URL of the selection widget, as described in the Creating integrations using embeddable widgets. The iFrame  can be shown, for example, as a modal dialog.

Once the user has selected an asset, an event is sent to the main application, which can be handled using the following JavaScript code:

function listener(event) {
    if (event.origin != tenantURL)
    if ( === 'assetSelected') {
        alert("An asset was selected: " +;
addEventListener("message", listener, false);


The tenantURL is the base URL of the FotoWeb site or tenant, e.g.,

The variable contains a JSON representation of the asset, as described in Asset Representation.

Having selected an asset in the Selection widget, the Export widget can now be used to modify the exported asset. If you prefer to do this programmatically, you can use the Export API to control the output.

Handling Cancel events in the Selection Widget

The Cancel button is not handled directly by the selection widget, because the selection widget cannot know what should happen if the user cancels selection. The application that embeds the selection widget can react to the user pressing cancel using the following JavaScript code:

window.addEventListener('message', function(event) {
  if ( === 'selectionWidgetCancel') {
    // Do something when the user clicks "Cancel"

Enabling selection of multiple assets

To enable selection of multiple assets in the Selection Widget, add ms=true to the query string when calling up the widget. 

When using this query string parameter to enable the selection of multiple assets, instead of sending a single json object, the data is sent in an array of assets - see Event Payload below. This is the case even if only one asset is selected when multi-select is enabled.

function listener(event) {
    if (event.origin != tenantURL)
    if ( === 'assetSelected') {
        if (Array.isArray( {
            // here you work with as an array of assets:
            var assets =;
            for (var i = 0, l = assets.length; i < l; i++) {
                var asset = assets[i];
                alert("This asset was selected: " + asset.href);
        } else {
            // single selection is in place
            alert("An asset was selected: " +;
addEventListener("message", listener, false);
Event payload

The variable contains a JSON representation of the asset. When the data from several assets is returned, it is delivered as an array.
For the complete payload of the asset data, see Asset Representation. === {
  event: 'assetSelected',
  asset: [
      href: 'assetHref1',
      href: 'assetHref2',
      href: 'assetHref3',

Export Widget

The export widget is typically embedded into an iFrame as follows:

<iframe src=""></iframe>

where ACCESS_TOKEN is the access token obtained in the authorization step, and ASSET_URL is the asset URL, which was obtained from the selection widget in the previous step. The iFrame can be shown, for example, as a modal dialog.

Note: The asset URL must be encoded using the JavaScript function encodeURIComponent.

Other Parameters:

Parameter Description
w A set width of the export
h A set height of the export
p A predefined preset
pub Publication text (used for easier identification of the export)

Once the user has exported the asset, an event is sent to the main application, which can be handled using the following JavaScript code:

function listener(event) {
    if (event.origin != tenantURL)
    if ( == 'assetExported') {
        var imageURL =;
        // Do something with the image URL
addEventListener("message", listener, false)

 The event data has the following format:

    "export": {
        "source": "...",
        "json": "...",
        "image": {
            "normal": "...",
            "highCompression": "...",
            "doubleResolution": "..."
        "widget": "...",
        "size": {
            "w": 921,
            "h": 627
    "caption": {
        "label": "...",
        "tooltip": "..."
    "publication": {
        "text": "..."
        "FIELD": "VALUE" | ["VALUE1", "VALUE2", ...],



Attribute Type Value
export.source URL (Asset)

URL of the exported asset.

Can be used to access the details of the asset using the API or displaying the details in a browser.

export.json URL (object)

JSON representation of the export.

Identical to this JSON representation

export.image URL (JPEG image) Processed and exported asset (normal version)
export.highCompression URL (JPEG image) Processed and exported asset (smaller file size and potentially reduced quality)
export.doubleResolution URL (JPEG image) Processed and exported asset (doubled resolution, for Retina and similar displays)
export.widget URL (HTML)

An HTML widget containing the processed and exported asset with a tooltip and caption and optional additional behavior, if enabled during export

Can be embedded using an iFrame.

export.size.w Integer Width of the exported image (normal version) in pixels
export.size.h Integer Height of the exported image (normal version) in pixels
caption.label String Caption string, if specified during export
caption.tooltip String Tooltip string, if specified during export
publication.text String Name of publication (free-form string), if specified during export
metadata Dictionary

Metadata of the asset when it was exported.

The keys in this dictionary are the field numbers (as strings).

The values are either strings (for regular fields) or arrays of strings (for bag fields).

Controlling user access to feature tabs in the widget

After choosing an image with the selection widget, FotoWeb displays the Export widget to let the user adjust the image size as well as crop and style the exported image. The options available here can be managed in two ways:

  • ​By enabling/disabling features in the FotoWeb site configuration in the Site Configuration. 
  • By sending parameters to the export widget in the URL. This can only be used to hide tabs. These parameters cannot be used to show tabs that are disabled in the site configuration settings described above.

Query parameters

Parameter Description
crop=false Image crop, size and rotate
enhance=false Enhancement filters
caption=false Image caption
action=false Click action behavior
behaviour=false Embed behavior (Ken Burns effect)
publication=false Publication information

Example URL: Hiding the crop and size tab


Special considerations


If FotoWeb widgets are to be embedded into web applications using HTTPS, then content security policy may require FotoWeb to use HTTPS as well. Otherwise, loading the widget may be blocked and only a blank page, dialog, or iFrame may be shown.

Note: It is generally strongly recommended to run FotoWeb, as well as any other web application, web service, or web page, on HTTPS only.


Generally, FotoWeb cannot be embedded into iFrames on domains that are not of the same origin. However, the embeddable widgets (Selection Widgets and Export Widget) are exempt from this rule. These widgets work in an iFrame because they are designed to be embedded into other applications as part of integrations.

The following rules apply:  

  1. Internal iframes (Fotoweb pages embedding other FotoWeb pages) are allowed.

  2. Same origin iframes (third-party page on the same host embeds FotoWeb) are allowed.

  3. Cross-origin iframes (third-party page on a different host embeds FotoWeb) are blocked.

  4. Cross-origin iframes embedding the widgets are allowed.


You can embed an application using the FotoWeb widgets into an HTML <iframe> on some other web page or web application. For security reasons, the FotoWeb login form cannot be loaded into an iFrame. Therefore, some extra work is required in such scenarios.

As an example, consider the following setup:

  • A FotoWeb site, e.g.,
  • A CMS system, e.g.,
  • A CMS plugin from a third party,

In this example, the CMS system embeds the plugin in an iFrame, and the plugin is an application using embeddable FotoWeb widgets which connect to the FotoWeb site.

When the user authorizes the plugin to connect to FotoWeb, the iFrame displays a blank page instead of a FotoWeb login form because of a content security policy. The following approach can be used to work around this limitation:

  1. Instead of navigating to the authorization URL ( directly, open it in a new browser tab or window (authorization tab).
  2. Use browser local storage and storage events for communication between the main application (in the iFrame) and the authorization tab.

This authorization flow SHOULD be triggered by a user action (the user selecting  Log in, for example), so the browser will not block the authorization tab as a potentially unwanted popup.