Para::Frame::Site::Page - Represents the response page for a req
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.
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.
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
See Para::Frame::Site::File/Accessors
The path and filename in http on the host. With the language part removed.
The path to the template, including the filename, relative the site home, begining with a slash.
True if this is a /index.tt
$page->erro_page_selected
True if an error page has been selected
$page->error_page_not_selected
True if an error page has not been selected
$p->headers
Returns: the http headers to be sent to the client as a list of listrefs of key/val pairs.
$p->orig
Returns: the original url as a Para::Frame::Site::File object.
TODO: Cache object
$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.)
$p->orig_url_path
Returns: The original URL path. Dirs may or may not have a trailing slash.
$p->redirection
Returns the page we will redirect to, or undef.
$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
$p->set_headers( [[$key,$val], [$key2,$val2], ... ] )
Same as /add_header, but replaces any existing headers.
$p->set_header( $key => $val )
Replaces any existing header with the same key.
Returns:
The number of changes
$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.
$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.
$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.
$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.
$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.
$p->set_http_status( $status )
Used internally by /render_output for sending the http_status of the response page to the client.
$p->paths( $burner )
Automaticly called by Template::Provider to get the include paths for building pages from templates.
Returns: /incpath
The standard functions availible in templates. This is called before the page is rendered. You should not call it by yourself.
req object.
returns ($doc, $ext) where $doc is a L<Template::Document> objetct that can be parsed to a L<Para::Frame::Burner> object.
$p->fallback_error_page
Returns a scalar ref with HTML to use if the normal error response templates did not work.
$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
$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.
$p->sender
$p->sender( $code )
$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.
$p->output_redirection( $url )
Internally used by /forward for sending redirection headers to the client.
$p->send_headers()
Used internally by /send_output for sending the HTTP headers to the client.
$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.)