Docs

Getting Started

What is Pokki!?

Pokki is an application platform for creating desktop applications using HTML5, CSS3 and JavaScript. Pokki is built upon Chromium for secure sandboxing, WebKit for HTML5 layout and rendering, and the V8 for virtual machine for JavaScript. This provides a foundation for the latest HTML5 features. If you are a front-end web developer, you are also a Pokki developer!

Beyond the standard HTML5 features you are accustomed to, Pokki gives you a set special JavaScript APIs and events, a window for your application, and an invisible background window for notifications called a background page.

Pokki also takes care of all the “desktop” stuff you don’t want to think about, like installers and auto-update, so you can focus purely on application development.

How do I get started?

  1. Download and install Pokki (it includes a development environment)
  2. Find the Pokki folder in your start menu and select ‘Toggle Dev Tools’
  3. Follow the tutorial below

Pokki Hello World

In an effort to kick-start your Pokki app development, and to promote good Pokki programming standards, we’ve prepared a bare bones Pokki called the Pokki Atom. You can download the Pokki Atom from GitHub You can use it as a starting point to understand the structure of a Pokki app. It includes libraries for your reference but you can use any libraries or frameworks you prefer.

It starts with a Manifest

Technically speaking, a Pokki app is simply a collection of files (html/css/js/images) contained within a directory. In order for Pokki to understand how to interact with this folder it looks for a file in the root directory called manifest.json. This is a simple JSON file that tells Pokki everything it needs to know about your app.

manifest.json from PokkiAtom:


{
   "name": "Pokki Atom",
   "version": "2.0",
   "icons": { "19":  "img/icon-19x19.png",
              "29":  "img/icon-29x29.png",
              "42":  "img/icon-42x42.png",
              "256": "img/icon-256x256.png" },
   "description": "A basic foundation from which to build a Pokki.",
   "window": "window.html",
   "background": "background.html"
}
  

As you can see each Pokki requires:

  1. name - the name of your app for development (when you upload a Pokki you choose its official name)
  2. version - the version of your app for development (when you upload a Pokki we automatically version it)
  3. icons - each Pokki requires three icons (19x19, 29x29, 42x42); these should be fully opaque and square PNGs
  4. description - a simple description of your Pokki
  5. window - HTML page that's loaded and displayed when a user clicks on your app’s icon
  6. background - HTML page that's always-on; it has no UI and is used for controlling things like notifications (not covered in this guide)

Beyond these required parameters, the manifest can also define other things such as context menu items. It can also store sensitive data like API keys which end up becoming obfuscated when distributed. We'll save those for a different guide.

Add the Pokki Atom

add a pokki

Now that you understand the manifest, let's add the Pokki Atom and see what happens.

  1. Find the Pokki icon in your system tray and right-click on it
  2. Choose "Add Pokki..." and browse to the PokkiAtom directory on your hard drive
  3. Press OK
pokki added

Voila! The Pokki Atom was added! Click on the Pokki Atom icon and give it a go. You should see a very cool splash screen followed by some good old Lorem ipsum.

Under the hood

window.html

Let's first take a look at window.html which is the page that's loaded when a user clicks on the app.

<!doctype html>
<html>
  <head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8" />
    <!-- CSS reset -->
    <link rel="stylesheet" href="css/html5reset-1.6.1.css" type="text/css" />
    <!-- Window styling -->
    <link rel="stylesheet" href="css/default.css" type="text/css" />
    <link rel="stylesheet" href="css/animation.css" type="text/css" />
    <!-- PokkiBrowser for testing in a normal chrome web browser -->
    <script type="text/javascript" src="js/lib/PokkiBrowser.js"></script>
    <!-- SmoothScroll for smooth scroll scrollbars (it's really smooth!) -->
    <script type="text/javascript" src="js/lib/SmoothScroll.js"></script>
    <!-- Google Analytics for Pokki wrapper -->
    <script type="text/javascript" src="js/lib/GAPokki.js"></script>
    <!-- Utility class for localStorage interaction -->
    <script type="text/javascript" src="js/lib/LocalStore.js"></script>
    <!-- Application files -->
    <script type="text/javascript" src="js/app.js"></script>
    <!-- Window logic -->
    <script type="text/javascript" src="js/window.js"></script>
  </head>
  <body>
        <div id="wrapper">
            <div id="content">

                <h1>Pokki Atom</h1>
                <div class="scrollable">
                    <div class="content">
                        <h2>Content goes here...</h2>
                        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
                    </div>
                </div>
            </div>
        </div>

        <div id="splash"></div>
        <div id="atom"></div>

        <script type="text/javascript">
            //GOOGLE ANALYTICS: Enter your settings here
            ga_pokki._setAccount('UA-22567862-1');
            ga_pokki._setDomain('googleanalytics.pokki.com');
        </script>
  </body>
</html>

  

As you can see this file is a straightforward HTML5 document. It loads some JavaScript, CSS and sets up the 

s required for the splash and content. Feel free to look at everything included but the two scripts we'll focus on are window.js and app.js.

js/window.js

window.js is important because it sets all of our event handlers, including Pokki specific event handlers.

// Global variable for our core app
var Atom = false;

// Add listener for when the window is first loaded
// Perform window page initiation and configuration
// NOTE: DOMContentLoaded is the ideal event to listen for as it doesn't
// wait for external resources (like images) to be loaded
function load() {
    console.log('Window page is loaded.');
    Atom = new App();
}
window.addEventListener('DOMContentLoaded', load, false);

// Add listener for when the page is unloaded by the platform
// This occurs due to inactivity or memory usage
// You have 4 seconds from this event to save/store any data
function unload() {
  console.log('App is being unloaded.');
  // Time to save any state
  if (Atom) {
      Atom.onUnload();
  }
}
pokki.addEventListener('unload', unload);

// Add listener for when the app is showing
function showing() {
  console.log('App is almost visible.');
  if (Atom){
      Atom.onShowing();
  }
}
pokki.addEventListener('showing', showing);

// Add listener for when the app is shown
function shown() {
  console.log('App is visible.');
  if (Atom) {
      Atom.onShown();
  }
}
pokki.addEventListener('shown', shown);

// Add listener for when the app is hidden
function hidden() {
    console.log('App was hidden.');
    if (Atom) {
        Atom.onHidden();
    }
}
pokki.addEventListener('hidden', hidden);

  

js/app.js

app.js contains the basic framework for our application and has been left intentionally bare - this is where your app logic would go.

var App = function() {
  var unloaded = new LocalStore('unloaded');
  var splash_ran = unloaded.get() ? true : false;

  // Initialize whatever else needs to be initialized




  // Kick off what needs to be done whenever the app is about to be shown
  this.onShowing = function() {

  };

  // Kick off what needs to be done when the app is shown
  this.onShown = function() {
      // splash elements
      var splash = document.getElementById('splash');
      var atom = document.getElementById('atom');
      var wrapper = document.getElementById('wrapper');

      // animate splash on first run
      if(!splash_ran) {
          splash.classList.add('animate');
          atom.classList.add('animate');
          wrapper.classList.remove('show');

          // allows the css animation to run for some time before removing the animation class
          setTimeout(function() {
              splash.classList.remove('animate');
              atom.classList.remove('animate');
              wrapper.classList.add('show');

              // stagger content animation
              var p = wrapper.getElementsByTagName('p');
              for(var i = 0; i < p.length; i++) {
                  p[i].style['-webkit-animation-duration'] = (100 * i + 300) + 'ms, 300ms';
                  p[i].style['-webkit-animation-delay'] = '0ms,'+ (100 * i + 300) + 'ms';
              }
          }, 2200);

          splash_ran = true;
      }
      else if(unloaded.get()) {
          splash.classList.remove('animate');
          atom.classList.remove('animate');
          wrapper.classList.add('show');
      }
      unloaded.remove();
  };

  // Kick off what needs to be done when the app is hidden
  this.onHidden = function() {

  };

  // Use this to store anything needed to restore state when the user opens the app again
  this.onAppUnload = function() {
      unloaded.set(true);
  };
    };
  

Understanding Pokki Events

pokki.addEventListener allows you to listen for specific Pokki events, some of which are listed below for your convenience:

  • showing - Fires when the user clicks on the app's icon in the taskbar and the window animates in
  • shown - Fires after the showing event once the window is done animating in
  • hiding - Fires as the app hides due to a user action, pokki.hide being called or the platform exiting
  • hidden - Fires after the hiding event once the window is hidden.
  • context_menu - Fires when the user selects a developer defined item in the context menu

You'll note there is no special Pokki or window load event. On load you should listen for standard loading events. We recommend listening for the DOMContentLoaded event as it does not wait for external resources such as images to load.

Let development begin!

Now that you have a sense for the contents of the Pokki Atom, start having some fun and making some changes! Simply edit any file, save it, then click the close button on the Pokki’s window and click on its icon. When the Pokki opens it will load your modified files. That's it! You're now a Pokki developer.

To get a more in-depth of understanding of Pokki please read the Overview.