NAME

Yote::Obj - Base class for all persistant Yote objects.

DESCRIPTION

Yote::Obj is the base class for all stateful Yote objects that have an API presence and will be stored in persistant.

This is a container class and all objects of this class have automatic getter and setter methods for scalar and list entries. Invoking '$yote_obj->set_foo( "bar" );' will cause a variable named 'foo' to be attached to this object and assigned the value of "bar". The values that can be assigend are any number, string, hash, list or Yote::Obj object. Calling 'my $val = $yote_obj->get_baz( "fred" )' will return the value of the variable 'baz', and if none is defined, assigns the value "fred" to 'baz' and returns it.

Additionally, '$yote_obj->add_to_foo( "a", "b", "c", "c" )' will add the values 'a', 'b', 'c' and 'c' to the list with the variable name 'foo' that is attached to this object. If no such variable exists, a list will be created and assigned to it. If there already is a 'foo' that is not a list, and error will not result. There are a counterpart methods '$yote_obj->remove_from_foo( "c" )' which removes the first instance of c from the foo list, and '$yote_obj->remove_all_from_foo( "b" )' which will remove all the "b" values from the 'foo' list.

All Yote objects have public api methods. These are methods that connect to javascript objects and are invoked by clients. All the public api methods have the same signature :

All Yote objects except YoteRoot are attached to an application or descent of the Yote::AppRoot class.

public_api_method( $data, $account )

Where $data is either a scalar value, a list, hash or yote object. $account is the account assigned to the user for the app that this yote object belongs to. $account may be undefined if the method may be called by someone not logging in.

A NOTE ON METHODS

There are different method types for yote :

Public API methods

These methods are called automatically by the yote system and are not meant to be called by other subs. The yote system automatically passes data given to the API and passes in the account of the logged in user (if any), so the signature for these methods is always the same.

Automatic container methods

These are the methods that are automatic to any yote object. The 'foo', is of course, a stand in for any data name.

* set_foo

* get_foo

* add_to_foo

* remove_from_foo

Utility methods

Initialization methods

These methods begin with an underscore. The underscore signals to yote to not broadcast this method to the javascript proxy objects. The yote convention is a single underscore for a utility method that is called by other methods in all packages, and a double underscore for 'private' methods.

A NOTE ON DATA

Yote has 3 behaviors for data fields of Yote objects

read only through api

If a field begins with a lowercase letter, the yote server will be transmitted it the javascript proxy object, and will ignore any requests from the client to update its value.

read/write through api

If a field begins with a capital letter, it will be transmitted to the javascript proxy object, which may send updates of its value back to the yote server.

private data field

If a field starts with an underscore, the yote server will not transmit it to the javascript proxy, and will ignore any requests from the client to update its value.

UTILITY METHODS

_absorb

This takes a hash reference as an argument and uses the key/value entries in this hash to set values for the fields corresponding to the hash keys.

_is

Returns true if the single object argument passed in is equivalent to this one.

_path_to_root

Returns the xpath string that locates this object in the object tree.

INITIALIZATION METHODS

new

New takes an optional hash as an argument. If given a hash, it populates the object with the key value pairs in the hash, as long as those are text/numbers,lists,hashes or yote objects. Note that while this does not start with an underscore, it is still not exposed to the javascript yote objects.

_init

This is called once : only the very first time a Yote object is created. It is used to set up initial data.

_load

This method is called each time an object is loaded from the data store.

PUBLIC API METHODS

count( field_name )

Returns the number of items for the field of this object provided it is an array or hash.

paginate

This method takes a list ref with three entries : [field_name, number of items to return, starting point]. The starting point is optional and defaults to 0. Returns a subset of the list that is specified by the field name and attached to this object.

This will throw an error if the value of the field name is defined as something other than a list.

paginate_hash

This method takes a list ref with three entries : [field_name, number of items to return, starting point]. The starting point is optional and defaults to 0. Returns a slice of the hash that is specified by the field name and attached to this object. The keys are sorted before the return so that the order can be guaranteed between subsequent calls.

This will throw an error if the value of the field name is defined as something other than a list.

paginate_rev

This method is just like paginate except it works on the list in reverse order. This method takes a list ref with three entries : [field_name, number of items to return, starting point]. The starting point is optional and defaults to 0. Returns a subset of the list that is specified by the field name and attached to this object.

This will throw an error if the value of the field name is defined as something other than a list.

sync_all

This method is actually a no-op, but has the effect of syncing the state of client and server.

update

This method is called automatically by a client javascript objet when its _send_update method is called. It takes a hash ref filled with field name value pairs and updates the values that are read/write ( first character is a capital letter ).

AUTHOR

Eric Wolf

LICENSE AND COPYRIGHT

Copyright (C) 2011 Eric Wolf

This module is free software; it can be used under the same terms as perl itself.