Apps
In Weavy we use the "apps" terminology for our main features (posts, chat, files etc.). Currently the following apps are available for use in the drop-in UI:
App type | Description |
---|---|
chat |
Contextual real-time group chat. |
files |
A contextual app for storing, viewing, and discussing files (physical and cloud). |
messenger |
Non-contextual, private real-time messaging with one-to-one and group conversations. |
posts |
A contextual app for posting updates on, and discussing, different topics. |
There are two different types of apps: contextual and non-contextual. Contextual apps are connected to a specific context or entity that you define. There can be multiple contextual apps of the same type, whereas a non-contextual app only exists in one single instance.
Initializing apps
To initialize an app you need to provide the drop-in UI with an app definition. An app definition is always an object with properties.
Non-contextual apps
For non-contextual apps you need to define the app type
and the container
to place the app in.
const app = weavy.app({
type: "messenger",
container: "#my-container"
})
Contextual apps
A contextual app must first be created in the Weavy backend and your user must be added as member before it can be loaded in the drop-in UI. For these apps you should first call the Web API from your server-side code to initialize the app.
Example: Execute a single request that creates the app (if it does not already exist) with the specified uid
and type
. Then adds the user with the given uid
as a member (if not already a member).
$ curl -H 'Authorization: Bearer {token}' {WEAVY_BACKEND_URL}/api/apps/init -d '{app: {"uid": "product-256", "name": "Product 256 chat", "type": "chat"}, user: {"uid": "u32"}}'
Once the app exists on the Weavy backend and your user is a member you can define it as usual and it will be loaded and displayed in the drop-in UI. For contextual apps you need to define the uid
of the app, it's type
and a container
to place the app in.
const app = weavy.app({
type: "chat",
uid: "product-256",
container: "#my-container"
})
The
uid
is a string that uniquely identifies your context (typically your internal entity id) for example a product page, but since it cannot contain whitespace and must contain at least one non-digit you might need to customize it. For instance, if a product has the integer id256
in your system you can create anuid
by adding a prefix, e.g."product-256"
.
Options
When defining an app you can specify additional options.
Option | Type | Description |
---|---|---|
className |
string | Classnames that will be set for the app panel. |
container * |
element | string | The container where the app should be placed. May be a DOM element or a string selector. The container must have a defined size (for example width and height), since the app will adapt to the size of the container. |
controls |
boolean | object | Set to true to show panel controls. You may also set specific controls in an object. See control buttons |
css |
string | Additional CSS to add to the app panel. See styling. |
group |
string | Group name when linking several apps in the same container. See open/close handling. |
uid |
string | The uid is a string that uniquely identifies your context. Must contain at least one non-digit character. |
open |
boolean | Sets whether the app should open automatically when initialized. Defaults to true . |
stylesheet |
string | string[] | Url or array of urls to stylesheets for the app. See styling. |
type * |
string | The type of the app, e.g. messenger , chat or files . |
* Required
Properties
Some properties are available instantly when you have defined your app, but most of the properties are available from the point when the app has been fully initialized. Await the whenInitialized()
promise to make sure the properties are set.
Property | Type | Description |
---|---|---|
.autoOpen |
boolean | Will the app open automatically when loaded? Defaults to true |
.container |
Element | string | The container where the app is placed. |
.data |
object | The server data for the app |
.isBuilt |
boolean | Has the app built the DOM nodes? |
.isInitialized |
boolean | Has the app initialized and fetched from the server? |
.isLoaded |
boolean | Is the app loaded and ready? |
.isOpen |
boolean | Is the app currently open? Returns the open status of the app panel. |
.name |
string | The name of the app, defined in options or received from app data. |
.options |
object | The options for defining the app. |
.panel |
WeavyPanel | The underlying app panel handling the frame. |
.root |
object | The root object for the container of the app. |
.type |
string | The short readable type of the app, such as "messenger". |
.uid |
string | The uid of the app, defined in options. null for non-contextual apps. |
.url |
string | The url of the app, received from app data. |
.weavy |
Weavy | The Weavy instance the app belongs to. |
Promises
Each app has promises and events part of the asynchronous lifecycle.
Promise | Description |
---|---|
.whenInitialized() |
When the app has been fetched from the backend. |
.whenBuilt() |
When the DOM nodes for the app has been built. |
.whenLoaded() |
When the app has loaded in the frame. |
Events
There are app events triggered when the app changes state. All events are propagated to the weavy instance with a reference to the triggering app
as event data. This means you also can add general listerners for all apps on the weavy instance. See events for more info on the event system.
You can register event listeners for a specific app using app.on()
.
Event methods
The event methods register handlers for the specific app. See events for details on how to use event methods.
Method | Description |
---|---|
.on(eventNames, [selector], handler) |
Event listener registration. |
.one(eventNames, [selector], handler) |
One-time event listener registration. Unregisters automatically after one triggering. |
.off(eventNames, [selector], handler) |
Unregisters event listener. Must reference the same handler as when registered. |
.triggerEvent(eventName, [data]) |
Triggers an event on app. |
Event | Description |
---|---|
"app-init" |
Triggered when app data has been fetched from the server. |
"app-build" |
Triggered when the app has built the DOM nodes. |
"app-load" |
Triggered when the app has loaded it's contents. |
"app-open" |
Triggered when the app panel is opened. |
"app-close" |
Triggered when the app panel is closed. |
"app-toggle" |
Triggered when the app panel is toggled. Is always followed by either "app-open" event or "app-close" event. |
"message" |
Triggered when the app receives a postMessage sent from the panel frame. |
Methods
.addStyles(styles) ⇒ boolean
Check if another app or an object is matching this app. It checks for a match of the id property or the server appId property.
Param | Type | Description |
---|---|---|
styles |
string | Object | CSS string or styles object |
[styles.css] |
string | Optional css to add. |
[styles.stylesheet] |
string | Optional stylesheet url to load. |
.open([destination]) ⇒ Promise
Opens the app panel and optionally loads a destination url after waiting for whenBuilt. If the app is grouped it also closes the other apps in the group.
Param | Type | Description |
---|---|---|
[destination] |
string | Destination url to navigate to on open |
.close() ⇒ Promise
Closes the app panel.
.toggle([destination]) ⇒ Promise
Toggles the app panel open or closed. It optionally loads a destination url on toggle open. If the app is grouped it also closes the other apps in the group.
Param | Type | Description |
---|---|---|
[destination] |
string | Destination url to navigate to on open |
.match(options) ⇒ boolean
Check if another app or an object is matching this app. It checks for a match of the id property or the server appId property.
Param | Type | Description |
---|---|---|
options |
WeavyApp | Object | |
[options.id] |
int | Optional id to match. |
[options.appId] |
string | Optional appId to match. |
.postMessage(message, [transfer]) ⇒ Promise
Sends postMessage to the app panel frame. Returns a promise that is resolved when the message has been delivered and rejected if the message fails or has timed out.
See: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
Param | Type | Description |
---|---|---|
message |
object | The Message to send |
[transfer] |
Transferable[] | A sequence of Transferable objects that are transferred with the message. |
.remove() ⇒ Promise
Removes the app in the client and the DOM. The app will not be removed on the server and can be added and fetched at any point again.
.reset() ⇒ Promise
Resets the app panel.