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 JS UI kit:
Class name | Tag name | Description |
---|---|---|
Chat |
<weavy-chat /> |
Contextual real-time group chat. |
Files |
<weavy-files /> |
A contextual app for storing, viewing, and discussing files (physical and cloud). |
Messenger |
<weavy-messenger /> |
Non-contextual, private real-time messaging with one-to-one and group conversations. |
Posts |
<weavy-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
Before you can use any apps you need to configure the url
and tokenFactory
in options.
Apps are initialized as a HTML Node that you need to add to your DOM. You can do this via javascript or HTML. Some apps require some options when initializing them and some have optional options. When creating apps in javascript, you can simply append the app to any existing node in the DOM.
Note: The container you place the app in must have a defined size (for example width and height), since the app will adapt to the size of the container.
Non-contextual apps
No app options are required when instantiating non-contextual apps, but you can optionally pass any of the common app options.
Javascript
const messenger = new Messenger({
className: "wy-dark"
})
document.getElementById("my-container").append(messenger)
HTML
<weavy-messenger class="wy-dark" />
Contextual apps
A contextual app must first be created in the Weavy environment and your user must be added as member before it can be loaded in the JS UI kit. 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_ENVIRONMENT_URL}/api/apps/init -d '{app: {"uid": "product-256", "name": "Product 256 chat", "type": "chat"}, user: {"uid": "u32"}}'
Once the app exists in the Weavy environment and your user is a member you can instantiate it as usual and it will be loaded and displayed in the JS UI kit. For contextual apps you need to define the uid
that you used when creating the app. Use the app class that corresponds to the type you defined.
Javascript
const chat = new Chat({
uid: "product-256"
})
document.getElementById("my-container").append(chat)
HTML
<weavy-chat uid="product-256" />
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"
.
Common options
When instantiating any app you can specify additional options.
Option | Type | Description |
---|---|---|
className |
string | Classnames that will be set for the app panel. |
css |
string | Additional CSS to add to the app panel. See styling. |
load |
boolean | Sets whether the app should load automatically when instantiated. Set it to false to use delayed loading in conjunction with the .load() method. Defaults to true . |
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 |
---|---|---|
.autoLoad |
boolean | Will the app open automatically when loaded? Defaults to true |
.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? |
.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. |
Promises
Each app has promises and events part of the their asynchronous lifecycle.
Promise | Description |
---|---|
.whenInitialized() |
When the app has been fetched from the environment. |
.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 also propagated to the weavy instance with a reference to the triggering app
as event data. This means you also can also add general listeners for all apps on the weavy instance.
You can register event listeners for a specific app using app.on()
.
Event methods
The event methods register handlers for the specific app.
Method | Description |
---|---|
.on(eventNames, handler) |
Event listener registration. |
.one(eventNames, handler) |
One-time event listener registration. Unregisters automatically after one triggering. |
.off(eventNames, 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. |
Messenger events
The Messenger has an additional event badge
when a new message is received. This is useful for displaying a badge with the number of unread messages somewhere in your app.
Event | Description |
---|---|
"badge" |
Triggered when the number of unread messages is updated. |
messenger.on('badge', (badge) => {
// update ui with number of unread conversations
const messengerBadge = document.getElementById('messenger-badge');
messengerBadge.innerText = badge.count > 0 ? badge.count : '';
});
Methods
.load() ⇒ Promise
Loads the content of the app. Useful in combination with delayed loading using the load: false
option when you don't want to load the app instantly.
.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.