<!DOCTYPE html>
<html>
<head>
<!-- TODO: rewrite this with templates and new info -->
<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(){
$.yote.init();
make_menus( '#top_nav' );
attach_login( {
attachpoint : '#logged_in_status',
message_attachpoint : '#msg_div'
} );
});
</script>
</head>
<BODY>
<DIV class="header">
<A href="/index.html" style="display:block">
<img height="70px" width="151px" src="yotelogo.png">
</A>
<UL id="top_nav" class="nav"></UL>
<DIV class="login logged_in" id="logged_in_status"></DIV>
<DIV id="msg_div"></DIV>
</DIV>
<H1>Server Side Documentation</H1>
<P>
This document explains Yote server side programming.
Server side programming is done using simple object oriented perl. There are no tables or schemas to deal with.
There are a few simple concepts to grasp and conventions to keep.
</P>
<SECTION>
<DIV class="page-header">
<h2>Yote Objects</h2>
</DIV>
<P>
Yote objects are organized in a heirarcical data structure. Each Yote object finds one or more paths to the
YoteRoot at the base of the graph. Yote Objects are basically containers of key value pairs where the values
may be other Yote objects, hashes, lists and scalars. All Yote objects are descendents of Yote::Obj.
Yote::Obj provides some automatic getters and setters as well as some other convenience methods.
</P>
<P>
Yote objects are loaded as needed. If one Yote object is attached to an other, it will not be loaded from
the database until the get_obj method returns it. This allows there to be a huge cohesive data tree that does
not have to be loaded into memory all at once.
</P>
<P>
Only one master process executes the Yote code and communicates with the data store. Server processes all talk
to the master process, which executes from a list of queued commands. The server process adds a command onto
a shared queue, which the master process reads from and executes, one at a time. The server thread waits on a
shared variable to be released by the main thread and returns the result contained within to the client. Optionally
the server thread can place a command in the queue and not wait for the answer.
</P>
<h3>Creating</h3>
<P>
Creating a new Yote object is as easy as <code>my $obj = new Yote::Obj();</code>. Once created it can be
attached anywhere in the tree and will persist. If it goes out of reference when it is not in the tree, it
is lost forever.
</P>
<h3>Getters and Setters</h3>
<P>
Yote uses get_ and set_ explicitly for getters and setters. This makes it clear what is happenening, and allows
yote to understand what is being asked of it. The <code><i>foo</i></code> in the cases below is a field of the
Yote object.
</P>
<ul>
<li><code>set_<i>foo</i>( <i>newvalue</i> )</code></li>
<li><code>get_<i>foo</i>( <i>defaultvalue</i> )</code></li>
<li><code>add_to_<i>foo</i>( <i>list of items</i> )</code></li>
<li><code>remove_from_<i>foo</i>( <i>list of items</i> )</code></li>
<li><code>add_once_to_<i>foo</i>( <i>list of items</i> )</code></li>
<li><code>remove_all_from_<i>foo</i>( <i>list of items</i> )</code></li>
</ul>
<p>
These are exposed to the client side in most cases. A client object will have get_foo and set_Foo methods
attached with these rules :
<ul>
<li>Properties may not start with an underscore. Those that do are considered private to the server side.</li>
<li>Only capitolized properties may be set from the client. The convention is that capitolized
field names are publically alterable for any object the client is allowed to see.</li>
</ul>
</p>
<h3>Public Methods</h3>
<P>
Yote Objects provide a stock of other methods. If a subclass of Yote::Obj is created, any methods
that do not begin with an underscore are considered to be public, and automatically exposed to the
client javascript.
</P>
<ul>
<li><code>new</code> - creates a new Yote object, automatically assinging it an ID. This method does not
attach the object to the tree.</li>
<li><code>paginate( [ $listname, $limit, $start ] )</code> returns a paginated part of a list that is attached to this object.</li>
<li><code>paginate_rev( [ $listname, $limit, $start ] )</code> returns a paginated part of a reversed list that is attached to this object.</li>
<li><code>paginate_hash( [ $hashname, $limit, $start ] )</code> returns a slice of a hash attached to this object. The keys are sorted so the order is guaranteed.</li>
<li><code>update( $hash_ref )</code> This method will fail unless overridden. It is intended to update the
data of the object with the data supplied in the hash argument.</li>
</ul>
<h3>Private Methods</h3>
<ul>
<li><code>_is( $otherobj )</code> Returns true if the $otherobj is the same object as this one.</li>
<li><code>_absorb( hash )</code> Loads the fields of the incoming hash into the data of this object.</li>
<li><code>_load</code> This method is called whenever this method is loaded.
This can be used to include new data or do checks or calculations.</li>
<li><code>_update( $hash_ref )</code> allows the client to update the writeable data in this object.</li>
</ul>
<h3>Method Signature</h3>
<P>
All public methods have the same signature. This is required so that the client and server can connect to
each other. The method signature is
</P>
<blockquote>
<code>
<pre>
$yote_obj->mymethod( $data_scalar_or_reference, $user_account, $environment );
</pre>
</code>
</blockquote>
<P>
These parameters are passed in automatically by the app server as the client invokes them. All arguments are
optional.
</P>
<SECTION>
<DIV class="page-header">
<h2>Apps</h2>
</DIV>
<p>
Yote has defined a number of classes for apps and provides specific behavior and handling of them.
The App objects that a developer will use directly.
</P>
<h3>Yote::Login</h3>
<p>
Credentials for a user associates the user with a Login. The Login is global across the whole Yote system
and have several accounts associated with it. Just as a member of a bank may have several account for one
person, a Yote user will have an account for each app.
<BR>
The Login the following automatic methods defined for it:
<ul>
<li><code><b>reset_password</b>( { op => old-password, p => newpassword, p2 => newpassconfirm } )</code></li>
<li><code><b>is_root</b></code> : returns true if root.</li>
<li><code><b>sync_all</b></code> : updates the client object cache.</li>
<li><code><b>upload_avatar</b>( { avatar => avatar-file } )</code></li>
<li><code><b>Avatar</b></code> : returns Yote::FileHelper object associated with avatar.</li>
</ul>
</p>
<h3>Yote::Account</h3>
<p>
Accounts are automatically and transparently created the first time a logged in user uses an app.
Accounts are just bundles of data specific to the app and user. Accounts are also messengers, with
convenience methods for sending and receiving messages from other users of the app.
<ul>
<li><code><b>read_messages</b>( { sort => sortby, sort_desc => reverse-sort-flag,
filter => { newer_than => time, older_than => time, from => account,
from_name => part-of-name, subject => part-of-subject
} )</code></li>
<li><code><b>send_message</b>( { recipients => list-of-accounts, message => msg, subject => subj } )</code></li>
<li><code><b>upload_avatar</b>( { avatar => avatar-file } )</code></li>
</ul>
</p>
<h3>Yote::AppRoot</h3>
<p>
Objects that are AppRoot objects are singletons which hold onto user account data in addition to
other data. They are requested on the client side by calling <code>$.yote.fetch_app( 'package name' )</code>.
If the package is visible to the Yote server by being in the perl path or the lib directory under the server
root, the singleton will be created and returned to the client.
</p>
<p>
All objects relevant to the App can trace a path back to this root object. Any App Root resides inside the
YoteRoot.
</p>
<h3>Public Methods</h3>
<ul>
<li><code>account</code> : Returns the account currently logged into this app.</li>
</ul>
<h3>Private Methods</h3>
<ul>
<li><code>_init_account</code> : This is run the first time a user logs into this app. It takes one argument - the new account.</li>
<li><code>_new_account</code> : Returns a new Account object. This method can be overridden to return a subclass of Account.</li>
</ul>
<h3>Yote::FileHelper</h3>
<p>
Yote provides a mechanism to upload files. These files, once uploaded, are stored on a the filesystem
and have a FileHelper object that provides access. This has a single public method : Url which returns
a url to the actual file to the client.
</p>
</SECTION>
<SECTION>
<DIV class="page-header">
<h2>Non App Programming</h2>
</DIV>
<p>
Yote can be useful for programs that do not connect to a client. The ability to create complex and
fluid datastructures on the fly is a powerful prototyping capability.
</p>
</SECTION>
<footer>
</footer>
<script src="/js/local.js"></script>
</body>
</html>