view release on metacpan or  search on metacpan

lib/Backed_Objects.pm  view on Meta::CPAN

=head2 select

This method returns an object from the DB or C<undef> if the ID is absent
(undefined or zero).

See its implementation:

  sub select {
    my ($self, $id) = @_;
    return undef unless $id;
    return $self->do_select($id);
  }

=cut

sub select {
  my ($self, $id) = @_;
  return undef unless $id;
  return $self->do_select($id);
}

=head2 do_insert, do_update, do_delete, post_process

By default these methods do nothing. (In this case you need to update database
yourself, before calling C<insert>, C<update>, or C<delete> methods.)

You may override these methods to do database updates:

  sub do_insert {
    my ($self, $obj) = @_;
    my @keys = keys %$obj;
    my @values = values %$obj;
    my $set = join ', ', map { "$_=?" } @keys;
    $dbh->do("INSERT table SET $set", undef, @values);
    $obj->{id} = $dbh->last_insert_id(undef, undef, undef, undef);
  }

  sub do_update {
    my ($self, $obj) = @_;
    my @keys = keys %$obj;
    my @values = values %$obj;
    my $set = join ', ', map { "$_=?" } @keys;
    $dbh->do("UPDATE table SET $set WHERE id=?", undef, @values, $obj->{id});
  }

  sub do_delete {
    my ($self, $id) = @_;
    $dbh->do("DELETE FROM table WHERE id=?", undef, $id);
  }

  sub post_process {
    my ($self, $obj) = @_;
    ...
  }

C<do_insert> should set object ID after it is saved into the database.

C<post_process> is called by C<insert> after the object is inserted into
the database (and the object ID is set). It can be used for amending the
object with operations which require some object ID, for example for
uploading files into a folder with name being based on the ID.

C<post_process> is also called by C<update>.

=cut

sub do_insert { }
sub do_update { }
sub do_delete { }
sub post_process { }

=head2 outputter

This method should return a value used to output a view of the DB
(for example it may be used to output HTML files and be a hash whose values
are HTML templates).

Example:

  use File::Slurp;

  sub outputter {
    my ($self) = @_;
    my $template_dir = "$ENV{DOCUMENT_ROOT}/templates";
    return { main_tmpl => read_file("$template_dir/main.html"),
             announce_tmpl => read_file("$template_dir/announce.html") };
  }

The default implementation returns C<undef>.

=cut

sub outputter { }

=head2 insert, update, delete

  HTML_DB->insert($obj);
  HTML_DB->update($obj);
  HTML_DB->delete($id);

These functions update the view based on the value C<$obj> from the DB.
They are to be called when an object is inserted, updated, or deleted in
the DB.

If you've overridden the C<do_insert>, C<do_update>, or C<do_delete> methods,
then C<insert>, C<update>, or C<delete> methods update the database before
updating the view.

Note that C<insert> methods calls both C<on_update> and C<on_insert> methods
(as well as some other methods, see the source).

C<insert> and C<update> also call C<post_process>.

C<update> also calls C<before_update> before calling C<do_update>.
The C<before_update> method can be used to update the data based on
old data in the DB, before the DB is updated by C<do_update>.

=cut

# Calls both on_update() and on_insert()
sub insert {

lib/Backed_Objects.pm  view on Meta::CPAN

# Is it better to first call output_all and then on_order_change, or the reverse
sub output_all_and_order {
  my ($self) = @_;
  $self->output_all;
  $self->on_order_change;
}

=head2 save

  HTML_DB->save($obj);

This saves an object into the DB: updates it if it is already in the DB
(has an ID) or inserts it into the DB if it has an undefined ID.

The actual code:

  sub save {
    my ($self, $obj) = @_;
    if($self->id($obj)) {
      $self->update($obj);
    } else {
      $self->insert($obj);
    }
  }

=cut

sub save {
  my ($self, $obj) = @_;
  if($self->id($obj)) {
    $self->update($obj);
  } else {
    $self->insert($obj);
  }
}

=head2 output

An internal function.

=cut

sub output {
  my ($self, $outputter, $obj, $update) = @_;
  die "Object has no ID!" unless $self->id($obj);
  $self->do_output(scalar($outputter), $obj, $update);
}

=head1 AUTHOR

Victor Porton, C<< <porton@narod.ru> >>

=head1 BUGS

Please report any bugs or feature requests to C<bug-backed_objects at rt.cpan.org>, or through
the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Backed_Objects>.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.

In the current version of C<Backed_Objects> there are no provision for passing
file handles for example got from a HTML form with a C<file> control.
A complexity is that usually to upload a file we need to already know the
ID of a row in a database what is possible only I<after> inserting into the DB.
Your suggestions how to deal with this problem are welcome.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Backed_Objects


You can also look for information at:

=over 4

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Backed_Objects>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Backed_Objects>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Backed_Objects>

=item * Search CPAN

L<http://search.cpan.org/dist/Backed_Objects/>

=back

=head1 LICENSE AND COPYRIGHT

Copyright 2011 Victor Porton.

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.


=cut

1; # End of Backed_Objects