Docs For Class WFRPC

Description

The WFRPC class encapsulates a remote procedure call from the client/UI layer.

This is the lowest-level of RPC data and is only related to the remote call.

Higher level classes like WFAction are used by widgets to coordinate RPC calls.

WFRPC is used mainly by WFAction or low-level programming on the client side that needs lower-level AJAX access, or needs to make an RPC outside of the event model.

Often custom ajax widgets like YUI TreeView or YUI Autocomplete will need to make calls to the server outside of the event model, and will use WFRPC (or the JS WFRPC) to do that.

Since the WFRPC mechanism is inherently PHOCOA-specific, it assumes all AJAX callbacks are done on the current module/page and provides wiring to integrate AJAX as cleanly as possible with the standard PHOCOA page life cycle. If you don't want this tight coupling, you can always just roll your own AJAX stuff for specific instances. You can even use WFAction::JSAction() to bootstrap this.

WFRPC API: All WFRPC calls made from JS will ultimately call a php function with the following prototype:

(object WFActionResponse) ajaxCallback($page, $params, [$userArg1, $userArg2, ... $userArgN]);

Since the prototype is effectively the same as the standard PHOCOA page action callback, you can use the same function for both circumstances.

Note that you can detect whether or not you're in an ajax callback via WFRequestController::sharedRequestController()->isAjax() call.

Has fluent interface for configuration.

todo: Why add WWW_ROOT to the invocationPath checks? is this from the form or something? seems like it's not an invocationPath if it starts with that... document/comment when you figure out why.

Located in /framework/WFRPC.php (line 34)

WFObject
   |
   --WFRPC

Class Constant Summary

PARAM_ACTION = '__phocoa_rpc_action'

PARAM_ARGC = '__phocoa_rpc_argc'

PARAM_ARGV_PREFIX = '__phocoa_rpc_argv_'

PARAM_ENABLE = '__phocoa_rpc_enable'

PARAM_INVOCATION_PATH = '__phocoa_rpc_invocationPath'

PARAM_RUNS_IF_VALID = '__phocoa_rpc_runsIfInvalid'

PARAM_TARGET = '__phocoa_rpc_target'

TARGET_MODULE = '#module#'

TARGET_PAGE = '#page#'

Variable Summary

string $action

mixed $args

object The $form

string $invocationPath

boolean $isAjax

boolean $runsIfInvalid

string $target

Method Summary

static object WFRPC RPC ()

static object WFRPC rpcFromRequest ( $invocationPath)

WFRPC __construct ()

void action ()

void execute (object WFPage $page)

void form ()

boolean isAjax ()

array rpcAsParameters ()

void runsIfInvalid ()

object WFRPC setAction (string $action)

object WFRPC setArguments (array $args)

object WFRPC setForm (object WFForm $form)

void setInvocationPath ( $mp)

object WFRPC setIsAjax (boolean $isAjax)

void setRunsIfInvalid (boolean $bool)

object WFRPC setTarget (string $target)

void target ()

Variables

string $action (line 65)

var: The method name to call on the target.
access: protected

mixed $args (line 69)

var: An array of arguments to pass on to the target/action method.
access: protected

object The $form (line 78)

var: WFForm object for the action. Actions with helpers are executed by submitting the form. Actions without helpers are submitted solely via URL and no form state is restored.
access: protected

string $invocationPath (line 52)

var: The module path of the module/page that is producing the WFRPC.
access: protected

boolean $isAjax (line 82)

var: Is this RPC an AJAX RPC or just a wrapper to submit the form?
access: protected

boolean $runsIfInvalid (line 74)

var: Should the action be executed IFF the bindings validated? Default FALSE.
access: protected

string $target (line 61)

var: A specially formatted string specifying the target object to call the action method on. This string takes on one of two formats:
- #page to bind to the page delegate
- #page#keyPath to bind to a page instance
- #module to bind to the module
- #module#keyPath to bind to a shared instance
access: protected

Methods

static method RPC (line 101)

Convenience constructor function, suitable for fluent configuration: WFRPC::WFRPC()->setForm('myForm') etc.

return: A new instance of a WFRPC object.
access: public

static object WFRPC RPC ()

static method rpcFromRequest (line 337)

Detects from the HTTP request whether or not there is an RPC request for the passed invocationPath.

NOTE: Will only return the RPC if the RPC in the parameters is for the passed invocation path. This allows PHOCOA to distinguish if an AJAX request is intended for the current module. Otherwise composited modules would all try to respond.

throws: object WFException
access: public

static object WFRPC rpcFromRequest ( $invocationPath)

$invocationPath

Constructor __construct (line 84)

access: public

WFRPC __construct ()

Redefinition of:

WFObject::__construct()

action (line 236)

void action ()

execute (line 255)

Execute the RPC. This function is called by the PHOCOA infrastructure to "execute" the RPC request in the PHOCOA infrastructure.

If the target/action method returns a WFActionResponse object, the response will be sent and execution will stop. If the target/action method returns NULL, execution will fall through to the caller.

void execute (object WFPage $page)

object WFPage $page: The current page.

form (line 226)

void form ()

isAjax (line 221)

Are we in AJAX mode?

return: TRUE if in ajax mode.

boolean isAjax ()

rpcAsParameters (line 199)

Get an array of all form parameters that need to be submitted to effect the RPC on the server when submitted.

Will include the php session id in the url params since often this is used by 3rd party clients like flash,java that don't have access to cookies.

return: An associative array of the phocoa RPC parameters. Will include form submission as well if the RPC has a form.

array rpcAsParameters ()

runsIfInvalid (line 241)

void runsIfInvalid ()

setAction (line 131)

Set the action for the rpc. See WFRPC::$action.

return: The current RPC instance, for fluent configuration.
access: public

object WFRPC setAction (string $action)

string $action: The name of the method to call on the target.

setArguments (line 143)

Set the arguments to pass along with the RPC.

return: The current RPC instance, for fluent configuration.

object WFRPC setArguments (array $args)

array $args: The array of arguments in positional order. These will be passed to the target/action starting with argument #3. The first two are $page, $params.

setForm (line 155)

Set the form associated with the RPC. RPC's with forms will submit to the PHOCOA form-processing infrastructure.

return: The current RPC instance, for fluent configuration.

object WFRPC setForm (object WFForm $form)

object WFForm $form: The form to submit with the RPC.

setInvocationPath (line 106)

access: public

void setInvocationPath ( $mp)

$mp

setIsAjax (line 168)

Tell the RPC to use either AJAX mode or simply perform a page refresh to implement the action.

return: The current RPC instance, for fluent configuration.

object WFRPC setIsAjax (boolean $isAjax)

boolean $isAjax: TRUE to use an AJAX RPC. Default: false.

setRunsIfInvalid (line 179)

Control whether the RPC will run the action method if the validation fails.

void setRunsIfInvalid (boolean $bool)

boolean $bool: TRUE to run even if validation fails. FALSE for normal behavior to just return errors if validation fails. DEFAULT: false.

setTarget (line 118)

Set the target for the rpc. See WFRPC::$target.

return: The current RPC instance, for fluent configuration.
access: public

object WFRPC setTarget (string $target)

string $target: The target of the WFRPC call. This should point to an object.

target (line 231)

void target ()

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

PARAM_ACTION = '__phocoa_rpc_action' (line 43)

PARAM_ARGC = '__phocoa_rpc_argc' (line 46)

PARAM_ARGV_PREFIX = '__phocoa_rpc_argv_' (line 47)

PARAM_ENABLE = '__phocoa_rpc_enable' (line 40)

PARAM_INVOCATION_PATH = '__phocoa_rpc_invocationPath' (line 41)

PARAM_RUNS_IF_VALID = '__phocoa_rpc_runsIfInvalid' (line 44)

PARAM_TARGET = '__phocoa_rpc_target' (line 42)

TARGET_MODULE = '#module#' (line 37)

TARGET_PAGE = '#page#' (line 36)