Weavy

The core class for the Weavy client.

Kind: global class

new Weavy(...options)

All options are optional. You may use multiple Weavy.presets together with options when constructing a weavy instance. Multiple option sets are merged together.

If you want to connect to a specific server use the url option.

These option presets are available for easy configuration

  • Weavy.presets.noplugins - Disable all plugins
  • Weavy.presets.core - Use the minimal core plugin configuration without additional plugins.
ParamDescription
...options : options

One or multiple option sets. Options will be merged together in order.

Example
var weavy = new Weavy();

var devSettings = {
    logging: true
};

var coreDevWeavy = new Weavy(Weavy.presets.core, devSettings, { url: "http://myweavysite.dev" });

Instance members

.options : Object

Main options for Weavy. The JWT option is required. When weavy initializes, it connects to the server and processes the options as well as using them internally.

Kind: instance property of Weavy
See: Client Options
Properties
NameDefaultDescription
[container : Element ]

Container where weavy should be placed. If no Element is provided, a <weavy> root is created next to the <body>-element.

[className : string ]

Additional classNames added to weavy.

[https : string ]"adaptive"

How to enforce https-links.
force - makes urls https.
adaptive - enforces https if the calling site uses https.
default - makes no change.

[id : string ]

An id for the instance. A unique id is always generated.

jwt : string

The JWT token passed to WeavyAuthentication.

[init : boolean ]true

Should weavy initialize automatically?

[includePlugins : boolean ]true

Whether all registered plugins should be enabled by default. If false, then each plugin needs to be enabled in plugin-options.

[lang : string ]

Language code of preferred user interface language, e.g. en for English. When set, it must match one of your configured languages.

[logging : Object : boolean ]

Options for console logging. Set to false to disable.

[logging.color : string ]

Hex color (#bada55) used for logging. A random color is generated as default.

[logging.log : boolean ]

Enable log messages in console.

[logging.debug : boolean ]

Enable debug messages in console.

[logging.info : boolean ]

Enable info messages in console.

[logging.warn : boolean ]

Enable warn messages in console.

[logging.error : boolean ]

Enable error messages in console.

[plugins : Object.<string, Object> ]

Properties with the name of the plugins to configure. Each plugin may be enabled or disabled by setting the options to true or false. Providing an Object instead of true will enable the plugin and pass options to the plugin. See the reference for each plugin for available options.

[preload : boolean ]

Start automatic preloading after load

[shadowMode : boolean ]closed

Set whether ShadowRoots should be closed or open (not recommended).

spaces : Array.<options>

Array of space definititions with apps to initialize spaces directly at initialization. See space.

[tz : string ]

Timezone identifier, e.g. Pacific Standard Time. When specified, this setting overrides the timezone setting on a user´s profile. The list of valid timezone identifiers can depend on the version and operating system of your Weavy server.

[url : string ]

The URL of the Weavy-installation to connect to. Defaults to the installation where the script came from.


.id : string

The weavy instance id

Kind: instance property of Weavy

.url : URL

The url of the weavy server.

Kind: instance property of Weavy

.isInitialized : boolean

True when inatialization has started

Kind: instance property of Weavy

.isBlocked : boolean

True when frames are blocked by Content Policy or the browser

Kind: instance property of Weavy

.isLoading : boolean

True when weavy is loading options from the server.

Kind: instance property of Weavy

.isLoaded : boolean

True when weavy has loaded options from the server.

Kind: instance property of Weavy

.connection : WeavyConnection

Reference to the instance of the realtime connection to the server.

Kind: instance property of Weavy

.getId([id]) ⇒ string

Appends the weavy-id to an id. This makes the id unique per weavy instance. You may define a specific weavy-id for the instance in the options. If no id is provided it only returns the weavy id. The weavy id will not be appended more than once.

Kind: instance method of Weavy
Returns: string - Id completed with weavy-id. If no id was provided it returns the weavy-id only.
ParamDescription
[id : string ]

Any id that should be completed with the weavy id.


.removeId(id) ⇒ string

Removes the weavy id from an id created with getId

Kind: instance method of Weavy
Returns: string - Id without weavy id.
ParamDescription
id : string

The id from which the weavy id will be removed.


.init([options]) ⇒ whenInitialized

Initializes weavy. This is done automatically unless you specify init: false in options.

Kind: instance method of Weavy
Emits: init
Resolved: When the weavy instance is initialized, ready and loaded.
ParamDescription
[options : options ]

Any new or additional options.


.createRoot(parentSelector, id) ⇒ root

Creates an isolated shadow root in the DOM tree to place nodes in.

Kind: instance method of Weavy
Emits: create-root
ParamDescription
parentSelector : Element : string

The node to place the root in.

id : string

Id of the root.


.getRoot(id) ⇒ root

Get a Weavy shadow root by id.

Kind: instance method of Weavy
ParamDescription
id : string

The id of the root.


.ajax(url, [data], [method], [settings]) ⇒ Promise

Method for calling JSON API endpoints on the server. You may send data along with the request or retrieve data from the server.

Fetch API is used internally and you may override or extend any settings in the external:fetch by providing custom fetch init settings.

You may of course call the endpoints using any other preferred AJAX method, but this method is preconfigured with proper encoding and crossdomain settings.

Kind: instance method of Weavy
ParamDefaultDescription
url : string : URL

URL to the JSON endpoint. May be relative to the connected server.

[data : object ]

Data to send. May be an object that will be encoded or a string with pre encoded data.

[method : string ]"GET"

HTTP Request Method https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods

[settings : external:fetchSettings ]

Settings to extend or override fetch init settings.

Example (Requires custom endpoints on the server, normally included in a sandbox installation.)
// Create a space and open it as a panel
weavy.ajax("/api/spaces/", { name: "My Space" }, "POST").then(function(result) {
  weavy.panels.addPanel("space" + result.id, result.url);
  weavy.panels.open("space" + result.id);
});

// Search for a space
weavy.ajax("/api/search", { q: "My Space", et: "space"}).then(function(result) {
  console.log("Found " + result.count + " results");
});

.destroy([keepConnection]) ⇒ Promise

Destroys the instance of Weavy. You should also remove any references to weavy after you have destroyed it. The destroy event will be triggered before anything else is removed so that plugins etc may unregister and clean up, before the instance is gone.

Kind: instance method of Weavy
Emits: destroy
ParamDefaultDescription
[keepConnection : boolean ]false

Set to true if you want the realtime-connection to remain connected.


.data : Object

Client configuration data from the server. Based on what is passed in options to the server and currently defined spaces.

Kind: instance typedef of Weavy
Properties
NameDescription
spaces : Array.<data>

List of configured spaces.

plugins : Object

Options for configured plugins.

[plugins.theme : Object ]

Options for the theme plugin

plugins.theme.logo : string

Thumb URL for the global installation logo.

plugins.theme.themeColor : string

Primary color for the theme in Hex color.

plugins.theme.clientCss : string

The CSS for the client. Gets injected in weavy roots.

status : string

Status of the server. Should be "ok".

version : string

Semver string of the server version. Should match the script version.


Authentication

.user : Object

Data about the current user. Use weavy.user.id to get the id of the user.

Kind: instance property of Weavy
Category: authentication

.authentication : WeavyAuthentication

Reference to the instance of the WeavyAuthentication for the current server.

You always need to define a JWT provider in your options. This may be a function that returns a JWT string or returns a promise that resolves a JWT string. The function will be called again whenever a new JWT token is needed. You may also provide a JWT string directly, then you can't benifit from weavy requesting a new token when needed.

See Client Authentication for full authentication documentation.

Kind: instance property of Weavy
Category: authentication

"signing-in"

Triggered when the authentication process has started.

Kind: event emitted by Weavy
Category: authentication

"clear-user"

Triggered when user data needs to be cleared. For example when a user is signing out.

Kind: event emitted by Weavy
Category: authentication

"authentication-error" ⇒ Object

Triggered when the authentication process was unsuccessful.

Kind: event emitted by Weavy
Category: authentication
Properties
NameDescription
method : string

Which metod that was used to authenticate "jwt" or "panel"

status : int

The HTTP error code from the server, like 401 for an unauthorized user

message : string

The message from the server, like "Unauthorized"


Eventhandling

.events : WeavyEvents

Instance of WeavyEvents which enables propagation and before and after phases for events.

The event system provides event chaining with a bubbling mechanism that propagates all the way from the emitting child trigger to the weavy instance.

All events in the client have three phases; before, on and after. Each event phase is a prefix to the event name.

  • The before:event-name is triggered in an early stage of the event cycle and is a good point to modify event data or cancel the event.
  • The on:event-name is the normal trigger point for the event. It does not need to be prefixed when registering an event listener, you can simly use the event-name when you register a listener. This is the phase you normally use to register event listeners.
  • The after:event-name is triggered when everything is processed. This is a good point to execute code that is dependent on that all other listers have been executed.

Cancelling an event by calling event.stopPropagation() will stop any propagation and cause all the following phases for the event to be cancelled.

Kind: instance property of Weavy
Category: eventhandling

.on([context], events, [selector], handler)

Registers one or several event listneres. All event listners are managed and automatically unregistered on destroy.

When listening to weavy events, you may also listen to before: and after: events by simply adding the prefix to a weavy event. Eventhandlers listening to weavy events may return modified data that is returned to the trigger. The data is passed on to the next event in the trigger event chain. If an event handler calls event.stopPropagation() or return false, the event chain will be stopped and the value is returned.

Kind: instance method of events
Category: eventhandling
ParamDescription
[context : Element ]

Context Element. If omitted it defaults to the Weavy instance. weavy.connection and wvy.postal may also be used as contexts.

events : string

One or several event names separated by spaces. You may provide any namespaces in the names or use the general namespace parameter instead.

[selector : string : Object ]

Only applicable if the context supports selectors, for instance jQuery.on().

handler : function

The listener. The first argument is always the event, followed by any data arguments provided by the trigger.

Example (Instance event)
weavyEvents.on("before:options", function(e, options) { ... })
weavyEvents.on("options", function(e, options) { ... })
weavyEvents.on("after:options", function(e, options) { ... })
 
Example (Realtime event)
weavyEvents.on(weavy.connection, "eventname", function(e, message) { ... })
  
Example (Connection event)
weavyEvents.on(weavy.connection, "disconnect.connection", function(e) { ... })
  
Example (Button event)
weavyEvents.on(myButton, "click", function() { ... })
  
Example (Multiple document event listeners using jQuery context and selector)
weavyEvents.on($(document), "show.bs.modal hide.bs.modal", ".modal", function() { ... })

.one([context], events, [selector], handler)

Registers one or several event listneres that are executed once. All event listners are managed and automatically unregistered on destroy.

Similar to on.

Kind: instance method of events
Category: eventhandling
ParamDescription
[context : Element ]

Context Element. If omitted it defaults to the Weavy instance. weavy.connection and wvy.postal may also be used as contexts.

events : string

One or several event names separated by spaces. You may provide any namespaces in the names or use the general namespace parameter instead.

[selector : string : Object ]

Only applicable if the context supports selectors, for instance jQuery.on().

handler : function

The listener. The first argument is always the event, folowed by any data arguments provided by the trigger.


.off([context], events, [selector], handler)

Unregisters event listneres. The arguments must match the arguments provided on registration using .on() or .one().

Kind: instance method of events
Category: eventhandling
ParamDescription
[context : Element ]

Context Element. If omitted it defaults to the Weavy instance. weavy.connection and wvy.postal may also be used as contexts.

events : string

One or several event names separated by spaces. You may provide any namespaces in the names or use the general namespace parameter instead.

[selector : string ]

Only applicable if the context supports selectors, for instance jQuery.on().

handler : function

The listener. The first argument is always the event, folowed by any data arguments provided by the trigger.


.triggerEvent(name, [data]) ⇒ data

Trigger a custom event. Events are per default triggered on the weavy instance using the weavy namespace.

The trigger has an event chain that adds before: and after: events automatically for all events except when any custom prefix: is specified. This way you may customize the eventchain by specifying before:, on: and after: in your event name to fire them one at the time. The on: prefix will then be removed from the name when the event is fired.

Eventhandlers listening to the event may return modified data that is returned by the trigger event. The data is passed on to the next event in the trigger event chain. If an event handler calls event.stopPropagation() or return false, the event chain will be stopped and the value is returned.

Kind: instance method of events
Returns: data - The data passed to the event trigger including any modifications by event handlers. Returns false if the event is cancelled.
Category: eventhandling
ParamDescription
name : string

The name of the event.

[data : Array/Object/JSON ]

Data may be an array or plain object with data or a JSON encoded string.

Example
// Normal triggering
weavyEvents.triggerEvent("myevent");

// Will trigger the following events on the root instance
// 1. before:myevent.event.weavy
// 2. myevent.event.weavy
// 3. after:myevent.event.weavy
Example
// Custom triggering, one at the time
weavyEvents.triggerEvent("before:myevent");
weavyEvents.triggerEvent("on:myevent");
weavyEvents.triggerEvent("after:myevent");
Example
// Advanced triggering with data handling

function doSomething() {
    // Will trigger the events sequentially and check the response data in between

    var myTriggerData = { counter: 123, label: "my label" };

    // Custom triggering, one at the time

    // 1. Trigger before: and save the response data back to myTriggerData
    myTriggerData = weavyEvents.triggerEvent("before:myevent", myTriggerData);
    
    if (myTriggerData === false) {
        console.warn("before:myevent was cancelled by event.stopPropagation() or return false");
        return;
    }

    // ...

    // 2. Continue with on: and save the response data back to myTriggerData
    myTriggerData = weavyEvents.triggerEvent("on:myevent", myTriggerData);
    
    if (myTriggerData === false) {
        console.warn("on:myevent was cancelled by event.stopPropagation() or return false");
        return;
    }

    // ...

    // 3. At last trigger after: and save the response data back to myTriggerData
    myTriggerData = weavyEvents.triggerEvent("after:myevent", myTriggerData);
    
    if (myTriggerData === false) {
        console.warn("after:myevent was cancelled by event.stopPropagation() or return false");
        return;
    }
    
    console.log("myevent was fully executed", myTriggerData);
    return myTriggerData;
}

Events

"init" ⇒ Promise

Event that is triggered when the weavy instance is initiated. This is done automatically unless you specify init: false in options. You may use the before:init event together with event.stopPropagation() if you want to intercept the initialization.

Kind: event emitted by Weavy
Category: events

"client-data" ⇒ data

Triggered when init data has been loaded from the server.

Kind: event emitted by Weavy
Category: events

"create-root" ⇒ root

Triggered when a shadow root is created

Kind: event emitted by Weavy
Category: events

"frame-check" ⇒ WeavyPromise

Triggered when the frame check is done.

Kind: event emitted by Weavy
Category: events
Resolves: WeavyPromise
Properties
NameDescription
blocked : boolean

Whether iframes communication is blocked or not.


"destroy" ⇒ Object

Event triggered when the Weavy instance is about to be destroyed. Use this event for clean up.

Kind: event emitted by Weavy
Category: events
Properties
NameDescription
whenAllDestroyed : Array

List of promises to wait for before destroy resolves. Add promises to wait for in your event handler.


"badge" ⇒ Object

Triggers when the number of unread conversations or notifications change.

Kind: event emitted by Weavy
Category: events
Properties
NameDescription
conversations : int

Number of unread conversations

notifications : int

Number of unread notifications

total : int

The total number of unread conversations and notifications.

Example
weavy.on("badge", function (e, data) {
    weavy.log("New notifications count", data.notifications);
    weavy.log("Unread conversations count", data.conversations);
});

"build"

Event triggered when weavy is building up the DOM elements.

Use this event to build all your elements and attach them to weavy. At this point you may safely assume that weavy.nodes.container is built.

Good practice is to build all elements in the build event and store them as properties on weavy. Then you can attach them to other Elements in the after:build event. This ensures that all Elements are built before they are attached to each other.

If you have dependencies to Elements built by plugins you should also check that they actually exist before attaching to them.

Often it's a good idea to check if the user is signed-in using WeavyAuthentication#isAuthenticated unless you're building something that doesn't require a signed in user.

Kind: event emitted by Weavy
Category: events
Example
weavy.on("build", function(e, root) {
    if (weavy.authentication.isAuthorized()) {
        weavy.nodes.myElement = document.createElement("DIV");
    }
});

weavy.on("after:build", function(e, root) {
    if (weavy.authentication.isAuthorized()) {
        if (weavy.nodes.overlay) {
            weavy.nodes.overlay.appendChild(weavy.nodes.myElement);
        }
    }
})

"load"

Event triggered when weavy has initialized, connected to the server and recieved and processed options, and built all components. Use this event to do stuff when everything is loaded.

Often it's a good idea to check if the user is signed-in using Weavy#isAuthenticated unless you're building something that doesn't require a signed in user.

Kind: event emitted by Weavy
Category: events
Example
weavy.on("load", function() {
    if (weavy.authentication.isAuthorized()) {
        weavy.alert("Client successfully loaded");
    }
});

Logging

.console : WeavyConsole

Class for wrapping native console logging.

  • Options for turning on/off logging
  • Optional prefix by id with color
Kind: instance property of Weavy
Category: logging

Panels

.panels : WeavyPanels

Instance of the panel manager for all iframes in the weavy instance.

Kind: instance property of Weavy
Category: panels

.nodes : object

Placeholder for all DOM node references. Put any created elements or DOM related objects here.

Kind: instance namespace of Weavy
Category: panels
Properties
NameDescription
container : Element

The main container under the root. This is where all common weavy Elements are placed.

overlay : Element

Container for displaying elements that needs to be full viewport and on top of other elements.


.nodes.panels : object

Placeholder for all panels.

Kind: instance namespace of nodes
Category: panels

.nodes.panels.drawer : container

Side drawer panel container. Slides in/out automatically when a child panel is opened or closed. Attached to Weavy#nodes#overlay.

Kind: instance property of .nodes.panels
Category: panels

.nodes.panels.preview : container

Preview panel container. Attached to Weavy#nodes#overlay.

Kind: instance property of .nodes.panels
Category: panels

Plugins

.plugins : Object.<string, plugin>

All enabled plugins are available in the plugin list. Anything exposed by the plugin is accessible here. You may use this to check if a plugin is enabled and active.

Set plugin options and enable/disable plugins using options.

Kind: instance property of Weavy
Category: plugins
Example
if (weavy.plugins.alert) {
  weavy.plugins.alert.alert("Alert plugin is enabled");
}

Promises

.whenTimeout(time) ⇒ WeavyPromise

Creates a managed timeout promise. Use this instead of window.setTimeout to get a timeout that is automatically managed and unregistered on destroy.

Kind: instance method of Weavy
Category: promises
ParamDefaultDescription
time : int 0

Timeout in milliseconds

Example
var mytimeout = weavy.whenTimeout(200).then(function() { ... });
mytimeout.cancel(); // Cancel the timeout

.whenReady() ⇒ WeavyPromise

Promise that the blocking check has finished. Resolves when frame-check is triggered.

Kind: instance method of Weavy
Category: promises
Resolved: when frames are not blocked.
Rejected: when frames are blocked
Example
weavy.whenReady().then(function() { ... })

.whenInitialized() ⇒ WeavyPromise

Promise that resolves when the initialization has been started

Kind: instance method of Weavy
Category: promises
Resolved: when init event has been fully executed

.whenLoaded() ⇒ WeavyPromise

Promise that weavy has recieved the after:load event

Kind: instance method of Weavy
Category: promises
Resolved: when init is called, the websocket has connected, data is received from the server and weavy is built and the load event has finished.
Example
weavy.whenLoaded().then(function() { ... })

Spaces

.spaces : Array.<WeavySpace>

List of all current defined spaces as an Array.

Kind: instance property of Weavy
Category: spaces

.space(options) ⇒ WeavySpace

Selects, fetches or creates a space in the weavy instance.

The space needs to be defined using a space definition object containing at least a key, which will fetch or create the space on the server. If the defined space already has been set up, the space will only be selected in the client. After the space is defined it can be quickly selected in the client using only the id (int) or the key (string) of the space, which never will create nor fetch the space from the server.

Kind: instance method of Weavy
Category: spaces
See: options
ParamDescription
options : int : string : options

space id, space key or space definition object.

Example
// Define a space that will be fetched or created on the server
var space = weavy.space({ key: "mykey", name: "My Space" });

// Select the newly defined space
var spaceAgain = weavy.space("mykey");

Static members

.version : string

The hardcoded semver version of the weavy-script.

Kind: static property of Weavy

.presets : Object

Option preset configurations. Use these for simple configurations of common options. You may add your own presets also. The presets may be merged with custom options when you create a new Weavy, since the contructor accepts multiple option sets.

Kind: static property of Weavy
Properties
NameDescription
Weavy.presets.noplugins : options

Disable all plugins.

Weavy.presets.core : options

Enable all core plugins only.

Example
// Load the minimal weavy core without any additional plugins.
var weavy = new Weavy(Weavy.presets.core, { url: "https://myweavysite.com" });

.defaults : Object

Default options. These options are general for all Weavy instances and may be overridden in options. You may add any general options you like here. The url is always set to the installation where your weavy.js was generated.

Kind: static property of Weavy
Properties
NameDefaultDescription
[container : Element ]

Container where weavy should be placed. If no Element is provided, a <section> is created next to the <body>-element.

[className : string ]"weavy-default"

Additional classNames added to weavy.

[https : string ]"adaptive"

How to enforce https-links.
force - makes urls https.
adaptive - enforces https if the calling site uses https.
default - makes no change.

[init : boolean ]true

Should weavy initialize automatically.

[includePlugins : boolean ]true

Whether all registered plugins should be enabled by default. If false, then each plugin needs to be enabled in plugin-options.

[preload : boolean ]

Start automatic preloading after load

[shadowMode : boolean ]closed

Set whether ShadowDOMs should be closed (recommended) or open.

url : string

The URL to the Weavy-installation to connect to.

Example
// Defaults
Weavy.defaults = {
    container: null,
    className: "",
    https: "adaptive",
    init: true,
    includePlugins: true,
    preload: true,
    url: "/"
};

// Set a general url to connect all weavy instances to
Weavy.defaults.url = "https://myweavysite.com";
var weavy = new Weavy();

.plugins : Object.<string, plugin>

Placeholder for registering plugins. Plugins must be registered and available here to be accessible and initialized in the Weavy instance. Register any plugins after you have loaded weavy.js and before you create a new Weavy instance.

Kind: static property of Weavy

.instances : Array.<string>

Id list of all created instances.

Kind: static property of Weavy

Inner members

~root : Object

Weavy shadow root to enable closed scopes in the DOM that also can be managed and removed. The shadow root will isolate styles and nodes within the root.

Structure:

{parent} ➜ <weavy/> ➜ {ShadowDOM} ➜ {container}

Kind: inner typedef of Weavy
See: https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM
Properties
NameDescription
parent : Element

The parent DOM node where the root is attached.

section : Element

The <weavy/> node which is the placeholder for the root. Attached to the parent.

root : ShadowDOM

The <weavy-root/> that by default is a closed ShadowDOM node. Attached to the section.

container : Element

The <weavy-container/> where you safely can place elements. Attached to the root.

id : string

The id of the root.

remove() : function

Function to remove the root from the DOM.