Eric Wolf > Yote > Yote::Obj

Download:
Yote-0.228.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  1
View/Report Bugs
Module Version: 0.074   Source  

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 Root 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 => container_name, items => [] } )

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

container_type( container_name )

returns the class name of the given container from this host object.

count( field_name )

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

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

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

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

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

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

Returns the item from the named hash by key.

hash_has_key( { name => container_name, key => keytotest } );
insert_at( { name => container_name, index => '', item => item } )

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

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

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

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

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

new_with_same_permissions()

Returns a new yote object with the same permissions as this.

paginate( args )

Returns a paginated list or hash. Arguments are

limit
name ( of container )
return_hash
reverse
reversed_orders list of sort fields that should be reversed
skip
search_fields
search_terms
sort
sort_fields list of fields to sort objects by. Only works on collection of Yote::Obj objects.
precache

Overridable. Should return items you want cached on the client side.

remove_from( { name => container_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.

sync_changed

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.

syntax highlighting: