view release on metacpan or  search on metacpan

Wyrd.pm  view on Meta::CPAN

The collection is not meant to be a drop-in replacement for PHP,
ColdFusion, or other server-side parsed content creation systems, but to
provide a more flexible framework for organic custom perl development
for an experienced perl programmer who favors an object-oriented
approach.  It has been designed to simplify the transition from static
to dynamic web content by allowing the design of objects that can be
operated by a non-perl programmer through the modification of the HTML
page on which the content is to be delivered.

The Apache::Wyrd module itself is an abstract class used to create
HTML-embeddable perl objects (I<Wyrds>).  The embedded objects are
interpreted from HTML files by an instance of the abstract class
C<Apache::Wyrd::Handler>. Most Wyrds also require an instance of an
C<Apache::Wyrd::DBL> object to store connection information and to
provide intermediary access to the Apache request and any DBI-style
database interfaces.

Each Wyrd has a corresponding perl module which performs work and
generates any output at the Wyrd's location on the HTML page.  Each
of these objects is a derived class of Apache::Wyrd, and consequently
draws on the existing methods of the abstract class as well as
implements methods of its own.  A few "hook" methods (C<_setup>,
C<_format_output>, and C<_generate_output> in particular) are defined in
the abstract class for this purpose.

The modules in this distribution are not meant to be used directly.
Instead, instances of the objects are created in another namespace (in
all POD synopses called BASENAME, but it can be any string acceptable as
a single namespace of a perl class) where the Handler object has been
configured to use that namespace in interpreting HTML pages (see
C<Apache::Wyrd::Handler>).

=head2 SETUP

At the minimum, BASENAME::Wyrd needs to be defined, C<BASENAME::Handler>
needs to be defined and properly configured and able to properly invoke
an instance of C<BASENAME::DBL>.  [N.B: A sample minimal installation,
C<TESTCLIENT> can be found in the t/lib directory of this package].

When a BASENAME::FOO Wyrd is invoked, and no BASENAME::FOO perl object can
be found, the object Apache::Wyrd::FOO will be tried.  This allows the use
of any Apache::Wyrd::FOO objects derived from this module to be used in a
web page as BASENAME::FOO objects without explicitly subclassing them.  If
neither a BASENAME::FOO nor an Apache::Wyrd::FOO object exists, a generic
(do-nothing) Apache::Wyrd object will be used rather than an error occur.

As one would expect, one namespace can also instantiate another namespace's
objects as long as the other namespace can be found in the local perl
installation's @INC array.

=head2 SYNTAX IN HTML

Wyrds are embedded in HTML documents as if they were specialized tags. 
These tags are assigned attributes in a manner very similar to HTML
tags, in that they are formed like HTML tags with named attributes and
(optionally) with enclosed text, i.e.:

    <NAME ATTRIBUTENAME="ATTRIBUTE VALUE">ENCLOSED TEXT</NAME>

They follow the XHTML syntax somewhat in that they require a terminating
whitespace followed by a forward-slash (/) before the enclosing brace
when they are embedded as "stand-alone" tags, and require quotes around
all attributes. Therefore:

    <BASENAME::WyrdName name=imasample>

must either be written:

    <BASENAME::WyrdName name="imasample"></BASENAME::WyrdName>

or as:

    <BASENAME::WyrdName name="imasample" />

to be valid.  Invalid Wyrds are ignored and do not get processed, but
may cause errors in other Wyrds if malformed, so it often pays to "view
source" on your browser while debugging.

Unlike (X)HTML, however, Wyrds are named like perl modules with the double-colon
syntax (BASENAME::SUBNAME::SUBSUBNAME) and these names are B<case-sensitive>. 
Furthermore, either single or double quotes MUST be used around attributes, and
these quotes must match on either side of the enclosed attribute value.  Single
quotes may be used, however, to enclose double quotes and vice-versa unless the
entire attribute value is quoted.  When in doubt, escape quotes by preceding
them with a backslash (\).  B<HTML tags should not appear inside attributes.> 
See C<Apache::Wyrd::Template> and C<Apache::Wyrd::Attribute> for common ways
around this limitation.

Also unlike (X)HTML, one Wyrd of one type cannot be embedded in another of the
same type.  We believe this is a feature(TM).

=head2 LIFE CYCLE

The "normal" behavior of a Wyrd is simply to disappear, leaving its enclosed
text behind after interpreting all the Wyrds within that text.  It is through
"hook" methods that manipulation and output of perl-generated material is
accomplished.

Just as nested HTML elements produce different outcomes on a web page depending
on the order which they are nested in, Wyrds are processed relative to their
nesting.  The outermost Wyrd is created (with the C<new> method) first from a
requested page and processes its enclosed text, spawning the next enclosing tag
within it, and so on.  When the final nested Wyrd is reached, that Wyrd's
C<output> method is called and the resulting text replaces it on the page.  The
C<output> method of each superclosing tag is called in turn, repeating the
process.  Between C<new> and C<output> are several stages.  In these stages,
"hooks" for Wyrd specialization are called:

=over

=item 1.

C<new> calls C<_setup> which allows initialization of the Wyrd B<before> it
processes itself, spawning enclosed Wyrds.

=item 2.

C<_setup> returns the object, which waits for the C<output> call to be
performed on it by it's parent or by the Handler.