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.

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

add_to( { name => '', items => [] } )

Adds the items to the list attached to this object specified by name.

count( field_name )

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

delete_key( { name => '', key => '' } )

Removes the key from the hash attached to this object specified by name.

hash( { name => '', key => '', value => item } )

Hashes the item to the key to the hash attached to this object specified by name.

hash_fetch( { name => '', key => '' } )

Returns the item from the named hash by key.

insert_at( { name => '', index => '', item => item } )

Insert the item at the index to the list attached to this object specified by name.

list_delete( { name => '', index => '' } )

Removes the item at the index postion from the list attached to this object specified by name.

list_fetch( { name => '', index => '' } )

Returns item at the index postion from the list attached to this object specified by name.

paginate( args )

Returns a paginated list or hash. Arguments are

remove_from( { name => '', items => [] } )

Removes the items ( by value ) from the list attached to this object specified by name.

* name - name of data structure attached to this object. * search_fields - a list of fields to search for in collections of yote objects * search_terms - a list of terms to search for * sort_fields - a list of fields to sort by for collections of yote objects * reversed_orders - a list of true or false values corresponding to the sort_fields list. A true value means that field is sorted in reverse * limit - maximum number of entries to return * skip - skip this many entries before returning the list * return_hash - return the result as a hashtable rather than as a list * reverse - return the result in reverse order

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 coyocanid@gmail.com http://madyote.com

LICENSE AND COPYRIGHT

Copyright (C) 2011 Eric Wolf

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