Weavy
The core class for the Weavy client.
Kind: global classnew 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.
Param | Description |
---|---|
...options : options
| One or multiple option sets. Options will be merged together in order. |
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 ofWeavy
See: Client Options
Properties
Name | Default | Description |
---|---|---|
[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. |
[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. |
|
[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 |
spaces : Array.<options>
| Array of space definititions with apps to initialize spaces directly at initialization. See space. |
|
[tz : string
] | Timezone identifier, e.g. |
|
[url : string
] | The URL of the Weavy-installation to connect to. Defaults to the installation where the script came from. |
.isBlocked : boolean
.isLoading : boolean
.isLoaded : boolean
.connection : WeavyConnection
Reference to the instance of the realtime connection to the server.
Kind: instance property ofWeavy
.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 ofWeavy
Returns:
string
- Id completed with weavy-id. If no id was provided it returns the weavy-id only. Param | Description |
---|---|
[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 ofWeavy
Returns:
string
- Id without weavy id. Param | Description |
---|---|
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.
Weavy
Emits:
init
Resolved: When the weavy instance is initialized, ready and loaded.
Param | Description |
---|---|
[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 ofWeavy
Emits:
create-root
Param | Description |
---|---|
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 ofWeavy
Param | Description |
---|---|
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 ofWeavy
Param | Default | Description |
---|---|---|
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. |
// 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 ofWeavy
Emits:
destroy
Param | Default | Description |
---|---|---|
[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 ofWeavy
Properties
Name | Description |
---|---|
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 ofWeavy
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 ofWeavy
Category: authentication
"signing-in"
Triggered when the authentication process has started.
Kind: event emitted byWeavy
Category: authentication
"clear-user"
Triggered when user data needs to be cleared. For example when a user is signing out.
Kind: event emitted byWeavy
Category: authentication
"authentication-error" ⇒ Object
Triggered when the authentication process was unsuccessful.
Kind: event emitted byWeavy
Category: authentication
Properties
Name | Description |
---|---|
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.
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.
events
Category: eventhandling
Param | Description |
---|---|
[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. |
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 ofevents
Category: eventhandling
Param | Description |
---|---|
[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 ofevents
Category: eventhandling
Param | Description |
---|---|
[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.
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
Param | Description |
---|---|
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. |
// 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.
Weavy
Category: events
"client-data" ⇒ data
Triggered when init data has been loaded from the server.
Kind: event emitted byWeavy
Category: events
"create-root" ⇒ root
"frame-check" ⇒ WeavyPromise
Triggered when the frame check is done.
Kind: event emitted byWeavy
Category: events
Resolves:
WeavyPromise
Properties
Name | Description |
---|---|
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.
- Any events registered using Weavy#on and Weavy#one will be unregistered automatically.
- Timers using whenTimeout will be cleared automatically.
- All elements under the Weavy#nodes#root will be removed.
Weavy
Category: events
Properties
Name | Description |
---|---|
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 byWeavy
Category: events
Properties
Name | Description |
---|---|
conversations : int
| Number of unread conversations |
notifications : int
| Number of unread notifications |
total : int
| The total number of unread conversations and notifications. |
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 byWeavy
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 byWeavy
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
Weavy
Category: logging
Panels
.panels : WeavyPanels
Instance of the panel manager for all iframes in the weavy instance.
Kind: instance property ofWeavy
Category: panels
.nodes : object
Placeholder for all DOM node references. Put any created elements or DOM related objects here.
Kind: instance namespace ofWeavy
Category: panels
Properties
Name | Description |
---|---|
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
.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 ofWeavy
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 ofWeavy
Category: promises
Param | Default | Description |
---|---|---|
time : int
| 0 | Timeout in milliseconds |
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 ofWeavy
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 ofWeavy
Category: promises
Resolved: when init event has been fully executed
.whenLoaded() ⇒ WeavyPromise
Promise that weavy has recieved the after:load event
Kind: instance method ofWeavy
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>
.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 ofWeavy
Category: spaces
See: options
Param | Description |
---|---|
options : int
: string
: options
| space id, space key or space definition object. |
// 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
.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 ofWeavy
Properties
Name | Description |
---|---|
Weavy.presets.noplugins : options
| Disable all plugins. |
Weavy.presets.core : options
| Enable all core plugins only. |
// 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 ofWeavy
Properties
Name | Default | Description |
---|---|---|
[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. |
[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 |
url : string
| The URL to the Weavy-installation to connect to. |
// 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 ofWeavy
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 ofWeavy
See: https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM
Properties
Name | Description |
---|---|
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. |