Widgets
Embed the platform's tools, such as the map, the form and the item picker, in your own web page with an iframe.
A widget is a small page of the platform that you embed in your page with an iframe and talk to with postMessage. The platform's own Apps use the same way: the map in Data Studio and the Share box in Drive are widgets.
A widget is not a dashboard widget of App Studio. That one is a chart or a table on a canvas. See App Studio.
URL and parameters
Every widget is at <site>/widgets/<name>. The parameters are in the query string.
| Parameter | Value |
|---|---|
_credential_type | bearer-token or api-key. Without it the widget shows 401. |
_token | The bearer token, for bearer-token. |
_api_key | The API key, for api-key. |
_origin | The origin of the embedding page, for example https://app.example.com. The widget sends its messages to this origin only. |
_message_token | A random string that you make. It proves that a message comes from this pair. |
_locale | th or en. |
_theme | light or dark. |
The parameters of each widget (for example item_id) are on that widget's page.
The token or API key is in the iframe's URL. Use a short-lived bearer token (API guide), and never put an API key with wide permissions in a public page.
The gateways take no username and password, so _credential_type=basic-auth does not work.
Messages
Every message is an object { messageToken, action, payload }. The receiver must check origin and messageToken before it uses one.
| action | Direction | Meaning |
|---|---|---|
ready | widget to your page | The widget has loaded and can take messages. Only the widgets that take post-widget-parameters send it: map, filter-builder and user-and-group-picker. |
post-widget-parameters | your page to the widget | Values too long for the URL, such as the map's options and features. Send it after ready. |
error | widget to your page | The widget could not do its work. |
close-with-error | widget to your page | The user pressed Close on the error page. |
Other actions belong to one widget, such as select of the item picker.
A widget shows an error page with a Close button when it cannot sign in (401), is not allowed (403), finds nothing (404) or fails (500). Close sends close-with-error to your page, which decides what to do next.
Example
<div id="box" style="height: 480px"></div>
<script>
const site = 'https://platform.example.com'
const token = '...' // a bearer token from /api/auth/oauth2/token
const messageToken = crypto.randomUUID()
const params = new URLSearchParams({
_credential_type: 'bearer-token',
_token: token,
_origin: location.origin,
_message_token: messageToken,
_locale: 'en',
_theme: 'light',
item_id: '<id of a web map>',
})
const frame = document.createElement('iframe')
frame.src = `${site}/widgets/map?${params}`
frame.style = 'width:100%;height:100%;border:0'
document.getElementById('box').append(frame)
addEventListener('message', (e) => {
if (e.origin !== site || e.data.messageToken !== messageToken) return
if (e.data.action === 'ready') {
frame.contentWindow.postMessage(
{ messageToken, action: 'post-widget-parameters', payload: { options: {} } },
site
)
}
})
</script>All widgets
| Widget | Name in the URL | What it does |
|---|---|---|
| Map | map | Shows a web map. |
| Geometry editor | inside the form | Draws or edits the geometry of a form field. |
| Form | form | Fills in a form or opens a Record. |
| Form editor | form-editor | Builds a form from a table's fields. |
| Item picker | item-picker | Picks Items from Drive. |
| Form list | item-list | Browses forms and starts a new one. |
| Item sharing | item-sharing | Sets who can open an Item. |
| Data picker | data-picker | Picks Records from a table. |
| Data import | data-import | Imports a collection of a file into a database. |
| User and group picker | user-and-group-picker | Picks users or groups. |
| Filter builder | filter-builder | Builds the filter of a layer. |
| Expression builder | expression-builder | Builds a label from text and fields. |
| Account card | account | The user card and Sign out. |
| Launcher | app | Opens other Apps. |