1. Reference
  2. UIKit JS
  3. Apps

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 UIKit JS:

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 UIKit JS. 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 UIKit JS. 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 id 256 in your system you can create an uid 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.

Weavy Docs