Working with apps

Apps in are represented by a class that handles the data of the app and the underlying panel that handles the frame. It also handles the communication with the app and how it behaves in it's environment.

App selectors

App selectors are used to refer to an app or define an app. Once you have defined your app, it can be created or fetched from the backend. You may then refer to your app by simply using the id of your choice.

App definition

An app definition is always an object with properties. To define an app you need at least an id of your choice, an app type and a container to place the app in. The container must have a defined size (for example width and height), since the app will adapt to the size of the container.

const app = weavy.app({
  id: "my-messenger",
  type: "messenger",
  container: "#my-container"
})

Referring to a defined app

Once you have defined your app you may reference it any time by the id (string) or by the appId used by the backend.

let messenger = weavy.app("my-messenger");
let messenger = weavy.app(773471);

Traversing apps

All defined apps are also accessible via weavy.apps[] on the weavy instance. It can be used to traverse all apps.

let messenger = weavy.apps.filter((app) => app.id === "my-messenger");

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.
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.
id* string Unique string id of your choice. Must not contain whitespace.
name string Display name of the app.
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

* Required

App types

Defines which app type to load.

App type Description
"messenger" Context-independent messaging with one-to-one and group conversations.

Control buttons

You may display a close button and a maximize button for the app. The close button comes handy if you have added open/close handling to your app. The maximize button will expand the app to fill the entire browser window which may be useful to get a larger view to work with. You can turn on both by specify controls: true in options or turn them on individually by specifying an object in options.

const app = weavy.app({
  id: "my-messenger",
  type: "messenger",
  container: "#my-container",
  controls: {
    close: false,
    maximize: true
  }
})

Controlling maximize

The maximize button can also be configured with additional styles to add when the maximize is applied. The styles should be provided with an object containing CSS properties in DOM notation (javascript).

const app = weavy.app({
  id: "my-messenger",
  type: "messenger"
  container: "#my-container"
  controls: {
    maximize: {
      top: "3rem"
    }
  }
})

If you want to use a custom maximize button you may also trigger the maximize by script using the app.panel.maximize() method.

const app = weavy.app({
  id: "my-messenger",
  type: "messenger",
  container: "#my-container"
})

// Set maximize using custom buttons

// Maximize
document.querySelector("#myMaxButton").addEventListener("click", () => {
  app.panel.maximize(true);
});

// Restore
document.querySelector("#myRestoreButton").addEventListener("click", () => {
  app.panel.maximize(false);
});

// Toggle and custom style
document.querySelector("#myToggleButton").addEventListener("click", () => {
  app.panel.maximize(null, { top: "3rem" });
});

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
.appId int The server appId of the app, recieved from app data.
.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
.id string The id of the app, defined in options.
.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".
.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.

Weavy Docs