NAME
Jifty::Request - Canonical internal representation of an incoming Jifty request
DESCRIPTION
This document discusses the ins and outs of getting data from the web browser (or any other source) and figuring out what it means. Most of the time, you won't need to worry about the details, but they are provided below if you're curious.
This class parses the submission and makes it available as a protocol-independent Jifty::Request object.
Each request contains several types of information:
- actions
-
A request may contain one or more actions; these are represented as Jifty::Request::Action objects. Each action request has a moniker, a set of submitted arguments, and an implementation class. By default, all actions that are submitted are run; it is possible to only mark a subset of the submitted actions as "active", and only the active actions will be run. These will eventually become full-fledge Jifty::Action objects.
- state variables
-
State variables are used to pass around bits of information which are needed more than once but not often enough to be stored in the session. Additionally, they are per-browser window, unlike session information.
- continuations
-
Continuations can be called or created during the course of a request, though each request has at most one "current" continuation. See Jifty::Continuation.
- (optional) fragments
-
Fragments are standalone bits of reusable code. They are most commonly used in the context of AJAX, where fragments are the building blocks that can be updated independently. A request is either for a full page, or for multiple independent fragments. See Jifty::Web::PageRegion.
METHODS
new PARAMHASH
Creates a new request object. For each key in the PARAMHASH, the method of that name is called, with the PARAMHASH's value as its sole argument.
fill
Attempt to fill in the request from any number of various methods -- YAML, JSON, etc. Falls back to query parameters.
from_data_structure
Fills in the request from a data structure. This is called once the YAML or JSON has been parsed. See "SERIALIZATION" for details of how to construct a proper data structure.
Returns itself.
from_mason_args
Calls from_webform with the current mason request's args.
Returns itself.
from_webform %QUERY_ARGS
Parses web form arguments into the Jifty::Request data structure. Takes in the query arguments, as parsed by Mason (thus, repeated arguments have already been turned into array refs). See "SERIALIZATION" for details of how query parameters are parsed.
Returns itself.
merge_param KEY => VALUE
Merges a single query parameter into the request. This may add actions, change action arguments, or change state variables.
parse_form_field_name FIELDNAME
Takes a form field name generated by a Jifty action. Returns a tuple of
- type
-
A slightly-too-opaque identifier
- moniker
-
The moniker for this field's action.
- argument name
-
The argument name.
call_continuation
Calls the Jifty::Continuation associated with this request, if there is one.
path
Returns the path that was requested
just_validating
This method returns true if the request was merely for validation. If this flag is set, then all active actions are validated, but no actions are run.
state_variables
Returns an array of all of this request's state variables, as Jifty::Request::StateVariables.
state_variable NAME
Returns the Jifty::Request::StateVariable object for the variable named NAME, or undef of there is no such variable.
add_state_variable PARAMHASH
Adds a state variable to this request's internal representation. Takes a key and a value.
actions
Returns a list of the actions in the request, as Jifty::Request::Action objects.
action MONIKER
Returns a Jifty::Request::Action object for the action with the given moniker, or undef if no such action was sent.
add_action PARAMHASH
Required argument: moniker.
Optional arguments: class, order, active, arguments.
Adds a Jifty::Request::Action with the given moniker to the request. If the request already contains an action with that moniker, it merges it in, overriding the implementation class, active state, and individual arguments. See Jifty::Action.
fragments
Returns a list of fragments requested, as Jifty::Request::Fragment objects.
add_fragment PARAMHASH
Required arguments: name, path
Optional arguments: arguments, wrapper
Adds a Jifty::Request::Fragment with the given name to the request. If the request already contains a fragment with that name, it merges it in. See Jifty::PageRegion.
do_mapping PARAMHASH
Takes two possible arguments, request and response; they default to the current Jifty::Request and the current Jufty::Response. Calls "map" in Jifty::Request::Mapper on every argument of this request, pulling arguments and results from the given request and response.
Jifty::Request::Action
A small package that encapsulates the bits of an action request:
moniker [NAME]
argument NAME [VALUE]
arguments
class [CLASS]
order [INTEGER]
active [BOOLEAN]
Jifty::Request::StateVariable
A small package that encapsulates the bits of a state variable:
key
value
Jifty::Request::Fragment
A small package that encapsulates the bits of a fragment request:
name [NAME]
path [PATH]
wrapper [BOOLEAN]
argument NAME [VALUE]
arguments
SERIALIZATION
CGI Query parameters
The primary source of Jifty requests through the website are CGI query parameters. These are requests submitted using CGI GET or POST requests to your Jifty application. See Jifty::MasonInterp for details of the CGI parsing.
actions
registration
For each action, the client sends a query argument whose name is J:A-moniker and whose value is the fully qualified class name of the action's implementation class. This is the action "registration." The registration may also take the form J:A-order-moniker, which also sets the action's run order.
arguments
The action's arguments are specified with query arguments of the form J:A:F-argumentname-moniker. To cope with checkboxes and the like (which don't submit anything when left unchecked) we provide two levels of fallback, which are checked if the first doesn't exist: J:A:F:F-argumentname-moniker and J:A:F:F:F-argumentname-moniker.
state variables
State variables are set via J:V-name being set to the value of the state parameter.
continuations
The current continuation set by passing the parameter J:C, which is set to the id of the continuation. To create a new continuation, the parameter J:CREATE is passed. Calling a continuation is a ssimple as passing J:CALL with the id of the continuation to call.
request options
The existence of J:VALIDATE says that the request is only validating arguments. J:ACTIONS is set to a semicolon-separated list of monikers; the actions with those monikers will be marked active, while all other actions are marked inactive. In the absence of J:ACTIONS, all actions are active.
YAML POST Request Protocool
To be spec'd later
JSON POST Request Protocool
To be spec'd later