view release on metacpan or  search on metacpan

Wyrd.pm  view on Meta::CPAN

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.

=item 3.

When the C<output> method is called, it processes itself, meaning that
it goes through the enclosed text (if any), finding embedded Wyrds. 
When such a Wyrd is found, it spawns a new object based on itself,
inheriting the same C<Apache::Wyrd::DBL>, the same C<Apache> request
object, the same loglevel (see attributes, below), and so on.  Prior to
spawning, the hook method C<_pre_spawn> is called to allow changes to
the new Wyrd before it is created.

=item 4.

C<output> then calls the two hooks, C<_format_output> which is meant to handle
changes to the enclosing text and C<_generate_output> which returns the actual
text to replace the Wyrd at that point in the HTML page.

=back

In most cases, there will not be any need to override non-hook methods.  For minor variations on Wyrd behavior, most
of the built-in Wyrds can be quickly extended by overriding the method with a method that calls the SUPER class:

  sub _setup {
    my $self = shift;
    
    ...do something here...
    
    return $self->SUPER::_setup();
  }

=head2 HTML ATTRIBUTES

Any legal attribute can generally be used.  Some, however, are important
and are be reserved.

=head3 RESERVED ATTRIBUTES

=over

=item loglevel

A value, defining the degree to which the Wyrd will spew debugging
information into STDERR (normally the Apache error log).  You may use
the keywords C<fatal>, C<error>, C<warn>, C<info>, C<debug>, and
C<verbose> or their corresponding numerical value (0-5).

=item dielevel

The degree of error which will trigger a server error.  Corresponds to
the loglevels and defaults to 'fatal'.

=item flags

A list of optional modifiers, separated by whitespace or commas, which
can be used to modify the behavior of the Wyrd.  Flags should contain no
whitespace.  One builtin flag exists: B<disable> keeps the Wyrd and all
enclosed data from being processed or generated at all.

=back

Additionally, any attributes corresponding to the reserved public
methods below will be discarded.

=head3 PRIVATE ATTRIBUTES

=over

Any attribute beginning with an underline is reserved  for future
development. Two of these are created at the time of generation which
are particularly important and deserve mention:

=item _data

At the time of spawning a new Wyrd, the enclosed text is stored in the
attribute _data.  This attribute is the data processed during the first
phase of the C<output> method, and is available to the hook methods.  If
one hook method changes this value, however, it is important that the
other hooks take this into account.  The default C<_generate_output>
simply returns this value, for example.

=item _flags

Also at the time of spawning, the flags attribute is translated into an
C<Apache::Wyrd::Services::Tree> object.  This object is used to keep
track of whether a flag is set or not, for example:

    $self->_flags->reverse;