Table of Contents
Using the widgets
Learn how to implement the widgets in your custom integration.
01. April 2025
Table of Contents
Selection Widget
The selection widget is typically embedded into an iFrame as follows:
1 |
<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:
|
|
|
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:
|
|
|
Enabling selection of multiple assets
To enable selection of multiple assets in the Selection Widget, add ms=trueto 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.
|
|
|
Event payload
The variable event.data.asset 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.
|
|
|
Export Widget
The export widget is typically embedded into an iFrame as follows:
1 |
<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:
|
|
|
The event data has the following format:
|
|
|
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 to display 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 showtabs 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
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.
Note:It is generally strongly recommended to run FotoWeb, as well as any other web application, web service, or web page, on HTTPS only.
iframes
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:
- Internal iframes (Fotoweb pages embedding other FotoWeb pages) are allowed.
- Same origin iframes (third-party page on the same host embeds FotoWeb) are allowed.
- Cross-origin iframes (third-party page on a different host embeds FotoWeb) are blocked.
- 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.,
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. The plugin is an application using embeddable FotoWeb widgets that 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:
- 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). - 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.