NAME

Apache::Wyrd::Site::Page - Construct and track a page of an integrated site

SYNOPSIS

  <BASENAME::Page
    title="A Random Page"
    tags="random, sample, system"
    description="This is a sample page."
  >
    Body of the page here...
  </BASENAME::Page>

DESCRIPTION

Page is the fundamental unit in the Apache::Wyrd::Site hierarchy. It generates the layout of and the meta-information for a "web page" and informs the index of the site about its self and its relationship to other pages.

Page is usually used to represent a full page of HTML, in a single file, referred to by a single URL which needs to be find-able by other objects on the site. Consequently, it is almost always seen as the outermost Wyrd on a page of HTML. It's attributes are, for the most part, those that a page of HTML may have in it's HEAD section, namely a title, keywords, description, and other meta-data.

An exception is when used as a proxy, in which case it stands in for another file/distinct location of the site, or some grouping of like files. In this behavior, it informs the index about it's original file's meta-data, text, etc. This provides a simple method of overcoming the opaqueness of some file formats to being indexed for word and meta-data content. This is not the default behaviour.

Page is rarely used in its "default" state, meaning that the logic of the layout or construction of a site is best served by working the special behaviors into a subclass of the Page Wyrd. Consequently, the _format_output method of this Wyrd can generally be safely overridden in a subclass, as long as the index's update_entry is called with the page as the argument. (This call is, of course, only necessary if you plan to make use of Pulls and word-search indexing.)

A page is also the parent of and controller of the Widget wyrds which exist on it. Several of the internal methods of the Page Wyrd perform the housekeeping functions for Widgets, and unless Widgets and WidgetControls are used, can be safely ignored.

HTML ATTRIBUTES

name, timestamp, digest, data, children

These are "reserved" attributes which are auto-generated in a format to suit the Apache::Wyrd::Services::Index object. They should not be defined in the HTML. See Apache::Wyrd::Interfaces::Indexable.

parent

The page directly above this one in the navigation-tree hierarchy.

keywords

Key words of the page, used for the keywords meta tag in the header.

description

A description of the page.

published

The publication date in YYYYMMDD format.

section

The section of the site, i.e. first branch of the tree this page belongs to in the navigational hierarcy. See Apache::Wyrd::Site and Apache::Wyrd::Site::NavPull.

allow/deny

Authorization tags. The default Apache::Wyrd::Services::Auth, Apache::Wyrd::User, and related classes operate by checking levels of authorization. Users are assigned levels and what they are allowed to access depend on what levels are required. If "allow" is not set, the page is considered public. If it is, only authenticated users with the security level indicated by the tags are allowed access. If "deny" is set, those users who would normally have access by virtue of the allow value are denied if they match one of the deny tags.

tags

Tokens used to classify the Page by subject matter. These are used by Apache::Wyrd::Site::TagPull to create lists of documents by subject metadata.

original

The location of the document if this page is proxying for another document. For example, if the document is located site-root-relative pdfs/thispdf.pdf, the attribute would be "/pdfs/thispdf.pdf". You would then want to set the doctype to "PDF" so that your pull can indicate that the doctype is PDF, not HTML.

doctype

The type of document (defaults to "HTML").

expires

A date attribute. Not currently used by the default Wyrds in this hierarchy, but often proves useful in determining when something should no longer be considered new.

longdescription

In some pulls, a longer description can be useful. This allows that description to be used, and defaults to the value of "description" when it is not provided.

shorttitle

Especially in NavPulls, the actual title of a page may be too cumbersome. This allows for a shorter alternate.

etc., etc.,

Other indexible attributes may be added in subclasses. Note that the attributes should be given as parameters to the index object (so it knows to look for and store them). If the index object is SQL-type, the attributes should be added to the underlying main table (normaly _wyrd_index), an index_xxxxx method needs to be made to properly supply that value to the index, and either the more_info method be defined to add all the data from these attributes to the data fingerprint, or the index_digest call SUPER::index_digest with the additional data as an argument (single scalar). See Apache::Wyrd::Services::Index and Apache::Wyrd::Interfaces::Indexible.

FLAGS

nofail

If a document is supplied to the "original" attribute and the document does not exist, Page will normally terminate with a fatal error. This forces Page to ignore the error. It's normal use is to allow external sites/documents to be referenced by a Page Wyrd (i.e. by using the full URL).

PERL METHODS

(format: (returns) name (arguments after self))

(void) _init_state (void)

Internal method for initializing the widget substructure.

(scalar) _state_digit (void)

(scalar) _state_symbol (void)

Internal methods for mapping widget states to values

(scalar) _decode_state (void)

(scalar) _encode_state (void)

(scalar) _state_string (void)

Internal methods for interacting with state values

(void) _state_marker (void)

Provides a string of characters which will be globally replaced at runtime in order to maintain state between page-views. All Widget Controls (see Apache::Wyrd::Site::WidgetControl) will need to include this in information submitted to the next page view in order to maintain consistent state between page views.

(void) _set_state (void)

The process by which the placemarker for the current state (once built) is inserted into the page final body. The default is to use a s/// regular expression.

(void) get_state (void)

This method is called by Widgets on the page to determine their overall state. The widget passes a reference to itself as the argument of the method. The Page Object uses this method to obtain information on Widgets on the page in order to track their current state and to give their controls a switch to use to pass as a CGI variable in order to manipulate this state, changing the attributes of the Widget.

(void) _read_widget_state (void)

The function by which each widget is assigned widget controls and records which values those widget controls have. Additionally, what encoding the widget controls will pass as CGI variables in order to manipulate their respective widget's state are generated during this attribute/value permutation count.

(scalar) _check_auth (void)

Examine the allow/deny state of the page and determine whether the user has the clearance to view the page. These interact with Apache::Wyrd::User-derived objects using the Apache::Wyrd::Services::Auth conventions to determine the user's current authorization levels. If the page is forbidden to the public, it will use the dir_config value "UnauthURL" to direct them to an "unauthorized page", presumably to be prompted to log in, or failing the existence of that, simply return an error message.

(scalar) _override_auth_conditions (void)

Override the default authorization behavior. The default behavior is to check the id against the dir_config values for "trusted_ipaddrs", a whitespace-separated list.

(scalar) _unauthorized_text (void)

The error message to be returned when no UnauthURL is set.

(void) _page_edit (void)

A hook method for pages which interact with some sort of content management editing facility.

(void) _process_template (void)

A hook method for how to assemble the body section of the page from the template. Defaults to replacing the string _INSERT_TEXT_HERE_ with the enclosed text.

(array) _attribute_list (void)

(array) _map_list (void)

List of those attributes supported by this Page object that are tracked in the the attributes of the Index object that supports it. The default is to use the Index object's attribute and map lists, respectively. See qw(Apache::Wyrd::Site::Index) and qw(Apache::Wyrd::Services::Index).

(scalar) index_digest (void)

As in Apache::Wyrd::Interfaces::Indexable, provides the raw data to be considered in generating the "fingerprint" that is used to determine if this page has been changed, and consequently requires re-indexing.

(scalar) more_info (void)

A hook method for adding information to the fingerprint for index_digest.

(scalar) index_* (void)

Methods used to provide this fingerprint data, per Apache::Wyrd::Interfaces::Indexable.

One of the default methods provided in this class is index_children, which also provides for the arbitrary order of children of a parent. See Apache::Wyrd::Site::NavPull for an explanation of this feature.

Also by default, the index_name method will return the "original" attribute if set, to allow the page to proxy for another document.

BUGS/CAVEATS

Reserves the _format_output and _generate_output methods.

AUTHOR

Barry King <wyrd@nospam.wyrdwright.com>

SEE ALSO

Apache::Wyrd

General-purpose HTML-embeddable perl object

Apache::Wyrd::Services::Index

Apache::Wyrd::Services::MySQLIndex

Apache::Wyrd::Site::Index

Apache::Wyrd::Site::MySQLIndex

Various index objects for site organization.

Apache::Wyrd::Site

Documentation about this sub-hierarchy

LICENSE

Copyright 2002-2007 Wyrdwright, Inc. and licensed under the GNU GPL.

See LICENSE under the documentation for Apache::Wyrd.