Understanding the Pokki Atom - blakemachado/Pokki GitHub Wiki

This guide's goal is to quickly walk you through the Pokki Atom to get you familiar with the basic Pokki development process.

Before we begin:

  1. You should have an understanding of front-end web development (HTML5/CSS3/Javascript)
  2. Make sure you've downloaded and installed the [Pokki SDK] (http://www.pokki.com/r/?get-sdk)
  3. Grab the latest Pokki Atom (pokkies/PokkiAtom) from our Git repo and save it somewhere on your hard drive

It starts with a Manifest

Technically speaking, a Pokki is simply a collection of files (html/css/js/images) contained within a directory. In order for the platform 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 the platform everything it needs to know about your Pokki.

manifest.json from PokkiAtom:

{
    "name": "Pokki Atom",
    "version": "1.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:

  • name - the name of your Pokki for development (when you upload a Pokki you choose its official name)
  • version - the version of your Pokki for development (when you upload a Pokki we automatically version it)
  • icons - each Pokki requires four icons (19x19, 29x29, 42x42, 256x256); these should be fully opaque PNGs
  • description - a simple description of your Pokki
  • window - HTML page that's loaded and displayed when a user clicks on your Pokki
  • 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 scrambled when distributed. We'll save those for a different guide.

Add the Pokki Atom

Dev Tools Menu

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 Atom 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

popup.html

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

<!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" />
    <!-- Loading pop-up styling -->
    <link rel="stylesheet" href="css/default.css" type="text/css" />
    <link rel="stylesheet" href="css/animation.css" type="text/css" />
    <!-- Loading SmoothScroll to make the scrollbars scroll more smoothly (it's really smooth!) -->
    <script type="text/javascript" src="js/lib/SmoothScroll.js"></script>
    <!-- Loading Google Analytics for Pokki wrapper -->
    <script type="text/javascript" src="js/lib/GAPokki.js"></script>
    <!-- Loading utility class for localStorage interaction -->
    <script type="text/javascript" src="js/lib/LocalStore.js"></script>
    <!-- Loading application files -->
    <script type="text/javascript" src="js/app.js"></script>
    <!-- Loading pop-up logic -->
    <script type="text/javascript" src="js/popup.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. Duis aliquet nunc non leo vulputate sed sollicitudin diam elementum. Ut et tristique lorem. Ut vitae mi quis lectus mattis lobortis. Fusce accumsan sagittis orci vel venenatis. Phasellus venenatis justo consectetur nibh vulputate elementum. Aliquam vehicula vulputate faucibus. Cras convallis tempus sapien. Etiam venenatis lectus et lorem mattis porta ut ac lectus. Nulla facilisi. Pellentesque commodo nisl at elit rhoncus nec consequat erat sagittis. Proin sit amet augue nec risus euismod pulvinar.</p>
                        <p>Maecenas consequat, felis ac rutrum euismod, nulla felis tincidunt augue, vel tempor nisi diam eget lectus. Maecenas et ligula a nisl blandit eleifend. Vivamus et quam laoreet dui congue sollicitudin ac sit amet sapien. Quisque ipsum libero, semper vitae luctus at, fermentum eget massa. Vivamus sed imperdiet augue. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Sed lacinia, metus et ultrices pharetra, ipsum elit aliquam dolor, sed dignissim nibh mauris quis ligula. Integer ut mi ut risus accumsan dictum. Suspendisse eget nulla id diam laoreet ultrices. Donec at eros odio, in vulputate erat. Morbi sed augue id massa varius molestie sit amet tincidunt enim.</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 <div>s required for the splash and content. Feel free to look at everything included but the two scripts we'll focus on are popup.js and app.js.

js/popup.js

popup.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 popup is first loaded
// Perform popup 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('Popup 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('Popup page is being unloaded.');
	// Time to save any state
	if (Atom) {
		Atom.onPopupUnload();
	}
}
pokki.addEventListener('unload', unload);

// Add listener for when the popup window is showing
function showing() {
    console.log('Popup window is almost visible.');    
    if (Atom){
    	Atom.onPopupShowing();
    }
}
pokki.addEventListener('showing', showing);

// Add listener for when the popup window is shown
function shown() {
    console.log('Popup window is visible.');
    if (Atom) {
    	Atom.onPopupShown();
    }
}
pokki.addEventListener('shown', shown);

// Add listener for when the pop-up window is hidden
function hidden() {
    console.log('Popup window was hidden.');
    if (Atom) {
    	Atom.onPopupHidden();
    }
}
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 Pokki app logic should 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 popup is about to be shown
    this.onPopupShowing = function() {    
    
    };
    
    // Kick off what needs to be done when the popup is shown
    this.onPopupShown = 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 popup is hidden
    this.onPopupHidden = function() {
    
    };
    
    // Use this to store anything needed to restore state when the user opens the Pokki again
    this.onPopupUnload = function() {
        unloaded.set(true);
    };
};

Understanding Pokki Events

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

  • showing - Fires when the user clicks on the Pokki's icon in the taskbar and the popup animates in
  • shown - Fires after the showing event once the popup window is done animating in
  • hiding - Fires as the popup hides due to a user action, pokki.hide being called or the platform exiting
  • hidden - Fires after hiding once the popup window is hidden.
  • unload - Fires when the popup page is being unloaded by the platform; you have four seconds to save state
  • context_menu - Fires when the user selects a developer defined item in the context menu; passes the identifier associated with that menu item

You'll note there is no special Pokki or popup load event. On load you should listen for standard loading events. We recommend listening for the DOMContentLoaded event which fires before window.load as it does not wait 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 right-click on the Pokki Atom icon and select Relaunch. When the Pokki relaunches it will load your modified files. That's it! You're now a Pokki developer.

If you run into trouble, don't worry, Pokki comes in with built-in developer tools! Simply right-click on the Pokki icon and choose Development -> [popup or background] -> Show Developer Tools. Because Pokki is based on Chromium these developer tools are essentially the same as those found in Chrome which you can read about [here] (http://code.google.com/chrome/devtools/docs/overview.html).

Happy Pokki development! We look forward to your creations.

Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️