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-fledged
           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.

REQUEST PROPERTIES

   address
   arguments
   body
   content_length
   content_type
   cookies
   env
   header
   headers
   input
   method
   request_method (deprecated)
   path
   path_info
   port
   protocol
   referer
   remote_host
   request_uri
   scheme
   script_name
   secure
   uploads
   uri
   user
   user_agent

METHODS

   BUILD 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.

   setup_subrequest_env
       Copies the bare minimals of the plack environment from the top request; this is called in
       "BUILD" if the request is a subrequest.

   clone
       Return a copy of the request.

   promote
       Attempt to fill in the request from any number of various methods -- YAML, JSON, etc.
       Falls back to query parameters.  Takes a Plack::Request object.

   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_args REQ
       Calls "from_webform" with the "parameters" in Plack::Request after splitting "|"'s in
       argument names.  See "argument munging".

       Returns itself.

   from_webform %QUERY_ARGS
       Parses web form arguments into the Jifty::Request data structure.  Takes in the query
       arguments. See "SERIALIZATION" for details of how query parameters are parsed.

       Returns itself.

   argument KEY [=> VALUE]
       Merges a single query parameter into the request.  This may add actions, change action
       arguments, or change state variables.

   template_argument KEY [=> VALUE]
       Sets an argument for the current template.  Template arguments, unlike values set via
       "argument", cannot add actions, change action argument, or change state variables.  They
       are also not stored in continuations.

   delete KEY
       Removes the argument supplied -- this is the opposite of "argument", above.

   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.

   webform_to_data_structure HASHREF
       Converts the data from a webform's %args to the data structure that Jifty::Request uses
       internally.

       XXX TODO: ALEX: DOC ME

   continuation_id [CONTINUATION_ID]
       Gets or sets the ID of the current continuation associated with the request.

   continuation [CONTINUATION]
       Returns the current Jifty::Continuation object associated with this request, if any.

   future_continuation_id
       Gets or sets the ID of the continuation that we are about to return or call into.

   future_continuation
       Returns the Jifty::Continuation that we are about to return or call into, if any.

   save_continuation
       Saves the current request and response if we've been asked to.  If we save the
       continuation, we redirect to the next page -- the call to "save_continuation" never
       returns.

   call_continuation
       Calls the Jifty::Continuation associated with this request, if there is one.  Returns true
       if the continuation was called successfully -- if calling the continuation requires a
       redirect, this function will throw an exception to its enclosing dispatcher.

   return_from_continuation
       Returns from the current continuation, if there is one.  If the request path doesn't
       match, we call the continuation again, which should redirect to the right place.  If we
       have to do this, we return true, which should be taken as a sign to not process the
       request further.

   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"; returns the newly-added Jifty::Request::StateVariable.

   remove_state_variable KEY
       Removes the given state variable.  The opposite of "add_state_variable", above.

   clear_state_variables
       Remove all the state variables.

   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.  Returns the newly added
       Jifty::Request::Action.

       See Jifty::Action.

   clear_actions
       Removes all actions from this request

   remove_action MONIKER
       Removes an action with the given moniker.

   fragments
       Returns a list of fragments requested, as Jifty::Request::Fragment objects.

   fragment NAME
       Returns the requested fragment with that name

   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.  Returns the newly added
       Jifty::Request::Fragment.

       See Jifty::PageRegion.

   do_mapping PARAMHASH
       Takes two possible arguments, "request" and "response"; they default to the current
       Jifty::Request and the current Jifty::Response.  Calls "map" in Jifty::Request::Mapper on
       every argument of this request, pulling arguments and results from the given "request" and
       "response".

   is_subrequest
       Returns true if this request is a subrequest.

   top_request
       Returns the top-level request for this request; if this is a subrequest, this is the user-
       created request that the handler got originally.  Otherwise, returns itself;

   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]

       has_run [BOOLEAN]

       delete

   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]

       in_form [BOOLEAN]

       argument NAME [VALUE]

       arguments

       delete

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.

       argument munging

       In addition to standard Mason argument munging, Jifty also takes arguments with a name of

          bla=bap|beep=bop|foo=bar

       and an arbitrary value, and makes them appear as if they were actually separate arguments.
       The purpose is to allow submit buttons to act as if they'd sent multiple values, without
       using JavaScript.

       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 a level of fallback, which is checked if the
       first doesn't exist: "J:A: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 simple as passing "J:CALL" with the id of the continuation to call;
       this will redirect to the appropriate url, with <J:RETURN> set.

       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 Protocol
   JSON POST Request Protocol