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
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
-
This method is overrided from Oak::Object to create all the owned components if it receives the RESTORE parameter with a hashref of his and his owned components, or RESTORE_TOPLEVEL with the full path of the XML file. Else does nothing. You can (and you will want to) pass the OWNER special variable with a reference to the object that you want to be the owner of this component. If you override this method, you MUST call SUPER.
In the case of the name property is not passed in RESTORE, the constructor will throw a Oak::Component::Error::MissingComponentName.
If this is a top-level component, you can pass the parameter DECLARE_GLOBAL to create the $::TL::name reference... (This is used by Oak::Application) you probably will not use it by yourself)
If you are designing this component you can use the IS_DESIGNING parameter with a true value (this is used by Forest).
In the case of error in one of owned objects, the function will throw: - 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.
- 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)
- choose_filer
-
Overrided to choose the COMPONENT filer if this is a top-level component.
- 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_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::AlreadyRegistered
-
Trying to register a component with a key that is already used.
COPYRIGHT
Copyright (c) 2001 Daniel Ruoso <daniel@ruoso.com> All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.