title()description()keywords()is_active()is_template()is_library()is_page()is_public()is_homepage()is_publishable()is_published()is_publishing()timestamp()filename()httppath()diskpath()get_url()get_url_canonical()get_url_static()get_url_dynamic()link()
The Page class handles the storage, retrieval, templating, assembly,
and dispatch of web pages. It is part of the ExSite content stack, so
it inherits from ExSite::Content, and is in turn inherited by
ExSite::Section. It provides a more sophisticated page-building
model than the older ExSite::PageBuf class.
The Page class also handles templates and libraries, which are special cases of the general page object. In all of these cases, a page is a ``container'' that holds content, so there is a lot of common functionality, even though conceptually they may seem quite different.
ExSite::Page inherits from:
Many important methods are actually drawn from these classes,
especially content-handling and assembly methods, which are inherited
from ExSite::ContentBase and used by all classes in the content
stack.
new()(This method is actually inherited from ExSite::ContentBase.)
setup()
setupPage()Instantiate and/or configure a page object. %option includes the
the configuration parameters, described below.
Usage:
my $page = new ExSite::Page(%option);
$page->setup(%option);
$page->setupPage(%option);
setup and setupPage are synonymous; they are used to setup or
reconfigure an existing Page object. new() instantiates a new page
object (this method is actually inherited from ExSite::ContentBase).
%option is used to pass the page description information that
allows the object to be configured. It can include the following page
description parameters:
/section/subsection/filename.html''. With this information, ExSite
can locate the page in the database, although the lookup is more costly
than other methods, above.
The following additional options are also accepted:
set_version(),
below).
If the page is not set up with an actual page description, the object
will have limited functionality. The setup methods are normally invoked
automatically by the class constructor method new(), which receives the
same %option parameters.
set_version()Usage:
$page->set_version($version);
Switches to an alternate version of the page. Versions are
alternative presentations of the same content, and are typically used
to provide a page in alternate languages. $version is a version
name (eg. ``Chinese'') used to find the alternate version. If there is
no such alternate page tied to the current page, the default version
of the page is used. For instance, if we request the Chinese version
of the home page in a certain site, but no Chinese version of that
page exists, then we use the default home page (for instance, the
English index.html) instead.
title()Returns the page title as a simple string.
description()Returns the page description as a simple string.
keywords()Returns the page keywords as a simple string.
is_active()Returns TRUE if the page can be served, ie. it has not been disabled in the CMS.
is_template()Returns TRUE if the page is a template.
is_library()Returns TRUE if the page is a library.
is_page()Returns TRUE if the page is a normal web page, ie. a destination URL for website visitors. This is true for pages of type ``page'' and type ``alternate''.
is_public()Returns TRUE if the page is viewable by unauthenticated members of the public.
is_homepage()Returns TRUE if the page is the default homepage for the section, ie. it is an index page with an appropriate suffix.
is_publishable()Returns TRUE if the page can be published to publicly-viewable files.
is_published()Returns TRUE is the page actually has been published, ie. it has no content that is younger than the page filename's mtime flag.
is_publishing()Returns TRUE if the page is currently publishing, ie. writing itself out to publicly-viewable files. This method is usually used to detect when the page should assume no special access permissions, even though the current user is an administrator who has full access.
timestamp()Returns a timestamp that gives the age of the page. The timestamp is defined as the most recent of the timestamps of the page's template, the page record itself, and the content objects in the page. The timestamp is a database timestamp, eg. a MySQL timestamp.
is_valid()Returns TRUE if the page belongs to the site the URL claims. Valid pages are those that belong to the site they are invoked from. Ie. if site x.com owns page 98 and site y.org owns page 99, then the url http://x.com/cgi/page.cgi?_id=99 is not valid.
However, if the user owns the page/site then we allow them to inspect it from anywhere. (This allows them to preview their pages from a webservice CMS, for instance.) System administrators can view any pages from anywhere.
authorize()Returns TRUE if the viewer is permitted to see the page contents in a dynamic page view. FALSE will normally be returned if the user is not a site member but is attempting to view a members-only page, or if the user is not an administrator and is attempting to view an administrators-only page.
show()Dispatches the page to the viewer. First it sends any headers that have been accumulated by the page, then it performs all CMS content expansions and substitutions, and finally it dumps the page contents to stdout.
cancel()Aborts the page, so that no contents will be displayed to the viewer. This is typically used if the page is superceded by a redirection.
header()Usage:
$page->header($hdr);
Adds the HTTP header line in $hdr to the list of header directives
that should be sent with this page. No validation of $hdr is performed.
show_headers()Dispatches the accumulated headers for the page to the viewer. If there is no content-type header, one is added.
redirect()Same as...
location()Usage:
$page->redirect($url);
Cancels the current page, and redirects the viewer to the specified URL. The redirection is performed by issuing a Location: header.
errorpage()Usage:
$page->errorpage($html);
Cancels the current page, and generates an error page in its place.
$html contains the error message.
This will attempt to use a special _ERROR template to format the page if the section has such a template defined. If not, the error message will be issued ``bare'', ie. without any wrapper template.
This method is called if there is any problem generating the page as requested. Most commonly, this occurs when a non-member attempts to view a members-only page. The error message in this case is the login prompt.
filename()Returns the publication name of the page. For regular pages, this is
the filename; for templates and libraries, it is the directory name.
The bare name is returned; see diskpath() if a full path is needed.
The filename is processed by ExSite::Misc::clean_filename() to
removed sensitive shell characters. If the page does not have a
filename (should not normally occur), a filename based on the page ID
will be generated.
Note that the return value may not refer to an actual file if the page is always rendered dynamically.
httppath()Returns the web path to the static page file. This is the part of the static URL after the domain name. For templates and libraries this returns the folder containing the template and library files. For normal pages, this returns the folder for the current section.
Note that the return value may not refer to an actual file if the page is always rendered dynamically.
diskpath()my $path = $page->diskpath($dir_only);
Returns the server disk path to the static page file. This returns the path to the page's file if it is a normal page and $dir_only is not TRUE. Otherwise it returns the path to the directory that the files are written to (ie. the section directory, template directory, or library directory, as appropriate).
Note that the return value may not refer to an actual file if the page is always rendered dynamically.
get_url()Return the URL to the page. If the page is static, it checks to make sure the page has actually been published before returning a static URL. If not, then a dynamic URL is returned instead, to ensure that the URL will actually generate a meaningful result.
get_url_canonical()Returns the correct public URL to the page. This simply means that if the page is supposed to be static, then the static URL is always returned, even if the page has not yet been published.
get_url_static()Returns the static URL to a page. This may not be a valid URL if the page is configured to only render dynamically.
get_url_dynamic()my $url = $page->get_url_dynamic($path_method);
Returns the dynamic URL to a page. If $path_method is TRUE, then
the URL is of the form:
/cgi/page.cgi/section/page.html
Otherwise, the URL is of the form:
/cgi/page.cgi?_id=123
link()my $url = $page->link(%args);
Generates a URL to a dynamic view of a page, including any optional
query parameters that are given in %args. It is thus analagous to
ExSite::BaseDCD::link() in usage.
fetch_all_content_objs()my @content = $page->fetch_all_content_objs(%options);
Returns an array of content objects for each content item defined
within the current page. The %options are passed to the new()
method when instantiating each content object.
edit_content_link()Generates a hotlink to allow the administrator to edit the contents of the current page. This is inserted into the page content so that the content can be edited directly from a page preview.
The result of following this link depends on the setting of
$config{page}{editmode}. For instance, it may invoke the Website
Manager or MySite CMS applications.
set_template()
$page->set_template($template);
Changes the template of the current page to $template (which may be
a template ID or a template record hashref), if permitted.
set_body()$page->set_body($body);
Changes the body of the current page to $body (which may be a
content ID or a content record hashref), if permitted. This is used
to copy content from a model body into the current page. To simply
update the page body, use ExSite::Content::update() on the body
object.
publish()Write a page and its files out to disk, and mark all of its content as published.
Publishing is equivalent to ``approving for public view'', so pages and content that do not get written to static files can still be published.
In some cases, dynamic pages and templates can be published to static files. The purpose in this case is to precompile the page/template so that less assembly is required at the actual time of page view. Dynamic page generation will begin from the precompiled file, rather than from scratch. Although the precompiled pages can in principle be viewed using static URLs, the pages will include unresolved CMS tags, and ExSite will not create links to those files.
If $config{search}{reindex_on_publish} is TRUE, the search index
for the page may also get rebuilt at this time.
WARNING: you need write access to the page's diskpath() to publish
files there. The webserver normally does not have this access.
Negotiating this access is normally done by the publish program
(ie. publish.cgi), which has special permissions. If you do not have
these permissions, then you have to ask publish.cgi to do this task on
your behalf, using ExSite::Util::run_publisher().
unpublish()Removes a page's files from disk. Also deindexes the page from the
search index, if $config{search}{reindex_on_publish} is TRUE. Does
not, however, unapprove the page content for public viewing. See
publish() for other warnings.
get_child_pages()my @child_pages = $page->get_child_pages($version);
Returns an array of page objects representing the children of this
page (ie. all pages in a submenu of this page). If $version is
specified, then the fetched pages will be of that version
(eg. language), if they exist, or the default version otherwise.
parent()Returns the parent page as a page object. This is the page whose submenu the current page belongs to.
master()Returns the master version (ie. the default version) of the current page. This will be the page itself, unless the page type is ``alternate''.
NB: modifying means changing the page attributes, not updating the page
content. The latter operation is done by calling the update()
method of the particular content object being updated.
validate()my @errors = $page->validate($pagedata);
if (@errors == 0) { # page is OK }
Returns TRUE if the values in the the $pagedata hashref comprise a
valid and legal page description. Returns an array of error messages,
which will be empty if the page data validates.
is_dupe() if ($page->is_dupe($pagedata)) { # similar page already exists }
Returns TRUE if the pagedata has identical publication characteristics
(ie. same filename, page type, and section) to an existing page in the
system. Called automatically by validate().
make()
make_page()$page->make($pagedata,$body,$opt);
Creates a new page, with the attributes given in the $pagedata
hashref. If the user is permitted to make pages and the attributes
validate, then the page record will be created.
If $body is defined, then a ``body'' content object will be created
in the new page, and initialized to the content in $body (presumed
to be HTML). $opt is an options hashref that is passed to
ExSite::Content::make() when the body is created.
delete()Removes the current page from the system. Attempts to unpublish its files, as well.