The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
<!DOCTYPE html>
<html>
<!-- TODO: rewrite this with templates and new info -->
  <head>
    <title>Yote</title>
    <script src="/yote/js"></script>

    <script src="/js/main.js"></script>

    <link href="/yote.css" rel="stylesheet" type="text/css" media="all" />
    <link href="/css/main.css" rel="stylesheet" type="text/css" media="all" />

    <META NAME="Author" CONTENT="Eric Wolf, coyocanid@gmail.com">

    <script>
    $().ready(function(){
	
	make_menus( '#top_nav' );

	$.yote.init();
    });
    </script>
  </head>

  <BODY>

    <DIV class="header">
	<img src="yotelogo.png">
	<UL id="top_nav" class="nav"/>
    </DIV>

    <SECTION>
      <DIV class="page-header">
	<H1>Documentation</H1>
      </DIV>

      <P>
	This documentation describes how Yote programs are written, and what idioms are used.
      </P>

      <SECTION>
	<DIV class="page-header">
	  <h2>Client Side</h2>
	</DIV>
	<h2>Getting Started</h2>
	  <h3>Includes</h3>
	  <p>
	    The following scripts should be included in any yote page. Yote relies on jquery and the javascript is not yet minified at the
	    time of this writing.
	  </P>

	  <blockquote>
	    <code>
	      <pre>
&lt;script src="/yote/js"&gt;&lt;/script&gt;
	      </pre>
	    </code>
	  </blockquote>
	  <P>
	    Including these provides $.yote which contains the methods needed to interact 
	    with the server.
	  </P>
	  <h3>Connecting Yote</h3>
	  <p>
	    To get started using a yote app, simply invoke init, then get the 
	    app singleton object. Each app has a singleton that provides methods for the app
	    and stores information specific to it. Putting all yote code inside the jquery <code>$().ready</code> function is recommended.
	  </P>
	  <blockquote>
	    <code>
	      <pre>
$.yote.init(); //connects the front end objects to the backend

//returns the singleton app object.
var app = $.yote.fetch_app( 'MyApp' );
	      </pre>
	    </code>
	  </blockquote>

	  <h3>Logins</h3>
	  <p>
	    Some apps do not need to store information on a per user basis, but some do.
	    Yote provides methods to create and manage user accounts and logins. There are 
	    four different login related methods attached to the $.yote.
	    <BR>
	    <BR>
	    <strong>Note:</strong> All the handlers below are optional.
	  </p>
	  <blockquote>
	    <code>
	      <pre>
var login = $.yote.login( 'handle', 'password', pass_handler, fail_handler );
var login = $.yote.create_login( 'handle', 'password', 'email', pass_handler, fail_handler );
$.yote.remove_login( 'handle', 'password', 'email', pass_handler, fail_handler );
$.yote.logout();
	      </pre>
	    </code>
	  </blockquote>

	  <h3>Invoking Methods</h3>
	  <p>
	    All methods on yote objects have the same method signature and take four optional arguments.
	  </p>
	  <blockquote>
            <code>
              <pre>
var return_value = yote_obj.some_method( 
   parameter,    // this can be undefined, a scalar, a yote object, an array or an object ( hash )
   passhandler,  // this is a function that is invoked upon completion and given the return value as an argument
   failhandler,  // this is a function that is invoked upon error and is passed the error message as an argument
   use_async     // when true, this method is called asyncronously
                                       );
	      </pre>
	    </code>
	  </blockquote>
	  

	<h2>Basic Concepts</h2>
	<P>
	  Yote core javascript has four main tasks that will be covered in detail in this document. Much of the client
	  side mirrors the server side, so both the server side documentation and the client side documentation will have necessary overlap.
	  <ul>
	    <li>System Initialization.</li>
	    <li>User authentication and creation.</li>
	    <li>Providing access to server side objects and their methods.</li>
	    <li>Automatically coordinating object state with the yote server.</li>
	  </ul>
	</P>
	<p>
	  Yote javascript objects are provided with methods that mirror server side methods.
	  Each method attached to a javascript yote object has the same parameter list and all
	  parameters are optional. The methods are called syncronously be default but any may be
	  called asyncronously.
	</p>
	<p>
	  There are a few types of server side objects that always may exist for the system. These objects
	  have special methods that return them. Think of these as the primary building blocks of a yote app.
	  <dl>
	    <dt>The Root</dt><dd>The system has a singleton instance of Yote::YoteRoot that serves as the base root. The methods on this object provide all other objects. Every object in the Yote tree trace back to this primary object. Apps and user logins are directly attached here. The root will rarely be interacted with directly; convenience methods are used instead.</dd>
	    <dt>User Logins</dt><dd>Uniquely identify one person by their email and handle. Credentials are kept here and passwords are hashed.</dd>
	    <dt>User Accounts</dt><dd>One Login has a different account per app just as one person may have an account in different banks. 
	      The account holds on to user data that relates to the app in question.</dd>
	    <dt>App Objects</dt><dd>The root objects for one app. These objects store user accounts and anything else as devised by the app developer. All public methods of the app on the server side are automatically attached to the javascript object counterpart.</dd>
	  </dl>
	</p>
	<h3>Primary Javascript Methods</h3>
	<dl>
	  <dt>$.yote.init()</dt>
	  <dd>
	    This method must be called before any other. It attempts to log into the system based on tokens stored on cookies, 
	    and returns a login object if successfull.
	  </dd>
	  
	  <dt>$.yote.fetch_app( 'perl package name of app' )</dt>
	  <dd>
	    This returns a singleton app object that contains all the methods defined on the server side for that app.
	  </dd>
	  
	  <dt>$.yote.create_login( handle, password, email, passhandler, failhandler )</dt>
	  <dd>
	    Tries to create a login with the credentials supplied. It returns the login created. A pass or fail handler function are optionally 
	    passed in. This method sets login token cookies on success.
	  </dd>

	  <dt>$.yote.login( handle, password, passhandler, failhandler )</dt>
	  <dd>
	    Tries to log in with the credentials supplied. It returns the login object upon success. A pass or fail handler function are optionally 
	    passed in. This method sets login token cookies on success.
	  </dd>

	  <dt>$.yote.logout()</dt>
	  <dd>
	    Invalidates any login tokens on both the client and server side.
	  </dd>

	  <dt>$.yote.remove_login( handle, password, email, passhandler, failhandler )</dt>
	  <dd>
	    Destroys the login objects. This method requires valid credentials in order to work.  A pass or fail handler function are optionally 
	    passed in. This method clears server side login token cookies.
	  </dd>

	  <p>
	    A yote login is composed of credentials that uniquely identify a user. A yote
	    login is global across all apps. Each app, however, has a different account for
	    every login. The account is a bundle of data that is specific to an app and a user.
	    This distinction is important.
	  </P>

	  <p>
	    Emails and handles are unique for logins. Login objects are like any other Yote
	    object and any sort of data can be stored in them. There are a number of methods
	    that are attached to the yote objects.
	  </p>


	  <blockquote>
	    <code>
	      <pre>
var login = $.yote.create_login( handle, password, email, passhandler, failhandler );
  // handle, password and email are required
  //  passhandler and failhandler are optional functions that are run if
  //  the login creation succeeds or fails.

var login = $.yote.login( handle, password, email, passhandler, failhandler );
  // handle, password and email are required
  //  passhandler and failhandler are optional functions that are run if
  //  the login creation succeeds or fails.
	      </pre>
	    </code>
	  </blockquote>

	  <blockquote>
	    <code>
	      <pre>
 login.reset_password( { op =&gt; oldpassword, p =&gt; newpass, p2 =&gt; newpassverify } );
	      </pre>
	    </code>
	  </blockquote>

      </SECTION>
      
      <SECTION>
	<DIV class="page-header">
	  <h2>Server Side</h2>
	</DIV>
      </SECTION>
    
    <footer>
    </footer>
    
    <script src="/js/local.js"></script>
  </body>
</html>