API Waterworld Example

Sample Toolbar/API Implementation - Waterworld

Table of Contents
  Introduction
  Part 1.  Basic Toolbar XML
  Part 2.  A simple button: Clam Counter
  Part 3.  Authentication: Logging in & out
  Part 4.  A more advanced button: Items
  Part 5.  Final Toolbar XML Layout

Introduction
Back to Top

This tutorial will take you through the entire process of implementing a toolbar that interfaces with the FreeCause API.

The sample implementation is called "Waterworld". Waterworld founder and CEO Kit Covenners wants a toolbar that players can use to check their character's bank balance and inventory from the browser.

Since Kit is very familiar with PHP5 that is what he will code the scripts in, but almost any codebase can be used.

Part 1.  Basic Toolbar XML
Back to Top

First let's define a skeleton XML template for the Waterworld toolbar.  The custom attributes added for Waterworld are framed in purple .

<xml xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

<toolbar 
     accesskey="F" 
     class="chromeclass-toolbar" 
     context="toolbar-context-menu" 
     height="30" 
     id="FCTB-Toolbar" 
     persist="hidden"
     toolbarname="Waterworld Game Toolbar">

     <toolbaritem cid="1396" collapsed="false" component="logo" static="true">

         <toolbarbutton image="http://dev.freecause.com/api/waterworld/waterworld.png" 
                                      label="" oncommand="" 
                                      preview_text="Waterworld Logo" type="menu">

              <menupopup menugenerated="true">

                   <menuitem label="Layout Manager" oncommand="FC_Toolbar.OpenOptions();event.stopPropagation();"/>      
                   <menuitem label="Help" oncommand="FC_Toolbar.LoadURL(FCTB_HelpURL);event.stopPropagation();"/>
                   <menuitem label="Feedback" oncommand="FC_Toolbar.LoadURL(FCTB_FeedbackURL);event.stopPropagation();"/>
                   <menuitem label="Clear Search History" oncommand="FCTB_SearchBox.clearHistory();event.stopPropagation();"/>
              </menupopup>

         </toolbarbutton>

     </toolbaritem>

     <toolbaritem cid="1397" collapsed="false" component="search" static="true">

       <fctb_search cid="MultiSearch" 
                default_image="http://dev.freecause.com/demos/MIT/search.png" 
                default_label=" Search the Web"                                 
                default_url="http://search.yahoo.com/search?type=100&fr=freecause&ei=utf-8&p=" width="250">

                <fctb_customsearch 
                      image="http://dev.freecause.com/demos/MIT/search.png" 
                      label=" Wikipedia"                 
                      url="http://en.wikipedia.org/wiki/Special:Search?go=Go&search=" width="200"/>

       </fctb_search>

     </toolbaritem>

</toolbar>

</xml>

Here's what the toolbar looks like based on the XML above. Very basic - a blank template.

Part 2. A simple button: Clam Counter
Back to Top

Next let's do the implementation of the "clam counter" which will be the button on the toolbar that tells the player how many clams their character has. Clams are the dominant currency in Waterworld.

We name this file clams.php on our server.

Later on, we will add one line of code to the core toolbar XML in order to include this button on the toolbar:

<toolbaritem component="include" url="http://dev.freecause.com/api/waterworld/clams.php?%api_auth"/>

Don't worry about the specifics for now. The only important part is the %api_auth at the end of the URL. This tells the toolbar to append the authentication variables to the end of the URL before it is called.

If the toolbar is authenticated (the user has successfully logged in) then these 3 variables are appended:

user_name
session_key
session_id

Functionally the toolbar converts %api_auth into user_name=[value]&session_key=[value]&session_id=[value] .

The actual URL request becomes (in the case above):

http://dev.freecause.com/api/waterworld/clams.php?user_name=[value]&session_key=[value]&session_id=[value]

If the toolbar is NOT authenticated then the toolbar erases %api_auth and the request would be:

http://dev.freecause.com/api/waterworld/clams.php?

By detecting whether or not these variables are appended, server-side scripts can determine whether or not the user is logged in. Most scripts/toolbar components will have (at least) two states: an authenticated state and a non-authenticated state. When the user is not authenticated, you could make the component invisible or display non-character-specific information.

Check out how we do this for the Clam Counter:

file: clams.php

<?php header('Content-type: text/xml'); ?>
<xml xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

<?php

include_once 'validate.php';

 // Note that validate.php contains abstracted functions like validate_user() and fetch_user_clams().
 // You will have your own abstractions, functions, and data structures; these are just used as illustrative examples.

$user_id     = $HTTP_GET_VARS['user_id'];
$session_key = $HTTP_GET_VARS['session_key'];

if( validate_user($user_id,$session_key) ) {

  // validate_user() checks to make sure the session_key is valid for the user. 
  // If it is, find out how many clams they have.

  $clams = fetch_user_clams($user_id);

}
else {

  // The user has failed validation either due to an invalid session_key or some other reason.
  // In this case we want the toolbar to display "? Clams".

  $clams = "?";

}

?>

 // Now let's output the XML that the toolbar will render into a button.  Since we want the component to appear 
 // substantially the same whether the user is authenticated or not (with either a "?" or the # of clams), we 
 // can use the same XML and substitute the variable $clams in where needed.


<toolbaritem component="button" collapsed="false" expire="3600">
 <toolbarbutton type="button" label="<? echo "$clams"; ?> clams" image="" preview_text="Clams">
 </toolbarbutton>
</toolbaritem>

</xml>

Great, we're done. We reload our toolbar and see this:

Since the user is not authenticated (we haven't covered how to do that yet!) the clams.php script returns "? clams" and this is what the toolbar displays. Next we will learn how to let the user log in to display character-specific information.

Part 3. Authentication: Logging in & out
Back to Top

file: login.php

<?php

echo "<html>";
echo "<title>Waterworld Toolbar</title>";
echo "<body background='http://dev.freecause.com/API/waterworld/login_background.png'>";

$session_key = $HTTP_GET_VARS['session_key'];
$user_name   = $HTTP_GET_VARS['user_name'];

if($session_key) {

  // If $session_key exists it means the toolbar/user is already authenticated.

  echo "You're already logged in, fool!";

}
elseif(!$user_name) {

  // No session key, no user name; this is a new request.  Display a pop-up window: the "log in" screen.

echo <<<EOH


<FORM METHOD='GET' ACTION='http://dev.freecause.com/API/waterworld/login.php'>

Welcome to Waterworld.<BR>

<TABLE CELLPADDING='4' CELLSPACING='4'>
 <TR>
  <TD COLSPAN='2'>Login:</TD>

 </TR>
 <TR>
  <TD>Username:</TD>
  <TD><INPUT TYPE='text' SIZE='20' NAME='user_name'></TD>
 </TR>

 <TR>
  <TD>Password:</TD>
  <TD><INPUT TYPE='text' SIZE='20' NAME='password'></TD>
 </TR>
 <TR>

  <TD COLSPAN='2'><INPUT TYPE='submit' VALUE='LOGIN!></TD>
 </TR>
</TABLE>
</FORM>

EOH;

}
elseif($user_name && $HTTP_GET_VARS['password'] != 'boston') {

  // Hard coded the password here for convenience.

  echo "Incorrect Password.  Please try again.";

}
else {

  // New user has been validated.  New session starting.  Set the session_key and session_id.
  // These are our own abstracted functions.  You will have your own that interact with your database.

  $session_key = set_session_key($user_name);
  $session_id   = set_session_id($user_name);

  // Now we return the Javascript that tells the toolbar the user is authenticated.
  // Every time the toolbar loads a page (any page) it calls OptionsInit().
  // We need to call Authenticate() ourselves and below I choose to do this in the body->onload tag.

  echo <<<EOH
    

<SCRIPT type="text/javascript">

    var toolbar;

  function ToolBarInit(tool) {
    toolbar = tool;
  }

  function Authenticate() {
    toolbar.Options.Authenticated("$user_name", "$session_key", "$session_id");
  }

</SCRIPT>
<BODY onload="Authenticate();">

    Thanks for logging in, $user_name!

</BODY>

EOH;

}

?>

Now we have to add a link to login.php on the toolbar. The added code is highlighted in purple below. We also added another link to a logout script that we will write later on (don't worry about it for now). Also notice that the code for the clam counter button has been loaded (highlighted in yellow).

<toolbaritem cid="1396" collapsed="false" component="logo" static="true">

 <toolbarbutton 
     image="http://dev.freecause.com/api/waterworld/waterworld.png" 
     label="" 
     oncommand="" 
     preview_text="Waterworld Toolbar" 
     type="menu">

     <menupopup menugenerated="true">

        <menuitem
                image="" 
                label="Login to Waterworld Toolbar" 
                oncommand="FC_Toolbar.LoadURL('http://dev.freecause.com/api/waterworld/login.php?%api_auth', 'apipopup', 'height=311,width=375')"/>

        <menuitem  
                image="" 
                label="Logout of Waterworld Toolbar"  
                oncommand="FC_Toolbar.LoadURL('http://dev.freecause.com/api/waterworld/logout.php?%api_auth', 'apipopup', 'height=311,width=375')"/>

       <menuseparator></menuseparator>

        <menuitem label="Layout Manager" oncommand="FC_Toolbar.OpenOptions();event.stopPropagation();"/>      
        <menuitem label="Help" oncommand="FC_Toolbar.LoadURL(FCTB_HelpURL);event.stopPropagation();"/>

        <menuitem label="Feedback" oncommand="FC_Toolbar.LoadURL(FCTB_FeedbackURL);event.stopPropagation();"/>
        <menuitem label="Clear Search History" oncommand="FCTB_SearchBox.clearHistory();event.stopPropagation();"/>

      </menupopup>

 </toolbarbutton>

</toolbaritem>

... [ more XML here ] ...

<toolbaritem component="include" url="http://dev.freecause.com/api/waterworld/clams.php?%api_auth"/>

Now the toolbar looks like this:

I proceed to login:

Upon successful authentication, every include component on the toolbar is automatically reloaded.

http://dev.freecause.com/api/waterworld/clams.php?%api_auth

is turned into

http://dev.freecause.com/api/waterworld/clams.php?user_name=[value]&session_key=[value]&session_id=[value]

and now clams.php can return the player's specific information (clam count). As soon as the player hits "login", the toolbar changes to:

Great job! Here's the logout script. It should be pretty self-explanatory: it checks to see whether you are logged in, and if you are, it sends back Javascript to log you out. If you aren't logged in to begin with, it tells you that.

file: logout.php

<?php

if($_GET['session_key']) {

echo <<<EOH
<html>
<SCRIPT> 

var Options;

function OptionsInit(opts)
{
  Options = opts;
  Options.Authenticated("","","");
}


</SCRIPT>

<body>
<h1> logged out </h1>
</body>
</html>
EOH;

}
else {

echo <<<EOH
<html>

You aren't logged in, fool!
</html>
EOH;

}
?>

Now (after I'm logged in) I click "logout" on the toolbar and see:

And immediately the toolbar changes back to:

And that's it!

Part 4. A more advanced button: Items
Back to Top

file: items.php

<?php header('Content-type: text/xml'); ?>
<xml xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

<?php

include_once 'validate.php';

$external_path = 'http://dev.freecause.com/api/waterworld';
$user_id = $HTTP_GET_VARS['user_id'];
$session_key = $HTTP_GET_VARS['session_key'];

if( validate_user($user_id,$session_key) ) {

 // Items would normally be pulled from a database.
 // They are hard-coded below to serve as a better example of how to format the XML.

echo <<<XML

<toolbaritem>
 <toolbarbutton type="menu" label="My Items " preview_text=" Items" image="$external_path/items_on.gif">

  <menupopup>
   <menuitem label="Pirate Ship" />
   <menuitem label="Box of Sand" />
   <menuitem label="Water Purifier" />
   <menuitem label="200 SPF Sunscreen" />
  </menupopup>

 </toolbarbutton>
</toolbaritem>

XML;

}
else {

echo <<<XML

<toolbaritem>
 <toolbarbutton type="menu" label="My Items " preview_text=" Items" image="$external_path/items_off.gif">
  <menupopup>
   <menuitem 
    label="Log in to Activate" 
    oncommand="FC_Toolbar.LoadURL('http://dev.freecause.com/api/waterworld/login.php?%api_auth', 'apipopup', 'height=311,width=375')" />

  </menupopup>
 </toolbarbutton>
</toolbaritem>

XML;

}

?>

</xml>

Logged out:

Logged in:

Part 5. Final Toolbar XML Layout:
Back to Top

<xml xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

<toolbar 
     accesskey="F" 
     class="chromeclass-toolbar" 
     context="toolbar-context-menu" 
     height="30" 
     id="FCTB-Toolbar" 
     persist="hidden"
     toolbarname="Waterworld Game Toolbar">

     <toolbaritem cid="1396" collapsed="false" component="logo" static="true">

         <toolbarbutton image="http://dev.freecause.com/api/waterworld/waterworld.png" 
                                      label="" oncommand="" 
                                      preview_text="Waterworld Logo" type="menu">

              <menupopup menugenerated="true">

                   <menuitem 
                       image="" 
                       label="Login to Waterworld Toolbar" 
                       oncommand="FC_Toolbar.LoadURL('http://dev.freecause.com/api/waterworld/login.php?%api_auth', 'apipopup', 'height=311,width=375')"/>

                   <menuitem
                       image="" 
                       label="Logout of Waterworld Toolbar" 
                       oncommand="FC_Toolbar.LoadURL('http://dev.freecause.com/api/waterworld/logout.php?%api_auth', 'apipopup', 'height=311,width=375')"/>

                   <menuseparator> </menuseparator>

                   <menuitem label="Layout Manager" oncommand="FC_Toolbar.OpenOptions();event.stopPropagation();"/>      
                   <menuitem label="Help" oncommand="FC_Toolbar.LoadURL(FCTB_HelpURL);event.stopPropagation();"/>
                   <menuitem label="Feedback" oncommand="FC_Toolbar.LoadURL(FCTB_FeedbackURL);event.stopPropagation();"/>
                   <menuitem label="Clear Search History" oncommand="FCTB_SearchBox.clearHistory();event.stopPropagation();"/>

              </menupopup>

         </toolbarbutton>

     </toolbaritem>

     <toolbaritem cid="1397" collapsed="false" component="search" static="true">

       <fctb_search cid="MultiSearch" 
                default_image="http://dev.freecause.com/demos/MIT/search.png" 
                default_label=" Search the Web"                                 
                default_url="http://search.yahoo.com/search?type=100&fr=freecause&ei=utf-8&p=" width="250">

                <fctb_customsearch 
                      image="http://dev.freecause.com/demos/MIT/search.png" 
                      label=" Wikipedia"                 
                      url="http://en.wikipedia.org/wiki/Special:Search?go=Go&search=" width="200"/>

       </fctb_search>

     </toolbaritem>
   
     <toolbaritem component="include" url="http://dev.freecause.com/api/waterworld/clams.php?%api_auth"/>

     <toolbaritem component="include" url="http://dev.freecause.com/api/waterworld/items.php?%api_auth"/>

</toolbar>

</xml>