NAME GenieMod::Request

Represents/stores the data for a single request.

DESCRIPTION

This is the generic wrapper/object/whatever for a request. One of these is created for each run. This particular request is optimized for CGI.

• create(%opt)

Options are:

    ViewMap     - View::Map object (needed so get_view() works) Can be a list reference
                  for fallback, in which case ViewMap objects are tried in order.

    Cgi         - CGI object. (url_param and param)
    Out         - Output handle 
    Session     - CGI:Session style object. (Optional)

• register_finish($code_ref)

Register a callback function to be run when finish() is called.

• create_session_object()

Provided so you can override it. (default, for !!!NOW!! creates a CGI::Session object)

[adv]

CGI:Session is bloated for regular CGI work, alas, we need it to send the headers.

• session()

Obtain the session object. Create if need be. This will return FALSE if a session object cannot be created (ex. if there is no session configuration area)

• cgi()

Obtain the CGI object.

• finish()

Call this method AFTER the request's view has been display()'d It is intended to execute bits of code (ideally and where possible) without any output sent to the browser.

    $vw = $ctl->run($req);
    $vw->display();
    

    # Possibly closing the request handle.. 

    $req->finish();

The callback code will have an instance of GenieMod::Request passed as it's first argument.

• action()

get/set the current Action for this request.

The Controller object needs to set this in it's run_method function, so that ViewMap can figure out which view to return.

• param()

param() is used to pass parameters into and out of views. (For display()) for passing stuff around WITHIN the controller, see pad()

    @param_names = $req->param();
    $val = $req->param("KEY");
    $req->param("KEY",$some_scalar);

• pad()

This is the pad area for passing parameters around WITHIN the controller. A view shouldn't use it. Use param() for that purpose.

With no arguments, returns a reference to a hash that can be assigned to, like a $self that ONLY lasts for this particular request.

The reason for having this is, the $self within a controller should not store request data this is because the Controller object may stay around in memory for awhile and you don't want data bleeding across from page to page!

pad() is a way of passing paramters around between controller methods.

• get_view($view_name)

This calls the underlying view map for a named view, and returns it.

• out()

Get/Set the out handle.

Note that Out is actually WRAPPED in a special handle. (See Output Handle)

One really should only set this once. To temporarily change the output handle see

    $old_out = $out->swap_out($new_io);
    $out->print("Whatever");
    $out->swap_out($old_out);

Output Handle

The Out paramter and out() method are used to get/set the output handle, that is, the handle used to display output to the browser/client/whatever.

In this particular case, we needed a way to set the headers. Therefore, the handle has a header() method associated with it.

• header($header_text,$append)

    $out = $req->out();

    # APPEND Foo: to the list of headers.
    $out->header("Foo: bark",1) 

    # SET (replace) the content-type header.   
    $out->header("Content-Type: text/plain"); 

    # Obtain current headers.
    @current = $out->header(); 

• headers_sent()

Return TRUE if headers have already been sent. You MAY change this manually if you need to. (Example: to use a "View" to send email or if for whatever reason your headers have been supplied elsewhere)

• headers_clear()

Clears all headers.

• swap_out($io)

Swaps the current output handle with a new one.

Returns the old handle, sets to $io.

The idea being to provide buffers and so-forth.