NAME

Apache::Wyrd::Site::Widget - Abstract dynamic element of a page

SYNOPSIS

  package BASENAME::SampleWidget;
  use base (Apache::Wyrd::Site:::Widget);

  sub _format_output {
    my ($self) = @_;
    my $text = '';
    #...
    ##---generate some occasionally-changing content here---
    #...
    $self->_data($text);
  }
  ....

  <BASENAME::Page>
    <BASENAME::SampleWidget />
  </BASENAME::Page>

DESCRIPTION

Widgets are a generic class of objects which work with Apache::Wyrd::Site::Page Wyrds, primarily to generate content on a page which may change through time and viewings. This makes the indexing of pages problematic, since a Page object by default looks only to its own file modification date to determine if it has been changed and needs re-indexing. A Widget will keep track of its own content in a similar way as the page (see Apache::Wyrd::Site::WidgetIndex), triggering an update in its parent Page Wyrd when it's content changes. It does this by changing the (internal) modification time value of the parent to the current time as defined by the builtin time() call.

So, if you want content from external sources to be indexed as a page is indexed, the wyrd which generates the content should be a sub-class of Apache::Wyrd::Site::Widget.

HTML ATTRIBUTES

name/title

All widgets MUST have either a title or a name attribute, as required by the WidgetIndex. Without one or the other, widgets may erroneously trigger a re-index of the Page object.

PERL METHODS

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

(Apache::Wyrd::Site::WidgetIndex ref) index (void)

Returns a Widget Index reference. If the package <BASENAME>::Site::WidgetIndex exists, it will attempt to call new() to get this reference. If not, it will assume that the widget index should be located in the /var directory under the document root. It is recommended that a subclass of this object initializes the WidgetIndex explicitly.

(void) index_digest (void)

Returns a fingerprint of the content (using sha1_hex by default) for storage in the index. For internal use.

(void) index_name (void)

Returns the indexable name of the widget for storage in the index. For internal use.

(void) _change_state (void)

If the widget makes use of Widget controls (Apache::Wyrd::Site::WidgetControl), their state is found and set by the Page Wyrd by calling this method. Widgets should call _change_state() during the _format_output phase. This method does nothing other than call the parent's get_state method (see Apache::Wyrd::Site::Page) and immediately follow it by a call to it's own _set_children method (see Apache::Wyrd::Interfaces::Mother).

If, however, the widget must make a decision more complicated than a simple radio-button-style switch between alternate values for given attributes, it should first call get_state to change the value of it's attributes to reflect the current input of the Widget Controls, then having made any adjustments based on this input, should call _set_children after these adjustments are made.

(void) _process_child (void)

Sets the default attributes for the widget from the Widget Controls. The first Widget Control will provide a value for it's attribute if it has not been set in the Widget Object already. Any Widget Controls flagged "default" will override the current value, with priority to the last one so flagged.

BUGS/CAVEATS

Reserves both the _setup and _generate_output methods.

AUTHOR

Barry King <wyrd@nospam.wyrdwright.com>

SEE ALSO

Apache::Wyrd

General-purpose HTML-embeddable perl object

Apache::Wyrd::Index

General-purpose metadata index

Apache::Wyrd::Page

Base Wyrd for Web site pages

LICENSE

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

See LICENSE under the documentation for Apache::Wyrd.