API installation

You will need to use the wesk.js Javascript file that can be found in your Wesk installation directory (under Resources) or downloaded here: download wesk.js. Simply reference this file on your website, exactly as you would do with jQuery for example.

Be Ready

Before using any other Wesk function, please use the ready() function to ensure that Wesk is properly loaded.
Any other call must be made within the callback of that function. For example, when getting information about the current window:
wesk.ready(function(){
    // Make any other call here, for example:
    wesk.get().then(function(currentWindow){
        alert(currentWindow.name);
    });
});
This of course doesn't apply to attributes.

Window Management

Opening a window (Unobtrusive)

Simple really. Just add an attribute to your link. If you have a link like this:
<a href="ticker.html">Ticker</a>
Change it to:
<a href="ticker.html" wesk="My Ticker">Ticker</a>
That's it!

Unobtrusive

The attributes are completely unobtrusive, so if you open your web application from a regular browser, it will still work as it did before.
To specify a size and/or a position, use the following attributes:
<a href="ticker.html" wesk="My Ticker" wesk-width="100" wesk-height="100" wesk-top="10" wesk-left="20">Ticker</a>

HTML5 Compliance

If your code needs to be HTML5 compliant, prefix the wesk attributes with "data-". For example: data-wesk="title", data-wesk-width="1234" and so on.

Opening a window (using Javascript)

To open a window by code, use the following function:
wesk.open('/some/url.html', 'A Title', width, height, left, top);
The arguments are: url, title, width, height, position from left, position from top.

The function also returns a Promise, with some information about the window created (such as id, position, size, etc.):
wesk.open('/some/url.html', 'A Title', width, height, left, top).then(function(windowInfo) {
    // Do something when the window is open (the windowInfo object gives you some information about the window)
});

Closing a window

Adding a link to close the current window couldn't be simpler:
<a href="#" wesk-close>Close</a>
To be HTML5 compliant, you can change that to:
<a href="#" data-wesk-close="">Close</a>
… which is the HTML5 equivalent. If you want to close another window, use the javascript function as follows: When opening a window, the call to wesk.open gives you an Id. You can use this id to close this window:
wesk.close(id);
The close method is promise compliant, which means it returns a promise object, allowing you to interact after the window is closed:
wesk.close(id).then(function(wasClosed){
    alert("The window was properly closed: "+wasClosed);
});
You can also use the getWindows() method (see below) to get all windows to find the Id of the window you want to close.

Getting information on the current window

To get information (position, size, id, etc.) about the current window, use the get function as follows:
wesk.get().then(function(windowInformation) {
    // Do something here with windowInformation
});
This will return a javascript object containing all information about the current window. For example:
{
    "isMain": true, // Only one "Main" window per application. Closing the main window closes all other windows
    "isCurrent": true, // Whether this is the Window on which the get() function was called
    "name": "Wesk Example",
    "url": "http://www.weskapp.com/examples/financial/",
    "id": "d4099f70-901e-43a8-b4c9-d1c10e5db604",
    "width": 1024.0,
    "height": 768.0,
    "top": 50.0,
    "left": 50.0
}

Getting information about a specific window

Use the same method as before, but using the Window ID of the window you want the information for:

wesk.get(id).then(function(windowInformation) {
    // Do something here with windowInformation
});

Getting information about all windows

wesk.getAll().then(function(windowsInformation) {
    // Do something here with windowsInformation
});
This will give you an array of objects containing information about opened windows. Here is an example:
[
    {
        "isMain": true,
        "isCurrent": false,
        "name": "Wesk Example",
        "url": "http://www.weskapp.com/examples/financial/",
        "id": "d4099f70-901e-43a8-b4c9-d1c10e5db604",
        "width": 1024.0,
        "height": 768.0,
        "top": 50.0,
        "left": 50.0
    },
    {
        "isMain": false,
        "isCurrent": true,
        "name": "Communication (receiver)",
        "url": "http://www.weskapp.com/examples/financial/comtwo.html",
        "id": "cab2de63-27a1-4ac0-834d-f4d1690ece8a",
        "width": 500.0,
        "height": 400.0,
        "top": 191.0,
        "left": -697.0
    }
]

Reacting to windows events

If you open, close, move, or resize one of the windows, you can react to it by subscribing to the onWindowEvent event:
wesk.onWindowEvent(function(){
    wesk.getAll().then(function(windows) {
        // do something
    });
});

Size & Position

Moving a Window

To move a window, use the move() method using three parameters: the X and Y positions of the top left corner of the window, and the Window ID:
wesk.move(x, y, id);
You can omit the Window ID when moving the current window:
wesk.move(x, y);
The move() method also returns a promise, with the updated Window Info object:
wesk.move(x, y, id).then(function(windowInfo) {
    // do something with the updated window info here
});

Resizing a Window

To resize a window, use the resize() method using three parameters: the width and height of the window, and the Window ID:
wesk.resize(width, height, id);
You can omit the Window ID when resizing the current window:
wesk.resize(width, height);
The resize() method also returns a Promise, with the updated Window Info object:
wesk.resize(width, height, id).then(function(windowInfo) {
    // do something with the updated window info here
});

Maximizing a Window

Calling maximize() will maximize a window if the window is not currently maximized (either minimized, or just not maximized).
If the window is already maximized, maximize() will simply un-maximize it.
wesk.maximize(id);
You can omit the Window ID when maximizing the current window:
wesk.maximize();
The maximize() method also returns a promise, with the updated Window Info object:
wesk.maximize(id).then(function(windowInfo) {
    // do something with the updated window info here
});

Minimizing a Window

Calling minimize() will minimize a window if the window is not currently minimized (either maximized, or just not minimized).
If the window is already minimized, minimize() will simply un-minimize it.
wesk.minimize(id);
You can omit the Window ID when minimizing the current window:
wesk.minimize();
The minimize() method also returns a Promise, with the updated Window Info object:
wesk.minimize(id).then(function(windowInfo) {
    // do something with the updated window info here
});

Screens

Get information about your current screen layout, including support for multi-monitor configurations.
wesk.screens().then(function(screens) {
    // do something with the screens array information here
});
The data returned by this method looks like this:
[
  {
    "isPrimary": false, // Whether this is the primary monitor
    "bitsPerPixel": 32,
    "name": "Display 1", // System name of the monitor
    "bounds": { // Coordinates of the monitor, including the Task Bar
      "x": 1680,
      "y": 0,
      "width": 1680,
      "height": 1050
    },
    "workingArea": { // Coordinates of the monitor, excluding the Task Bar
      "x": 1680,
      "y": 0,
      "width": 1680,
      "height": 1010
    }
  },
  {
    "isPrimary": true,
    "bitsPerPixel": 32,
    "name": "Display 2",
    "bounds": {
      "x": 0,
      "y": 0,
      "width": 1680,
      "height": 1050
    },
    "workingArea": {
      "x": 0,
      "y": 0,
      "width": 1680,
      "height": 1010
    }
  }
]

What can I use this information for?

Having the coordinates of your various screens will allow you to position your windows exactly where you want them, calculating a position at the centre of the screen for example.


Inter-window communication

A message sent by one page can be received by any other page that subscribes to the relevant topic. This allows for a very fine grained communication bus across your windows. To send a message:
wesk.coms.publish('myTopic', 'My Message');
On a different page (which will open in a different window), subscribe to the message by doing the following:
wesk.coms.on('myTopic', function(message){
    alert(message);
});

Notifications

Display desktop notifications with a title and a message body. The code is self explanatory:
wesk.notify('my title', 'my message').then(function() {
    // Do something when the notification is displayed (optional)
});

Binding

When using Wesk attributes (such as wesk-width, wesk-close, etc.), Wesk automatically binds them behind the scenes to event listeners, making sure that a link with the wesk="mypage.html" attribute will open mypage.html when clicked.
Most of the time, this is done automatically when the page is loaded.
In some instances, such as when using templates and partials (for example in AngularJS, when you use ng-include), part of the page is loaded asynchronously via Javascript, which happens after the page is loaded. In this case, Wesk has no way of knowing when this is done.
To prevent this from happening, make sure you call the following after your asynchronous content is loaded:
wesk.ready(function(){ // Wesk might not be loaded yet
    wesk.bind();
});
In AngularJS, this can be done in the controller (which is loaded after the template), or by using the on-load directive on the ng-include element: (this is taken from the Financial App example)
<div data-ng-include="'menu.template.html'" onload="wesk.bind()"><div>
Again, this is nothing to worry about – it only happens when using asynchronous templates.