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 Widget Integration parent topic. 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)
        return;
 
    if (event.data.event === 'assetSelected') {
        alert("An asset was selected: " + event.data.asset.href);
    }
}
 
addEventListener("message", listener, false);

 

The tenantURL is the base URL of the FotoWeb site or tenant, e.g., https://acme.fotoware.cloud

The variable event.data.asset 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 (event.data.event === 'selectionWidgetCancel') {
    // Do something when the user clicks "Cancel"
  }
});

Export Widget

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

<iframe src="https://acme.fotoware.cloud/fotoweb/widgets/publish?access_token=ACCESS_TOKEN&i=ASSET_URL&PARAMETERS"></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)
        return;
     
    if (event.data.event == 'assetExported') {
        var imageURL = evt.data.export.export.image.normal;
        // 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": "..."
    },
    "metadata":{
        "FIELD": "VALUE" | ["VALUE1", "VALUE2", ...],
        ...
    }
}

where

 

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 image size, crop and style the exported image. The options available here can be controlled in two ways:

  • ​By enabling/disabling features in the FotoWeb site configuration in the Operations Center
  • 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 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

http://fwserver/fotoweb/widgets/publish?i=%2Ffotoweb%2Farchives%2F5003-Trip%2520pictures%2FPrivate%2FDSC00697jpg.info&crop=false

Special Considerations

HTTPS

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.

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

IFRAMEs

In some situations, an application using the FotoWeb widgets may be embedded 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., acme.fotoware.cloud.
  • A CMS system, e.g., blog.coyote.com.
  • A CMS plugin from a third party, apps.acme.com.

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

When the user authorizes the plugin to connect to FotoWeb, the IFRAME will show 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 (https://acme.fotoware.cloud/fotoweb/oauth2/authorize/...) 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 (e.g. the user pressing a "Log in" button), so the browser will not block the authorization tab as a potentially unwanted popup.