Developers > Kernel Documentation > Content Management > Page.pm

Page.pm



ExSite::Page - templated page generation and management

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:

ExSite::Content
ExSite::ContentData
ExSite::ContentBase

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.


Configuration & Setup

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:

id
The numeric page ID will be used to fetch the page description from the database.

page
The page record can be passed as a hash reference, if it has already been fetched.

section_id, filename
Given a section_id and filename, the page can be looked up in the database.

path
The section path and filename can be specified as a text string, eg. ``/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.

(null)
If no page description is provided, the object will reuse any previously loaded page info, if present. Otherwise it will configure an empty page object that will have limited functionality.

The following additional options are also accepted:

version
An alternate version of the page may be specified (see set_version(), below).

cms
If this parameter is true and we have CMS permissions to manage this page, we will select the latest working revisions of content for display. Otherwise we select the current approved revisions.

publish
Set this flag to 1 if the page is publishing. This is used to distinguish between dynamic and static page views.

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.


Page Attribute Queries

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.


Access Controls

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.


Displaying Pages

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.


Page Location

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.


Content Management

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.


Publishing

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.


Page Relationships

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


Creating/Modifying Pages

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.

Topics