Widgets

What are widgets?

Apps can use widgets to render a web application inside an iframe or a webview within Flock. Besides doing everything a normal webapp can, a widget can also interact with the Flock client hosting it. This allows you to extend Flock's UI in many wonderful and amazing ways.

There are three types of widgets that one can create in Flock.

Modal Widget

A Modal Widget appears as a blocking popup on desktop and as a full window web view on a mobile. For eg Notes, Code Snippets and Polls all use a modal widget to enable the user to create an attachment and an attachment picker button to launch the same. The image below depicts a modal widget on the desktop.

The image below depicts a modal widget on a mobile. Note that the modal occupies the entire mobile screen area.

Sidebar Widget

A Sidebar Widget is shown below. Sidebar widgets are only available on the desktop client.

For eg:

The Todo app uses them to list all the todos for a given chat
The Notes app uses them to list all the notes shared within a chat

Attachment Widget

An Attachment Widget appears inline in the chat pane on desktop, and opens inside a modal when clicked on a mobile. Check Sending Attachments for more details on sending an Attachment widget from your app.

For eg:

The polls app uses an Attachment widget to show interactive polls right inside the chat pane
Code Snippets and Notes app use an Attachment widget to show a preview of their content

How do I open a widget?

Widgets can be opened in one of two ways:

Either you can configure the open widget client action for a slash command, launcher button, attachment button, etc.

Or you can create an attachment widget by providing a widget URL (and dimensions, for desktop) inside a message Attachment.

Adding a widget to an attachment

 {
    "title": "attachment title",
    "description": "attachment description",
    "views": {
        "widget": { "src": "<widget url>", "width": 400, "height": 400 }
    }
}

When a widget is launched, Flock simply creates an iframe (on desktop) or in a webview (on mobile), and within that launches the widget URL specified by you.

What query parameters are appended to the widget URL?

These parameters provide context about how the widget was launched. Your widget URL can be a fully interactive web application.

Name	Description
`flockEvent`	The JSON of the event that created the widget, serialized into a string. For eg if the widget was triggered by a button press you will get the JSON of the client.Pressbutton event
`flockEventToken`	The event token that your app should use to authenticate the Flock user who opened this widget
`flockClient`	One of either `desktop`, `ios` or `android`
`flockWidgetType`	The widget type. It can be one of the following: `modal` – a modal widget. On mobile, this is the only value possible. `sidebar` – a sidebar widget. Only used on desktop. `inlineAttachment` – used when an attachment widget is opened inline in the chat pane. Only used on desktop.

Can my widget interact with the Flock client?

Yes. Flock provides a handy Javascript library - flock.js that you can include in your web app. Some of the things that you can do with flock.js are:

Use the currently opened widget to open another widget. For eg launch a modal widget from a sidebar widget
Launch the browser
Close the current widget (only applicable for modal widgets)

See flock.js for more details.

My widget does not open up. What is going wrong?

If your widget doesn't load, ensure that:

Your widget URL is over HTTPS. The desktop client on macOS and the web client will not load your widget unless it is over HTTPS.
Your widget URL does not include X-Frame-Options or Content-Security-Policy: frame-src in the HTTP response. Widgets are loaded inside an iframe in the desktop and web clients, and presence of these headers will prevent them from loading under Flock.

Content

Space Tools