Docs For Class WFModule

Class WFModule

Description

The WFModule represents a single chunk of web application functionality.

Each module can have multiple pages, and each page can have multiple actions.

Basially there are two types of requests; page load requests, and actions against loaded pages.

A url like /myModule/myPage will cause the framework to simply load the requested page. Extra PATH_INFO data may be used to load particular model data into the page.

Examples: Open up a product detail page with /admin/productDetail/123 Open up a list of all products with /admin/productList Show page 2 of the search results with /admin/productSearch/myQuery/2

When the ResponsePage finishes initializing / loading the page, your module will be called back on the method <pageName>_PageDidLoad($page), which is your opportunity to provide default information and/or perform changes to the UI before it is rendered.

A url like /myModule/myPage?__action=myAction will restore the state of the myPage UI to the submitted state, then call the myAction handler for that page. Of course myAction must be part of the myPage. Also, the myAction handler may decide to CHANGE the current page.

Examples: Edit a product with /admin/productDetail/123?__action=edit or /admin/productDetail?__action=edit&id=123 Delete a product with /admin/productList?__action=delete&id=123

Action methods have the prototype: <pageName>_<actionName>_Action($requestPage) where $requestPage is restored UI state of the calling page (pageName).

Each module has a request and a repsonse page. The framework will restore the request's UI state before calling your module's action handler so that you can easily access widget values via the framework instead of via the $_REQUEST vars.

Once you decide which WFPage to display as the response, the framework loads all of the widgets in the page and allows you to manipulate them from your action handler before rendering the response.

WFModule/Page CALLBACK METHODS: Each method listed is a function in the module for the given page, with a name like myPageName_callbackName().

array ParameterList() - Called by the page to get a list of URL parameters that the page accepts. Return a list of parameters in order of how they map to the URL. void PageDidLoad($page, $params) - Called when the page has finished loading from the YAML file. void DidRestoreState($page) - called after the page has finished restoring state from all widgets, including ones created dynamically during PageDidLoad. void myPageName_myActionName_Action($page) - called on the page after pushBindings, BUT ONLY IF THERE WERE NO ERRORS. void SetupSkin($skin) - Called just before rendering the template so you can set up title and other head tags.

todo: Add a WFModule::willRender() callback called from WFPage::render() to easily allow module-level skin stuff
abstract:

Located in /framework/WFModule.php (line 663)

WFObject
   |
   --WFModule

Variable Summary

object The $invocation

object The $requestPage

object The $responsePage

array $__sharedInstances

Method Summary

static object A factory (string $invocation)

WFModule __construct (string $invocation)

void addInstance ( $id, $obj)

array allPages ()

integer checkSecurity ( $authInfo)

string defaultPage ()

void init ()

object The invocation ()

void loadConfigPHP (string $configFile)

string moduleName ()

void outlet ( $id)

string pathToModule ()

string pathToPage (string $pageName)

void prepareSharedInstances ()

object The requestPage ()

object The responsePage ()

void setupResponsePage ([string $pageName = NULL])

void sharedInstancesDidLoad ()

boolean shouldProfile ()

string WFURL ([string $module = NULL], [string $page = NULL])

Variables

object The $invocation (line 680)

var: WFModuleInvocation that launched this module.
access: protected

object The $requestPage (line 668)

var: WFPage for the incoming request.
access: protected

object The $responsePage (line 672)

var: WFPage for the outgoing response.
access: protected

array $__sharedInstances (line 676)

var: An associative array of all shared instances for this module.
access: protected

Methods

static method factory (line 861)

Get a module instance for the specified module path.

return: WFModule subclass instance.
throws: WFException if the module subclass or file does not exist.
throws: WFAuthorizationException if there is an access control violation for the module.
access: public

static object A factory (string $invocation)

string $invocation: The path to the module.

Constructor __construct (line 687)

Constructor.

WFModule __construct (string $invocation)

string $invocation: The relative path to this module.

Redefinition of:

WFObject::__construct()

addInstance (line 711)

void addInstance ( $id, $obj)

$id
$obj

allPages (line 1127)

Tell the phocoa infrastructure which "pages" your module implements.

OPTIONAL!

This method is optional. It is only needed if you want your default page to accept parameters even if the page name is not in the invocation path.

If you have only one page, this is done automatically. If you have more than one page, you'll need to implement this method to include all pages so that you can access these pages via URL.

return: An array of strings of the page names implemented by your module.

array allPages ()

checkSecurity (line 731)

Callback to allow the module to determine security clearance of the user.

Subclasses can override this method to alter security policy for this module. Default behavior is to allow all.

return: One of WFAuthorizationManager::ALLOW or WFAuthorizationManager::DENY.

integer checkSecurity ( $authInfo)

object WFAuthorizationInfo $authInfo: The authInfo for the current user.

defaultPage (line 1113)

Get the default page to use for the module if no page is specified.

return: The name of the default page.
abstract:

string defaultPage ()

init (line 698)

void init ()

invocation (line 817)

Get the module invocation.

return: WFModuleInvocation object that owns this module instance.

object The invocation ()

loadConfigPHP (line 1029)

Load the shared.config file for the module and process it.

The shared.config file is an OPTIONAL component. If your module has no instances, or the instances don't need configuration, you don't need a shared.config file.

The shared.config file can only configure properties of objects at this time. Only primitive value types may be used. String, boolean, integer, double, NULL. NO arrays or objects allowed.

$__config = array(
'instanceID' => array(
'properties' => array(
'propName' => 'Property Value',
'propName2' => 123
)
),
'instanceID2' => array(
'properties' => array(
'propName' => 'Property Value',
'propName2' => true
)
)
);

see: loadConfigYAML
throws: Various errors if configs are encountered for for non-existant instances, etc. A properly config'd page should never throw.
access: protected

void loadConfigPHP (string $configFile)

string $configFile: The absolute path to the config file.

moduleName (line 827)

Get the module's name

return: The module's name.

string moduleName ()

outlet (line 717)

void outlet ( $id)

pathToModule (line 848)

Get the path to the module.

return: The absolute file system path to the module's directory.

string pathToModule ()

pathToPage (line 838)

Get the path to the given page.

return: The path to the page, without extension. Add '.instances', '.config', or '.tpl'.

string pathToPage (string $pageName)

string $pageName: The page name.

prepareSharedInstances (line 915)

Prepare any declared shared instances for the module.

Shared Instances are objects that not WFView subclasses. Only WFView subclasses may be instantiated in the <pageName>.instances files. The Shared Instances mechanism is used to instantiate any other objects that you want to use for your pages. Usually, these are things like ObjectControllers or Formatters, which are typically "shared" across multiple pages. The Shared Instances mechanism makes it easy to instantiate and configure the properties of objects without coding, and have these objects accessible for bindings or properties. Of course, you can instantiate objects yourself and use them programmatically. This is just a best-practice for a common situation.

The shared instances mechanism simply looks for a shared.instances and a shared.config file in your module's directory. The shared.instances file should simply have a var $__instances that is an associative array of 'unique id' => 'className'. For each declared instance, the module's instance var $this->$uniqueID will be set to a new instance of "className".

$__instances = array(
'instanceID' => 'WFObjectController',
'instanceID2' => 'WFUnixDateFormatter'
);

To bind to a shared instance (or for that matter any object that's an instance var of the module), set the instanceID to "#module#, leave the controllerKey blank, and set the modelKeyPath to "<instanceVarName>.rest.of.key.path".

To use a shared instance as a property, .................... NOT YET IMPLEMENTED.

todo: Allow properties of page.config files to use shared instances.

void prepareSharedInstances ()

requestPage (line 1104)

Get the requestPage for the module.

return: WFPage representing the requestPage for this module.

object The requestPage ()

responsePage (line 1094)

Get the responsePage for the module.

return: WFPage representing the responsePage for this module.

object The responsePage ()

setupResponsePage (line 1074)

Call this method if you want the ResponsePage to be the same as the RequestPage.

Another method for altering the display of the response is to change the templateFile of the existing page with WFPage::setTemplateFile().

This is a convenience method for actions that don't need to switch the page.

see: WFPage::setTemplateFile()

void setupResponsePage ([string $pageName = NULL])

string $pageName: The name of the page in this module to use as the response page; NULL to use the request page as the response page.

sharedInstancesDidLoad (line 997)

Optional method for WFModule subclasses if they want to know when the shared instances have finished loading.

Will be called after the Shared Instances have been instantiated and configured, and before any pages are loaded.

void sharedInstancesDidLoad ()

shouldProfile (line 1139)

Should APD profiling be enabled for this request? To enable profiling of your module, just add shouldProfile() to your WFModule and return TRUE.

If so, will turn on profiling just before executing your module, and dump the profile data into the log dir.

return: TRUE to enable profiling.

boolean shouldProfile ()

WFURL (line 796)

Generate a "full" URL to the given module / page.

It is recommended to use this function to generate all URL's to pages in the application. Of course you may append some PATH_INFO or params afterwards. Also it is recommended that when referencing another action in the SAME module you pass NULL for the module, as this will ensure that your links don't break if you decide to rename your module.

return: a RELATIVE URL to the requested module/page.

string WFURL ([string $module = NULL], [string $page = NULL])

string $module: The module name (or NULL to use CURRENT module).
string $page: The page name (or NULL to use CURRENT page).

Inherited Methods

Inherited From WFObject

WFObject::__construct()
WFObject::exposedProperties()
WFObject::getClass()
WFObject::keyPathToTargetAndKey()
WFObject::setValueForKey()
WFObject::setValueForKeyPath()
WFObject::setValuesForKeys()
WFObject::validatedSetValueForKey()
WFObject::validatedSetValueForKeyPath()
WFObject::validateObject()
WFObject::validateValueForKey()
WFObject::validateValueForKeyPath()
WFObject::valueForKey()
WFObject::valueForKeyPath()
WFObject::valueForStaticKey()
WFObject::valueForStaticKeyPath()
WFObject::valueForTargetAndKeyPath()
WFObject::valueForUndefinedKey()
WFObject::valueForUndefinedStaticKey()
WFObject::valuesForKeyPaths()
WFObject::valuesForKeys()
WFObject::_valueForStaticKey()
WFObject::__toString()

Documentation generated on Thu, 14 May 2009 16:20:12 -0400 by phpDocumentor 1.4.2