view release on metacpan or  search on metacpan

Wyrd/Site/Widget.pm  view on Meta::CPAN

package Apache::Wyrd::Site::Widget;
use strict;
use warnings;
our $VERSION = '0.98';
use base qw(Apache::Wyrd::Interfaces::Indexable Apache::Wyrd::Interfaces::Mother);
use Digest::SHA qw(sha1_hex);

=pod

=head1 NAME

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

=head1 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>

=head1 DESCRIPTION

Widgets are a generic class of objects which work with
C<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 C<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 C<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
C<Apache::Wyrd::Site::Widget>.

=head2 HTML ATTRIBUTES

=over

=item 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.

=back

=head2 PERL METHODS

I<(format: (returns) name (arguments after self))>

=over

=item (Apache::Wyrd::Site::WidgetIndex ref) C<index> (void)

Returns a Widget Index reference.  If the package
E<lt>BASENAMEE<gt>::Site::WidgetIndex exists, it will attempt to call
C<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.

=cut

sub index {
	my ($self) = @_;
	return undef if ($self->_flags->noindex);
	$self->_error("Widgets are better written by subclassing Apache::Wyrd::Site::Widget and defining an index() method as an interface that returns a WidgetIndex for your site.");
	my $formula = $self->base_class . '::Site::WidgetIndex';
	eval ("use $formula") unless ($INC{$formula});
	my $index = undef;
	if ($@) { #assume a failed compile means no WidgetIndex is defined
		$index = Apache::Wyrd::Site::WidgetIndex->new({file => $self->dbl->req->document_root . '/var/widgetindex.db'});
	} else {
		eval ('$index=' . $formula . '->new()');
	}
	return $index;
}

=item (void) C<index_digest> (void)

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