Yote
Author: Eric Wolf, coyocanid@gmail.com

# Server Side Documentation

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.

## Yote Objects

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.

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.

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.

### Creating

Creating a new Yote object is as easy as `my $obj = new Yote::Obj();`. 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.

### Getters and Setters

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 `foo` in the cases below is a field of the Yote object.

- `set_foo( newvalue )`
- `get_foo( defaultvalue )`
- `add_to_foo( list of items )`
- `remove_from_foo( list of items )`
- `add_once_to_foo( list of items )`
- `remove_all_from_foo( list of items )`

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 :

- Properties may not start with an underscore. Those that do are considered private to the server side.
- 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.

### Public Methods

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.

- `new` - creates a new Yote object, automatically assinging it an ID. This method does not attach the object to the tree.
- `paginate( [ $listname, $limit, $start ] )` returns a paginated part of a list that is attached to this object.
- `paginate_rev( [ $listname, $limit, $start ] )` returns a paginated part of a reversed list that is attached to this object.
- `paginate_hash( [ $hashname, $limit, $start ] )` returns a slice of a hash attached to this object. The keys are sorted so the order is guaranteed.
- `update( $hash_ref )` This method will fail unless overridden. It is intended to update the data of the object with the data supplied in the hash argument.

### Private Methods

- `_is( $otherobj )` Returns true if the $otherobj is the same object as this one.
- `_absorb( hash )` Loads the fields of the incoming hash into the data of this object.
- `_load` This method is called whenever this method is loaded. This can be used to include new data or do checks or calculations.
- `_update( $hash_ref )` allows the client to update the writeable data in this object.

### Method Signature

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

> `

>     $yote_obj->mymethod( $data_scalar_or_reference, $user_account, $environment );

> `

These parameters are passed in automatically by the app server as the client invokes them. All arguments are optional.

## Apps

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.

### Yote::Login

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.
The Login the following automatic methods defined for it:

- `reset_password( { op => old-password, p => newpassword, p2 => newpassconfirm } )`
- `is_root` : returns true if root.
- `sync_all` : updates the client object cache.
- `upload_avatar( { avatar => avatar-file } )`
- `Avatar` : returns Yote::FileHelper object associated with avatar.

### Yote::Account

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.

- `read_messages( { 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 } )`
- `send_message( { recipients => list-of-accounts, message => msg, subject => subj } )`
- `upload_avatar( { avatar => avatar-file } )`

### Yote::AppRoot

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 `$.yote.fetch_app( 'package name' )`. 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.

All objects relevant to the App can trace a path back to this root object. Any App Root resides inside the YoteRoot.

### Public Methods

- `account` : Returns the account currently logged into this app.

### Private Methods

- `_init_account` : This is run the first time a user logs into this app. It takes one argument - the new account.
- `_new_account` : Returns a new Account object. This method can be overridden to return a subclass of Account.

### Yote::FileHelper

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.

## Non App Programming

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.