NAME

Para::Frame::Site::Page - Represents the response page for a req

DESCRIPTION

Represents a page on a site with a specific URL.

Inherits from Para::Frame:Site:::File

During lookup or generation of the page, the URL of the page can change. We differ between the original requested URL, the resulting URL and an URL for the template used.

A Para::Frame::Request will create a Para::Frame::Site::Page object representing the response page.

A request can also create other Page objects for representing other pages for getting information about them or for generating pages for later use, maby not specificly copupled to the current request or session.

The distinction between Para::Frame::Request and Para::Frame::Site::Page are still a litle bit vauge. We should separate more clearly between the requested URL and the URL used for the response and the template used for the response.

Methods for generating the response page and accessing info about that page has been collected here.

A Site can answer under many hosts. The host of a Page vary with the request. The language given by the request is used also for actions and not just for the response page.

Each Request has one response Page object. It may first be a normal template and then change to generate an error page if action or template throw an exception. But it is still the same object.

I may change that so that a new Page object is created if there was a redirection to a new page.

Constructors

new

  Para::Frame::Site::Page->new( \%args )

Creates a Page object.

The supported arguments are

Required arguments:

  url: The path to the page in the site or a L<URI> object
  site: The name of the site as a string

Optional arguments:

  req: the Request object
  ctype: The (default) content-type to use for the page

url is set by /set_template, site is set by Para::Frame::Site::File/set_site, req defaults to the dynamicly using the current request and ctype is set by /ctype.

This constructor is usually called by /response_page.

response_page

  Para::Frame::Site::Page->response_page( $req )

Creates and initiates the page object for the request. (Not used for page objects not to be used as the response page.)

Gets the site to use from Para::Frame::Request/dirconfig or from Para::Frame::Request/host_from_env.

Calls /new with the url and ctype from the request.

Returns: a Para::Frame::Site::Page object

Accessors

See Para::Frame::Site::File/Accessors

url_path_tmpl

The path and filename in http on the host. With the language part removed.

path_tmpl

The path to the template, including the filename, relative the site home, begining with a slash.

is_index

True if this is a /index.tt

error_page_selected

  $page->erro_page_selected

True if an error page has been selected

error_page_not_selected

  $page->error_page_not_selected

True if an error page has not been selected

headers

  $p->headers

Returns: the http headers to be sent to the client as a list of listrefs of key/val pairs.

orig

  $p->orig

Returns: the original url as a Para::Frame::Site::File object.

TODO: Cache object

orig_url

  $p->orig_url

Returns: the original URI object (given then the pageobject was created), including the scheme, host and port. (But using the current site info.)

orig_url_path

  $p->orig_url_path

Returns: The original URL path. Dirs may or may not have a trailing slash.

redirection

  $p->redirection

Returns the page we will redirect to, or undef.

template

  $p->template()

Returns the (current) Template::Document object for this page, as returned by /find_template given /url_path_tmpl.

The document object can be used for getting variables set in the META part of the template, via Template::Document/AUTOLOAD.

Example:

If the template contains [% META section="games" %] you can get that value by saying:

  my $section = $p->template->section;

section has no special meaning in paraframe. ... You can also get the specially used variables like next_action, et al.

Returns: The Template::Document object

Public methods

set_headers

  $p->set_headers( [[$key,$val], [$key2,$val2], ... ] )

Same as /add_header, but replaces any existing headers.

set_header

  $p->set_header( $key => $val )

Replaces any existing header with the same key.

Returns:

The number of changes

add_header

  $p->add_header( [[$key,$val], [$key2,$val2], ... ] )

Adds one or more http response headers.

This sets headers to be used if this page is sent to the client. They can be changed until they are actually sent.

set_template

  $p->set_template( $url_path )
  $p->set_template( $url_path, $always_move_flag )

$url_path should be the URL path including the filename. This can later be retrieved by /url_path_tmpl.

Redirection to other pages can be done by using this method. Even from inside a page being generated.

To forward to a page not handled by the paraframe server, use /redirect.

Apache can possibly be rewriting the name of the file. For example the url /this.tt may be translated to, based on Apache config, to /var/www/that.tt.

The url_path to file translation is used for getting the directory of the url_path. But we assume that the filename part of the URL represents an actual file, regardless of the uri2file translation. If the translation goes to another file, that file will be ignored and the file named like that in the URL will be used.

For example: If the site path is /var/www and we have a path translation in the apache config that translates /one/two.tt to /var/www/three/four.tt we will be using the url_path /var/www/three/two.tt using the dir but disregarding the filename change.

We want to tell browsers/spiders if any redirection is a permanent or temporary one. We assume it's a temporary one unless $always_move_flag is true. But if just one move is of temporary nature, keep that value. This will only be used if we are ending up redirecting to another page.

The content type is set to text/html if this is a .tt file.

set_error_template

  $p->set_error_template( $path_tmpl )

Calls /set_template for setting the template. Sets a flag for remembering that this is an error response page.

NB! Should be called with a /path_tmpl and not a url_path_tmpl. We will prepend the Para::Frame::Site/home part.

This is done because we may change site that displays the error page. That also means that the site changed to, must find that template.

ctype

  $p->ctype
  $p->ctype( $content_type )

Returns the content type to use in the http response, in the form of a Para::Frame::Request::Ctype object.

If $content_type is defiend, sets the content type using Para::Frame::Request::Ctype/set.

redirect

  $p->redirect( $url )
  $p->redirect( $url, $permanently_flag )

This is for redirecting to a page not handled by the paraframe.

The actual redirection will be done then all the jobs are finished. Error in the jobs could result in a redirection to an error page instead.

The $url should be a full url string starting with http: or https: or just the path under the curent host.

If $permanently_flag is true, sets the http header for indicating that the requested page permanently hase moved to this page.

For redirection to a TT page handled by the same paraframe daemon, use /set_template.

set_http_status

  $p->set_http_status( $status )

Used internally by /render_output for sending the http_status of the response page to the client.

paths

  $p->paths( $burner )

Automaticly called by Template::Provider to get the include paths for building pages from templates.

Returns: /incpath

set_tt_params

The standard functions availible in templates. This is called before the page is rendered. You should not call it by yourself.

browser
The HTTP::BrowserDetect object. Not in StandAlone mode.
dir
The directory part of the filename, including the last '/'. Symlinks resolved.
u
$req->{'user'} : The Para::Frame::User object.
ENV
$req->env: The Environment hash (http://hoohoo.ncsa.uiuc.edu/cgi/env.html). Only in client mode.
filename
Holds the Para::Frame::Request/filename.
home
$req->site->home : Para::Frame::Site/home
lang
The Para::Frame::Request/preffered_language value.
me
Holds the Para::Frame::Site::File/url_path_slash for the page, except if an /error_page_selected in which case we set it to /orig_url_path. (For making it easier to link back to the intended page)
q
The CGI object. You will probably mostly use [% q.param() %] method. Only in client mode.
req
The req object.
reqnum
The paraframe server request number
result
$req->{'result'} : The Para::Frame::Result object
site
The <Para;;Frame::Site> object.

Private methods

find_template

  returns ($doc, $ext) where $doc is a L<Template::Document> objetct
that can be parsed to a L<Para::Frame::Burner> object.

fallback_error_page

  $p->fallback_error_page

Returns a scalar ref with HTML to use if the normal error response templates did not work.

render_output

  $p->render_output()

Burns the page and stores the result.

If the rendering failes, may change the template and URL. The new URL can be used for another call to this method.

This method is called by Para::Frame::Request/after_jobs.

Returns: True on success and 0 on failure

send_output

  $p->send_output

Sends the previously generated page to the client.

If the URL should change, sends a redirection header and stores the generated page in the session to be sent as a response to the future request to for the new URL.

Sends the headers followd by the page content.

If the content is in UTF8, sends the page in UTF8.

For large pages, sends the page in chunks.

sender

  $p->sender
  $p->sender( $code )

forward

  $p->forward( $url )

Should only be called AFTER the page has been generated. It's used by /send_output and should not be used by others.

$url must be a normalized url path

To request a forward, just use /set_template before the page is generated.

To forward to a page not handled by the paraframe, use /redirect.

output_redirection

  $p->output_redirection( $url )

Internally used by /forward for sending redirection headers to the client.

send_headers

  $p->send_headers()

Used internally by /send_output for sending the HTTP headers to the client.

send_in_chunks

  $p->send_in_chunks( $dataref )

Used internally by /send_output for sending the page in $dataref to the client.

It will try many times sending part by part. If a part failed to be sent, it will check if the connection has been canceled. It will also wait about a second for the client to recover, by doing a Para::Frame::Request/yield.

Returns: The number of characters sent. (That may be UTF8 characters.)

SEE ALSO

Para::Frame