Docs

Interface

App window

Every app is contained in a single window called the app window. The app window is divided into two areas: a title bar, and container. The title bar is for app identity and window management, and is rendered by Pokki. The container is loaded from the window page defined in your app’s manifest, and you may consider it a blank canvas entirely defined by you.

Title bar

The title bar is provided to every app by Pokki. It serves two purposes: help the user identify the app, and provide a consistent set of controls to manage the app and it's window. The title bar contains the following:

  • App name - the name of the app. This is determined by the value of the "name" field in the app’s manifest file.
  • Minimize button - when pressed, the app window disappears from view, however the app remains loaded.
  • Close button - when pressed, the app window disappears from view, and the app itself is unloaded.
  • Full-screen button - when pressed, enters full-screen mode. This button is optional, and controlled by the developer at run-time.

In addition to providing this fundamental window and app controls, the title bar itself is the means at which the user can drag the app window around the screen.

Interaction and events

Your app window is shown when the user clicks on your app’s icon in the taskbar. The user can minimize the window to the taskbar by clicking on the app's icon or clicking the minimize button in the window's title bar. The user can also close your app, and it's window, by clicking on the close button in the window's title bar.

The window page may detect these actions by listening for the showing, shown, hiding and hidden events. See Listening for events for more details.


pokki.addEventListener('showing', function() {
  console.log("The app was clicked and it's window is animating in.");
});

pokki.addEventListener('shown', function() {
  console.log("The app window is now shown!");
});

pokki.addEventListener('hidding', function() {
  console.log("The app window is animating out.");
});

pokki.addEventListener('hidden', function() {
  console.log("The app window was minimized.");
});
  

To determine if the app window is currently visible you may use pokki.isShown from the background page or window page.


if (pokki.isShown()) {
  console.log("The app window is shown.");
} else {
  console.log("The app window is not visible on screen.");
}
  

The window can also close itself by callingpokki.hide. We recommend rarely using this, as it leavaes the user in control.

Size and resizing

Your app window’s size is controlled by you and, if you choose, the user.

The size of the app window is defined by the contents of the window page DOM. As the preferred size changes, so does the width and height of your app window. You can effectively prevent the automatic resizing by specifying the size of the window page’s body and setting the overflow to hidden.

You may choose to allow the user to resize your app window. This is set, and may be changed, at runtime usingpokki.allowResize. The user may resize your app window by dragging any edge of the window frame.


pokki.allowResize(allowX, allowY, {
                  minWidth: MinWidth,
                  minHeight: MinHeight,
                  maxWidth: MaxWidth,
                  maxHeight: MaxHeight
});
  

You may specify if the app window may be resized vertically and/or horizontally. You may also specify the minimum and maximum dimensions. Passing a value of 0 means there is no limit.


// no restrictions
pokki.allowResize(true,true);

// no resize on width
pokki.allowResize(false, true, {
  minHeight: 300,
  maxHeight: 800
});

// resize both with constraints on both
pokki.allowResize(true, true, {
  minWidth: 500,
  maxWidth: 1024,
  minHeight: 500,
  maxHeight: 768
});

// resize both, no constraint on width
pokki.allowResize(true, true, {
  minWidth: 0, // not including this param would do the same
  maxWidth: 0, // not including this param would do the same
  minHeight: 200,
  maxHeight: 800
});

// resize both, only minimum constraint
pokki.allowResize(true, true, {
  minWidth: 500,
  maxWidth: 0, // not including this param would do the same
  minHeight: 400,
  maxHeight: 0 // not including this param would do the same
});
  

You can lock the aspect ratio of your app window while the user resizes it by using pokki.setWindowFeature with a string of 'aspect' and a decemial value representing the width divided by the height (eg. 1.5).


pokki.setWindowFeature('aspect', 1.5);
  
Positioning

When your app loads, the app window is positioned front and centre on the user’s primary desktop. The primary desktop is defined by the desktop that includes the taskbar. If the top left of the window’s title bar is not visible, the window is positioned top left of the primary desktop.

You have the option of saving and loading the position and size of your app window at any time. You may store multiple states, each associated with an arbitrary name string. This enables you to maintain various states based on your apps visible states -- e.g. a login screen and main window. To save a state usepokki.saveWindowState, and to load a state usepokki.loadWindowState

If you want to restore your app's state before the app window is shown on load, you may call pokki.loadWindowState while handling the DOMContentLoaded event. If this call is not made, or if there is no state information associated with the specified state, or restoring the state places the app window offscreen (e.g. on a monitor that is no longer connected), the app window defaults to the center of the primary monitor.

Maintaining state

Pokki may unload your app's window page when the app window is closed by the user, or as a result of system shutdown or restart. If maintaining the state of your app window is important for your app then please see Maintaining state.

Badge notifications

badge

Badge notifications are displayed as a number on the top-right of your app’s icon. They are used to communicate that something important has occurred that the user may be interested in, such as receiving new messages.

While Badge methods can be accessed by the popup and background pages, the background page is ideally suited for this task because it is always running.

Set the badge with pokki.setIconBadge

var unread_count = app.get_count_unread();
pokki.setIconBadge(unread_count);%p Clear the badge with pokki.removeIconBadge
  
pokki.removeIconBadge();

Context menu

context menu

The context menu is displayed when a user right-clicks on your app’s icon. In addition to menu items controlled by Pokki, such as removing an app, developers can specify their own custom menu items.

The context menu items you specify can be defined statically in your app’s manifest or dynamically using Pokki APIs during run-time. A menu item is an object that consists of a string displayed to the user, the text property, and a string used to identify the item, the id property. They are displayed in the order they are defined.

Defining menu items in your app’s manifest file


{
  ...
  "menu": [ {"text":"Help...", "id":"help"},
            {"text":"Mark all read", "id":"mark_read"} ]
  ...
}
  

Defining menu items using pokki.addContextMenuItem and pokki.resetContextMenu


// Best practice: clear your app’s context menu when loaded
// to avoid creating duplicate menu items
pokki.resetContextMenu();

// Add items to the context menu
pokki.addContextMenuItem('Help...', 'Help');
pokki.addContextMenuItem('Mark all read', 'mark_read');
  

When a user selects a developer defined menu, Pokki fires a context_menu event with the sole parameter being the id associated with that item. Because the context menu is always available, you should listen for context_menu events from the background page to ensure they are heard.

Upon receiving a context_menu event, your app has special permissions for 5 seconds to call pokki.show to open your app. This is should be used when the context menu item requires displaying additional information to the user, such as configuring options for your app.

Listening for and handling a context_menu event


// Basic
pokki.addEventListener('context_menu', function(id) {
  console.log("Menu item selected! Identifier: " + id);
});

// Using pokki.show()
pokki.addEventListener('context_menu', function(id) {
  if (id == 'help') {
    pokki.show();
    app.display_options();
  }
});
  

Opening the web browser

For many apps there are times when you will want to open a link in the user’s browser. Pokki provides a simple API for accomplishing this.

Opening a URL using pokki.openURLInDefaultBrowser


$('#pokki-logo').click(function(){
  pokki.openURLInDefaultBrowser('http://pokki.com');
});
  

To ensure compatibility with existing web apps, Pokki catches window.location changes and window.open calls and fires the pokki_link event. Below is an example of how to catch and handle this event.


pokki.addEventListener('link', function(url){
  pokki.openURLInDefaultBrowser(url);
});
  

Web sheets

A web sheet is a chromeless browser embedded in the app window that is intended to be used with OAuth and similar protocols for authentication. OAuth is becoming the de-facto standard used by sites like Twitter and Facebook to grant a 3rd party app permission to access a user’s data. Web sheets provide an integrated OAuth experience, negating a user having to open their web browser and then enter a PIN or token back into the app window.

Facebook’s oAuth page loaded in a web sheet within the Facebook app..

The web sheet methods are as follows; see the WebSheet API reference for details.


pokki.showWebSheet(url, width, height, loading_callback, error_callback);
pokki.hideWebSheet();
pokki.clearWebSheetCookies();
  

In addition to displaying external web content, web sheets enable you to extract information from the external URL. For example, OAuth passes back access tokens through a callback URL and query string. With a web sheet you can use a callback function to watch the external URL for changes.

Below is an example of using OAuth in a web sheet to request permission from Facebook to install the FrontierVille Facebook game. The web sheet opens a Facebook authorization URL with a callback URL provided in the query string. Facebook will redirect to the callback URL with an access token in the query string once authorization is granted.

When the URL of the web sheet changes, the loading callback function is called and this blocks the display of the specified URL unless the callback function returns true. In our function we check to see if the URL being loaded matches the callback URL, in which case the access token is extracted from the URL and the web sheet is hidden. Otherwise we allow the new URL to be displayed in the web sheet.

The user can close the web sheet at any time by pressing the close button, which is located just right of the domai label. When this happens the error callback is fired with the error code user_abort. Once the error callback is completed the platform closes the web sheet.


// The URL that will contain the access token
var token_url = 'http://apps.facebook.com/frontierville/tracks.php';

// The initial URL for the WebSheet
var url = 'https://www.facebook.com/login.php?api_key=201278444497&next=' + token_url;

// Display the web sheet
// params: url, width, height, loading_callback, error_callback
pokki.showWebSheet(
  url,
  512,
  400,
  function(_url) {
    if (_url.startsWith(token_url)) {
      // The URL with the access token is being loaded
      // Extract access token from _url and do something with it
      // Close the web sheet
      pokki.hideWebSheet();
    } else {
      // This is not the URL we're looking for
      // allow the page to be shown by returning true
      return true;
    }
  },
  function(error) {
    // Oops, something went wrong!
    if (error == user_abort) {
      // User hit the close button
    } else {
      // Network error (network_error) or General error (general_error)
      // Handle the error
      pokki.hideWebSheet();
    }
  }
);
  

Full-screen

Pokki supports a full-screen mode, through the HTML5 full-screen API . This allows your app or game to enter and exit full-screen programmatically, for an immersive experience.

Getting started with full-screen

There are three easy steps to implementing full-screen:

  1. Let Pokki know your app is capable of full-screen by calling pokki.setWindowFeature with a string of 'fullscreen' and value of true.
  2. Listen to the Pokki event 'fullscreen' and toggle between entering and exiting full-screen. This event is fired as a result of the user pressing the full-screen button in the app window's title bar.
  3. Use the HTML5 full-screen APIs to enter and exit full-screen

pokki.setWindowFeature('fullscreen', true);

pokki.addEventListener('fullscreen', function() {
  var content = document.getElementById('content');
  if (document.webkitIsFullScreen) {
    document.cancelFullScreen();
  } else {
    document.requestFullScreen(c);
  }
});
    
HTML5 Full-screen API

The full-screen API enables you to center any content from the popup page on the user’s display. For example, if you wanted to take a div into full-screen, simply call the WebKit method.


div.webkitRequestFullScreen(Element.ALLOW_KEYBOARD_INPUT);
    

To exit full-screen, call the WebKit document method.


document.webkitCancelFullScreen();
    

You can also style the same content differently while in full-screen. To style content, display or hide specific elements in full-screen the way you want, the CSS full-screen pseudo-selectors make it simple.


div:-webkit-full-screen {
  width: 100% !important;
}
:-webkit-full-screen .tohide {
  display: none; /* While in fullscreen, hide any children with class 'tohide' */
}
    

When implementing full-screen, there are some user experience guidelines we suggest following:

  • Supporting various screen sizes - The JavaScript screen.width or screen.height may be useful in helping determining your full-screen elements’ styling for a responsive app design.
  • Web sheets are disabled in full-screen - Web sheets functionality isn't available when in full-screen mode. Please consider this when determining the best time to allow the user to enter full-screen.