NAME

Oak::Component - Implements component capability in objects

DESCRIPTION

This module is the base for all objects that needs to own other objects and other things. Oak::Component objects will use a Oak::Component::Filer filer to store the properties.

HIERARCHY

Oak::Object

Oak::Persistent

Oak::Component

PROPERTIES

__XML_FILENAME__: The name of the xml file (needed if this is a top-level)
name: All components have a name property.

EVENTS

ev_onCreate: Called after the creation of the object

METHODS

constructor

A Component can be created in the following ways:

  # 1 - Instanciating a top level
  my $comp = new MyComponent(RESTORE_TOPLEVEL => "FILENAME_OR_FILEHANDLE");

  # 2 - Instanciating a normal component
  my $comp = new MyComponent(RESTORE => { this => "that", name => "bla" });

The following options are accepted in the constructor:

IS_DESIGNING: if true, this component will not dispatch any event. Not even ev_onCreate.
OWNER: The owner component of this component.
DECLARE_GLOBAL: A variable $::TL::component_name will be created in reference to this object. If you set this option, remember to undef this variable later.

This function throws the following errors:

  - Oak::Component::Error::MissingOwnedClassname if __CLASSNAME__ not found.
  - Oak::Component::Error::MissingOwnedFile if require return a error.
  - Oak::Component::Error::ErrorCreatingOwned if new return false.

restore_toplevel($xml_filename): This function is called when the constructor receives the RESTORE_TOPLEVEL param. It loads the toplevel data from the $xml_filename file, calls restore for this object and create all the owned components.

restore($data): Receives a hash ref with the properties to be restored.

create_owned($data): Creates the owned component specified into the hashref $data.

after_construction: Overrided to dispatch the ev_onCreate event.

register_child(OBJECT, OBJECT): Register object OBJECT in the owned tree with the name of the component as key. Returns a Oak::Component::Error::AlreadyRegistered if a object is already registered with this name. The owned objects are stored on $self->{__owned__} hash. And the owned properties are stored in the __owned__properties__ hash using the same key.

free_child(KEY): Remove the object registered by the key KEY from the list of owned objects. Actually, this function will delete the entry from the hash, and if this is the last reference to that object, it will (obviously) destroy it. Throws a Oak::Component::Error::NotRegistered if KEY not exists.

get_child(KEY): Returns a reference to the owned object registered as KEY. If KEY is not registered, throws a Oak::Component::Error::NotRegistered.

list_childs: Returns an array with the key of the owned objects of this component

set_owner(OBJ): Defines the owner of this component. Creates a reference to the owner of this object and stores in $self->{__owner__} Throws a Oak::Component::Error::AlreadyOwned if a owner is already defined. Obs.: Do not set a object to be it's own owner, or you'll create a circular reference.

change_name(NEWNAME): Changes the name of this component. This function will try to register this object again as another name and then free this object as the other name.

is_designing: If called without params then returns the actual value of this special property, else sets the new value. This function defines if the current object is being edited to modify its behavior.

store_all: This function will store (if this is a top-level component) all his and his owned components properties on the filer. This function is only called if the component is in ``design time'' (see is_designing)

test_filer: Overrided to create and test the COMPONENT filer when needed. The COMPONENT filer needs the __XML_FILENAME__ property defined to create using the correct file.

child_update: Receives a change in one of the childs, abstract in Oak::Component. Called everytime the ``set'' method is called in one of its owned components.

set: Overrided from Persistent to save the changes only when the funcion store_all is called. In this case, it will only feed the property with the value.

dispatch(EVENT)

Dispatch the EVENT.

does nothing if the component is designing.

dispatch_all: This method will see if any event must be started by this component. I.e.: if a submit button was clicked, test if there is an event for this button and then launch the event. This method must not be overrided. To dispatch an event, just set $self->{__events__}{EVENTNAME} = 1, and this function will automatically dispatch the event.

AUTOLOAD

Oak::Component introduces AUTOLOAD to provide a quick acess to the owned components. ie:

  $page->login->get('value');

Will be the same as:

  $page->get_child('login')->get('value');

EXCEPTIONS

The following exceptions are introduced by Oak::Component

Oak::Component::Error::MissingOwnedClassname: This error is throwed when the property ``__CLASSNAME__'' is not found in the property hash while doing ``RECOVER'', so its impossible to create the object.

Oak::Component::Error::MissingOwnedFile: If perl could not require the module especified by the __CLASSNAME__ property this exception is throwed.

Oak::Component::Error::ErrorCreatingOwned: If the new of the class returns false, this error is raised.

Oak::Component::Error::AlreadyOwned: Trying to set the owner of a component that already has an owner

Oak::Component::Error::NotRegistered: Trying to reference an owned component that is not registered

Oak::Component::Error::AlreadyRegistered: Trying to register a component with a key that is already used.

Oak::Component::Error::MissingComponentName: Missing the name property