Docs For Class WFModuleInvocation

Class WFModuleInvocation

Description

The WFModuleInvocation object is a wrapper around WFModule. This allows the modules to be nicely decoupled from the callers. Thus, the http handler can create a WFModuleInvocation based on the URL, while a WFModuleView can create one based on parameters set by a caller.

This is particularly useful for using the module infrastructure to render HTML for emails, etc.

WFModuleInvocation is also used to keep track of "composited" pages. That is, pages can contain arbitrarily nested pages WFModuleView. This allows easy creation of portal-type environments and promotes re-use of pages as components. Since most reusable components of web pages are more complicated than single widgets (ie WFView or WFWidget subclasses), the ability to use modules as components allows for the creation of re-usable components that harness the power of the Module/Page system. This way, components can use bindings, formatters, GUI builder, etc and thus make it much easier for developers to build re-usable components for their applications.

The ROOT module always has a skin, and its output will be skinned by default. Sub-modules by default have no skin. Callers may be interested in either the module's skin skin() on the "root" skin rootSkin() of the module.

Developers may still want to develop new WFWidget and WFView subclasses, but these should be limited to their appropriate scope, which is non-application specific UI widgets.

todo: Eventually we'd like the ability to have multiple BASE directories containing modules. Mainly the purpose of this is so that the framework could ship with some modules, and they would be accessible, but in a different place from the user's modules. We have to make the framework easy to update separately from the user code. We could have some "aliases" inside the path-walking stuff that would shunt over to another dir. for instance, maybe if the first path was "contrib" it would shunt over to contrib/modules/ or that kind of thing.
todo: Evaluate whether the WFModuleInvocation and WFModule should be coalesced into a single class... can they be used apart from each other?
todo: Do we need to encapsulate the "login" module in a method of WFAuthorizationManager so that applications can override the login module with their own?

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

WFObject
   |
   --WFModuleInvocation

Class Constant Summary

PARAMETER_NULL_VALUE = 'WFNull'

Variable Summary

array $invocationParameters

string $invocationPath

object WFModule $module

string $moduleName

string $modulePath

string $modulesDir

string $pageName

object WFModuleInvocation $parentInvocation

boolean $respondsToForms

object The $skin

boolean $targetRootModule

Method Summary

static string quickModule (string $invocationPath, [ $skinDelegate = NULL])

WFModuleInvocation __construct (string $invocationPath, object WFModuleInvocation $parentInvocation, [string $skinDelegate = NULL])

string execute ()

string invocationPath ()

boolean isRootInvocation ()

object WFModule module ()

string moduleName ()

string modulePath ()

string modulesDir ()

string pageName ()

array parameters ()

string parametersAsPathInfo ()

object WFModuleInvocation parentInvocation ()

boolean respondsToForms ()

object WFModuleInvocation rootInvocation ()

object WFSkin. rootSkin ()

void setModulesDir (string $d)

void setRespondsToForms (boolean $responds)

object WFSkin setSkinDelegate (string $skinDelegate)

void setTargetRootModule (boolean $targetRoot)

object WFSkin. skin ()

boolean targetRootModule ()

Variables

array $invocationParameters (line 52)

var: the calculated extra parameters for the invocation: (Param1, Param2)
access: protected

string $invocationPath (line 48)

var: the passed-in invocation path: /path/to/module[/Param1[/Param2]]. Note that the ParamN values should be urlencoded.
access: protected

object WFModule $module (line 68)

var: The WFModule that this invocation wraps.
access: protected

string $moduleName (line 60)

var: The name of the module that was found, if one was found, at modulePath.
access: protected

string $modulePath (line 56)

var: The path to the module. This will be normalized to always start WITHOUT '/'. IE: path/to/myModule
access: protected

string $modulesDir (line 88)

var: The base modules directory that contains this module path. This is one of the paths in WFWebApplication::modulePaths(), or the APP_ROOT/modules directory.
access: protected

string $pageName (line 64)

var: The name of the page that will be displayed for this invocation.
access: protected

object WFModuleInvocation $parentInvocation (line 44)

var: A reference to the parent WFModuleInvocation for this object, or NULL if it's the root object.
access: protected

boolean $respondsToForms (line 80)

var: TRUE if this invocation should respond to form submissions, FALSE otherwise. This setting is typically used in situations where the module is used from a skin or a compositing situation. For instance, you may want to use a "search" module in your skin via WFSkinModuleView. When the user submits the form, it will automatically target the search module and display the results in the body. However, unless respondsToForms is set to FALSE, the skin itself will also respond to the search!
access: protected

object The $skin (line 84)

var: WFSkin object for this invocation. By default, only ROOT invocations will be skinned.
access: protected

boolean $targetRootModule (line 72)

var: TRUE to have all forms for this module target the rood module, FALSE to target the current module.
access: protected

Methods

static method quickModule (line 584)

Easily convert an invocation path into the resulting HTML.

Perfect for buliding emails, AJAX popups, etc.

NOTE: this mechanism doesn't allow you to communitcate with the module before execution.

If you want to pass data to a WFModuleInvocation before executing, you'll need to instantiate WFModuleInvocation yourself and call execute() manually.

return: The resulting output of module execution.
throws: object WFException Any exception generated during execution.
access: public

static string quickModule (string $invocationPath, [ $skinDelegate = NULL])

string $invocationPath: The invocation path to use.
$skinDelegate

Constructor __construct (line 102)

Constructor used to create a new WFModuleInvocation.

A WFModuleInvocation wraps the execution of a module. It contains all of the environment information needed to actually load and cause a module to execute and return the rendered result.

throws: Various errors if the module could not be identified.

WFModuleInvocation __construct (string $invocationPath, object WFModuleInvocation $parentInvocation, [string $skinDelegate = NULL])

string $invocationPath: The invocationPath for the module. The invocationPath is basically a way to specify the module to run, along with parameters. Example: path/to/my/module/pageName/param1/param2/paramN
object WFModuleInvocation $parentInvocation: The parent WFModuleInvocation that is creating this invocation, or NULL if this is the root invocation.
string $skinDelegate: The name of the skin delegate to use. Default is NULL (no skin).

Redefinition of:

WFObject::__construct()

execute (line 370)

Execute the module wrapped by this invocation.

This function is where the invocationPath is parsed, the WFModule instantiated, and the module executed.

return: The rendered result of the module invocation.
throws: Any uncaught exception.

string execute ()

invocationPath (line 322)

Get the invocationPath that was used to create this WFModuleInvocation.

return: The complete invocationPath for this WFModuleInvocation.

string invocationPath ()

isRootInvocation (line 333)

Is this module the root invocation?

return: TRUE if this is the root invocation, FALSE otherwise.
todo: Should this be named isRootModule? This would be more consistent with setTargetRootModule/targetRootModule.

boolean isRootInvocation ()

module (line 280)

Get the module that this invocation wraps.

return: The WFModule wrapped by this invocation.

object WFModule module ()

moduleName (line 290)

Get the name of the module that this invocation is wrapping.

return: Module name.

string moduleName ()

modulePath (line 312)

Get the module path to the current module.

Will always be normalized to the form: path/to/myModule

return: Module path.

string modulePath ()

modulesDir (line 155)

Get the "modules" directory used to access this module.

This is not necessarily the entire path to the module; the entire path to the module is modulesDir() + modulePath()

return: The modules directory.
see: WFModule::pathToModule()

string modulesDir ()

pageName (line 300)

Get the name of the page that this invocation will call in the module.

return: Page name.

string pageName ()

parameters (line 343)

Get the parameters that were provided in the invocationPath.

return: The parameters extracted from the invocationPath.

array parameters ()

parametersAsPathInfo (line 353)

Get the parameters that were provided in the invocationPath, as a '/'-separated string.

return: The invocation parameters in the form: /param1/param2. Each param will be urlencoded.

string parametersAsPathInfo ()

parentInvocation (line 227)

Get the parent invocation.

return: The WFModuleInvocation for the parent, or NULL if this is the root invocation.

object WFModuleInvocation parentInvocation ()

respondsToForms (line 206)

should this invocation of this module respond to forms?

return: TRUE to respond to the form, FALSE otherwise.
see: WFModuleInvocation::respondsToForms

boolean respondsToForms ()

rootInvocation (line 239)

Get the root invocation for this invocation. This may be the current invocation.

Please note that it is possible to have multiple "root" invocations -- this routine just finds the root of the "current" tree.

return: that is the "root" of this invocation tree.

object WFModuleInvocation rootInvocation ()

rootSkin (line 181)

Get the skin used by the ROOT module of this module hierarchy.

This function should be used if you want access to the skin that will be wrapping the current page, regardless of where in the module hierarchy the caller is.

return: The WFSkin object for this invocation's root module, or NULL if there is none.
see: WFModuleInvocation::skin()

object WFSkin. rootSkin ()

setModulesDir (line 142)

Set the "modules" directory used to access this module.

This is not necessarily the entire path to the module; the entire path to the module is modulesDir() + modulePath()

see: WFModule::pathToModule()

void setModulesDir (string $d)

string $d: The modules directory.

setRespondsToForms (line 217)

Set whether or not the module in this invocation should respond to forms.

see: WFModuleInvocation::respondsToForms

void setRespondsToForms (boolean $responds)

boolean $responds: TRUE to respond to the form, FALSE otherwise.

setSkinDelegate (line 193)

set the skin delegate for this invocation.

return: The skin object set up with the passed delegate.

object WFSkin setSkinDelegate (string $skinDelegate)

string $skinDelegate: The name of the skin delegate to use.

setTargetRootModule (line 270)

Should this invocation target the root invocation's module, or the current module?

For modules that target the root module, their forms will always post to the root module. This will result in keeping the current "compositing" of the root module.

For modules that target the current module, their forms will always post to the current module. This will result in making the sub-module the root module if a form is submitted.

void setTargetRootModule (boolean $targetRoot)

boolean $targetRoot: TRUE if it targets the root module, false if it targets the current module.

skin (line 168)

Get the skin for this module invocation.

This function should be used if you want to know if this module itself has a skin. Contrast with rootSkin().

return: The WFSkin object for this invocation, or NULL if there is none.
see: WFModuleInvocation::rootSkin()

object WFSkin. skin ()

targetRootModule (line 254)

Does this invocation target the root invocation's module, or the current module?

return: TRUE if it targets the root module, false if it targets the current module.

boolean targetRootModule ()

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()

Class Constants

PARAMETER_NULL_VALUE = 'WFNull' (line 39)

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