Docs For Class WFPage

Class WFPage

Description

The WFPage encapsulates the UI and Controller Layer state of a page.

The Page infrastructure initializes pages by instantiating all WFView instances (including widgets) in a page (from the .instances file), loads all configs for those instances (from the .config file), and also can render the page to HTML using a WFPageRendering-compatible template instance.

The page manages the WFView instances with a Mediator pattern.

The page is responsible for helping the widgets restore their state from a request.

SEE COMPOSITE PATTERN IN GoF for ideas about the widget hierarchy.

WFPage automatically adds a few useful variables to your template:

__page The current WFPage being rendered.
__module The WFModule that the page belongs to.
__skin The WFSkin being used to wrap the page. MAY BE NULL! When a page is not the "root" module, it may not be wrapped in a skin, so be careful when using this.

Located in /framework/WFPage.php (line 160)

WFObject
   |
   --WFPage

Variable Summary

mixed $delegate

mixed $errors

mixed $instances

mixed $module

mixed $pageName

mixed $parameters

mixed $template

Method Summary

WFPage __construct ( $module)

void addError (object A $error)

void addInstance (string $id, object The $object)

void assertPageInited ()

void assign (string $name, mixed $value)

object An delegate ()

void didRenderPage ( &$output)

void doAction ( $actionName)

void dumpTree ([ $obj = NULL])

array errors ()

boolean formIsValid ()

boolean hasOutlet (string $id)

boolean hasSubmittedForm ()

object The initInstancePHP (string $id, assoc_array $instanceManifest)

object The initInstanceYAML (string $id, assoc_array $instanceManifest)

void initPage ( $pageName)

array instances ()

boolean isLoaded ()

boolean isRequestPage ()

boolean isResponsePage ()

void loadConfig (string $configFile)

object A module ()

void noAction ()

object An outlet (string $id)

void pageInstancesDidLoad ()

string pageName ()

mixed parameter (string $name)

void parameterList ()

assoc_array parameters ()

void parametersDidLoad ()

object The prepareTemplate ()

void pullBindings ()

void pushBindings ()

void removeInstance (string $id)

string render ()

void restoreState ()

void setDelegate (object An $d)

void setTemplateFile (string $tplFileName)

void setupSkin ( $skin)

void sharedOutlet (string $id)

string submittedFormName ()

object WFPageRendering template ()

string urlToState ()

array widgets ()

void willPushBindings ()

void willRenderPage ()

Variables

mixed $delegate (line 169)

access: protected

mixed $errors (line 167)

access: protected

mixed $instances (line 165)

access: protected

mixed $module (line 162)

access: protected

mixed $pageName (line 163)

access: protected

mixed $parameters (line 166)

access: protected

mixed $template (line 164)

access: protected

Methods

Constructor __construct (line 171)

WFPage __construct ( $module)

WFModule $module

Redefinition of:

WFObject::__construct()

addError (line 992)

Add an error to the current page.

This function is used by WFWidgets or from action methods to add errors to the current request page. Widgets automatically register all errors generated by Key-Value Validation of bound values. Clients can call this function from the action method to add other run-time errors to the error mechanism.

If the requestPage has *any* errors, the responsePage will *not* be loaded.

throws: If the passed error is not a WFError or if addError() is called on the responsePage.

void addError (object A $error)

object A $error: WFError object.

addInstance (line 444)

Add an instance to our page.

Use this function to add dynamically created instances to the page. NOTE: for adding WFView instances, you don't need to do this as the WFView class automatically registers all widgets.

throws: If there is a duplicate, or $object is not an object.

void addInstance (string $id, object The $object)

string $id: The ID of the instance (must be unique).
object The $object: object.

assertPageInited (line 1406)

Ensure the page is inited.

access: protected

void assertPageInited ()

assign (line 1416)

Assign a value to the underlying template engine.

void assign (string $name, mixed $value)

string $name: Name of the value in the template engine.
mixed $value: The value to assign.

delegate (line 202)

Get the WFPageDelegate for this page.

return: object implementing some of the WFPageDelegate methods.

object An delegate ()

didRenderPage (line 1603)

void didRenderPage ( &$output)

&$output

doAction (line 1548)

void doAction ( $actionName)

$actionName

dumpTree (line 1616)

Debug function for dumping the instance tree for the page.

Recursive. Call dumpTree() to use.

void dumpTree ([ $obj = NULL])

$obj

errors (line 1003)

Get a list of all errors on the page.

return: An array of WFErrors, or an empty array if there are no errors.

array errors ()

formIsValid (line 1013)

Is the form valid? A form (ie requestPage submission) is considered valid if there are NO errors after it has been processed.

return: TRUE if the form is valid, FALSE otherwise.
throws: If called on a view besides the requestPage, or if no form was submitted.

boolean formIsValid ()

hasOutlet (line 418)

Determine if there is a page instance for the given id.

return: TRUE if there is an instance of that id, false otherwise.

boolean hasOutlet (string $id)

string $id: The id of the instance to get.

hasSubmittedForm (line 285)

Does this page have a form that was submitted for it?

return: TRUE if a form was submitted; FALSE otherwise.

boolean hasSubmittedForm ()

initInstancePHP (line 495)

Handle the instantiation of the passed object from the instances file.

The .instances mechanism simply looks for a file named <pageName>.instances and a <pageName>.config file in your module's templates directory. The .instances contains a list of all WFView instances for the page, and the hierarchy information.

$__instances = array(
'instanceID' => array(
'class' => 'WFViewSubclass',
'children' => array(
'subInstanceID' => array('class' => 'WFTextField')
),
'instanceID2' => array(
'class' => 'WFViewSubclass'
)
);

For each instance id, an instance of the listed class will be added to the view hierarchy. If children are listed, they will be added as well at the appropriate place in the hierarchy.

return: instantiated object.
access: protected

object The initInstancePHP (string $id, assoc_array $instanceManifest)

string $id: The ID of the instance.
assoc_array $instanceManifest: The manifest info for the instance. 'class' is the class of the instance, and 'children' contains child items (widgets only!)

initInstanceYAML (line 560)

Handle the instantiation of the passed object from the .yaml file.

The .yaml mechanism simply looks for a file named <pageName>.yaml in your module's templates directory. The .your contains a list of all WFView instances for the page, in a hierarchical tree, and the configuration / binding information for each instance.

form:
class: WFForm
properties:
method: post
children:
aField:
class: WFTextField
properties:
maxLength: 50
bindings:
value:
instanceID: customer
controllerKey: selection
modelKeyPath: creationDTS
options:

For each instance id, an instance of the listed class will be added to the view hierarchy. If children are listed, they will be added as well at the appropriate place in the hierarchy.

return: instantiated object.
access: protected

object The initInstanceYAML (string $id, assoc_array $instanceManifest)

string $id: The ID of the instance.
assoc_array $instanceManifest: The manifest info for the instance.

initPage (line 1055)

Initialize the named page. This will load the widget instances and prepare for manipulating the UI.

Each page has two parts, the HTML template, and the page instances config file (also called the .yaml file). On the filesystem, they are named <pageName>.tpl (the template file) and <pageName>.yaml (the config file).

Once the instances are initialized and configured, the module will be given a chance to load default settings for the page via a callback. This is the time to set up select lists, default values, etc. The method name that will be called on the module is "<pageName>_PageDidLoad". Here is the prototype for that method: void <pageName>_PageDidLoad($page, $parameters);

The parameters argument is an associative array, with "name" => "value". The items that will be in the array are determined by the page's parameterList, which is provided by the <pageName>_ParameterList() method, you can implement if your page needs parameters. This method should simply return a list of strings, which will become the "names" passed into your _PageDidLoad method.

Here's how the parameterization works... for each item in the array, first the PATH_INFO is mapped to the items. So, if your parameterList is:

array('itemID', 'otherParameter')

And the PATH_INFO is /12/moreData then the parameters passed in will be array('itemID' => '12', 'otherParameter' => 'moreData'). Any data that cannot be matched up will be passed with a NULL value. Also, if there is a form submitted, then the values for the parameters will be replaced by the "value" of the outlets of the same name. Thus, if your form has an "itemID" hidden field, the value from the form will supercede the value from PATH_INFO.

After the _PageDidLoad call, the UI state from the request will be applied on top of the defaults.

todo: Something is goofy with the detection of isRequestPage surrounding the action processor... seems to be getting called on the response page too. investiage.
todo: Rename this to executePage or something... this actually runs the whole page infrastructure!

void initPage ( $pageName)

$pageName

instances (line 377)

Get all instances of the page.

return: An array of all instances.

array instances ()

isLoaded (line 387)

Has the page been loaded? This becomes true once initPage() is called.

return: TRUE if loaded, FALSE otherwise.

boolean isLoaded ()

isRequestPage (line 1393)

Is this instance the requestPage for the module?

return: TRUE if this is the requestPage, false if it is not (thus it's the responsePage).

boolean isRequestPage ()

isResponsePage (line 1380)

Is this instance the responsePage for the module?

return: TRUE if this is the responsePage, false if it is not (thus it's the requestPage).

boolean isResponsePage ()

loadConfig (line 730)

Load the .config file for the page and process it.

The .config file is an OPTIONAL component. If your page has no instances, or the instances don't need configuration, you don't need a .config file. The .config file is used to set up 'properties' of the WFView instances AND to configure the 'bindings'.

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
'propName3' => '#module#moduleInstanceVarName' // use the '#module#' syntax to assign data from the module (or shared instances)
),
'bindings' => array(
'value' => array(
'instanceID' => 'moduleInstanceVarName', // put the instance name of a module instance var, or "#module#" to bind to the actual module (like File's Owner)
'controllerKey' => 'Name of the key of the controller, if the instance is a controller',
'modelKeyPath' => 'Key-Value Coding Compliant keyPath to use with the bound object'
'options' => array( // Binding options go here.
'InsertsNullPlaceholder' => true,
'NullPlaceholder' => 'Select something!'
)
)
)
)
);

NOTE: To see what bindings and options are available for a widget, cd to /framework and run "php showBindings.php WFWidgetName".

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

void loadConfig (string $configFile)

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

module (line 211)

Get the module that the page is a part of.

return: WFModule object.

object A module ()

noAction (line 1566)

void noAction ()

outlet (line 405)

Get a reference to an instance of the page.

Using $page->outlet($id) is equivalent to accessing an object through a Cocoa outlet.

return: outlet (reference) to the specified instance id.
throws: An exception if no object exists with that id or the page is not inited.

object An outlet (string $id)

string $id: The id of the instance to get.

pageInstancesDidLoad (line 1484)

void pageInstancesDidLoad ()

pageName (line 246)

Get the name of the "page" for the current WFPage instance. The "page" is our equivalent of a nib file, essentially.

return: The page name for this instance.

string pageName ()

parameter (line 236)

Get a named parameter.

return: The value of the desired parameter.
throws: object WFException If there is no parameter of the passed name.

mixed parameter (string $name)

string $name: The name of the desired parameter.

parameterList (line 1492)

void parameterList ()

parameters (line 224)

Get the parameters for the page. These are the parsed parameters of the URL, coalesced with form elements of the same name.

NOTE: This data isn't available until after initPage() has executed.

return: Array of parameters in format 'parameterID' => 'parameterValue'
todo: refactor initPage to move the code from there to here so that it's available earlier in the life cycle.

assoc_array parameters ()

parametersDidLoad (line 1515)

void parametersDidLoad ()

prepareTemplate (line 337)

Make sure a template object (a template engine conforming to WFPageRendering interface) is initialized.

return: template object for this page.
throws: Exception if there is no template file for the current page.

object The prepareTemplate ()

pullBindings (line 879)

For each widget in the current form, give the widget a chance to PULL the values from the bound objects onto the bound properties.

Only meaningful when called on the responsePage of the module. pullBindings() will call the pullBindings() method on all widgets in the form, thus allowing them to determine which bound properties need to "lookup" their values from the bound objects.

throws: If called on the responseView, as it is not meaningful.

void pullBindings ()

pushBindings (line 907)

For each widget in the current form, give the widget a chance to PUSH the values from the form onto the bound objects.

Only meaningful when called on the requestPage of the module. pushBindings() will call the pushBindings() method on all widgets in the form, thus allowing them to determine which bound properties need to "publish" their values from the form onto the bound objects. If the value has changed, validate the value and set it as appropriate (on the bound object). WFWidget subclasses do that from their pushBindings() callback using propagateValueToBinding()

throws: If called on the responseView, as it is not meaningful.

void pushBindings ()

removeInstance (line 464)

Remove an instance from the page.

Useful for dynamically created instances, if one needs to re-create them.

throws: object Exception if the instance doesn't exist.

void removeInstance (string $id)

string $id: The id of the page instance to remove.

render (line 1436)

Get the HTML output of the page.

This function will call the <pageName>_SetupSkin() callback IFF this page belongs to the root module. This function is useful if a page wants to munge skin settings such as Title or Meta Info. It is called just prior to rendering the page, as this way the client can be certain that all data is loaded prior to this call.

The prototype is:

void <pageName>_SetupSkin($skin)

return: The HTML output of the module.

string render ()

restoreState (line 946)

Restore the UI state of the page based on the submitted form.

Only meaningful when called on the requestPage of the module. Restore state will call the restoreState() method on all widgets in the form, thus allowing them to re-create the state they should be in after the changes that the user made to the form. IMPORTANT!!! THIS FUNCTION ONLY RESTORES THE VALUE OF THE UI WIDGET AND DOES NOT PUBLISH THE VALUE BACK THROUGH BINDINGS.

see: WFPage::pushBindings()
throws: If called on the responseView, as it is not meaningful.

void restoreState ()

setDelegate (line 191)

Set the WFPageDelegate to use for this page.

throws: object WFException If the parameter is not an object.

void setDelegate (object An $d)

object An $d: object implementing some of the WFPageDelegate methods.

setTemplateFile (line 309)

Tell the page to use an alternate .tpl file (besides the default, '<pagename>.tpl') for rendering the page.

When responding to a request, you will form a response to send back to the client. Depending on the nature of the response, there are two options in PHOCOA for building the response page.

In many cases, your application will need to present the same data in different ways. Once example of this is on "thank you" pages for contact form submissions. Since you will display the same data in the page, but display it differently, it is a good application of setTemplateFile().

The alternative is to use $module->setupResponsePage() to have PHOCOA respond to the request with a completely different page. However, this is most useful only if you are going to be displaying different data from the request. For instance, the "continue shopping" button of a shopping cart may go back to a product list page.

see: WFModule::setupResponsePage()

void setTemplateFile (string $tplFileName)

string $tplFileName: The template file name to use.

setupSkin (line 1575)

void setupSkin ( $skin)

$skin

sharedOutlet (line 429)

Convenience function to make it less verbose to get access to a shared outlet from a $page object (usually from a WFPageDelegate method).

throws: object WFException If there is no outlet with that name.

void sharedOutlet (string $id)

string $id: The ID of the outlet.

submittedFormName (line 261)

Determine the name of the submitted form, if there is a submitted form for the current module.

This function takes into account the module invocation's respondsToForms setting...

return: The name of the submitted form, if one was submitted. NULL if no form was submitted.
todo: Should this be in WFRequestController?

string submittedFormName ()

template (line 321)

Get the template used for this page.

return: An object that implemented WFPageRendering

object WFPageRendering template ()

urlToState (line 857)

Get a URL that will take you to the current requestPage of the module, with the current state.

Only meaningful when called on the requestPage of the module.

return: A URL to load the current page with the current state, but NOT send the current action. Useful for things like a "modify search" link.
throws: If called on the responseView, as it is not meaningful.

string urlToState ()

widgets (line 358)

Get a list of all instantiated widgets belonging to this page.

return: An array of widgets.

array widgets ()

willPushBindings (line 1537)

void willPushBindings ()

willRenderPage (line 1595)

void willRenderPage ()

Inherited Methods

Inherited From WFObject

WFObject::__construct()
WFObject::exposedProperties()
WFObject::getClass()
WFObject::keyPathToTargetAndKey()
WFObject::setValueForKey()
WFObject::setValueForKeyPath()
WFObject::validateValueForKey()
WFObject::validateValueForKeyPath()
WFObject::valueForKey()
WFObject::valueForKeyPath()
WFObject::valueForUndefinedKey()
WFObject::__toString()

Documentation generated on Thu, 17 Apr 2008 13:51:59 -0400 by phpDocumentor 1.4.1