ASP4x-Linker

 view release on metacpan or  search on metacpan

Changes  view on Meta::CPAN

2012-02-03      v1.001
  - Added chained widget-attribute-setters.
    $widget->set(foo => 'bar', ...)->uri();
    $widget->set(%args)->set(%more_args)->uri();
  - Thanks to eric.hayes++ for the suggestion.

2011-05-01      v1.000
  - $widget->set( non_existent_attribute => "value" ) will result in an exception.
  - Simplified the documentation for ASP4x::Linker - the simplified style of
    $linker->widget(...)->get/set(...) interface is very much preferred.
  - API has otherwise remained unchanged for over a year.  Time to go v1.000!!!

2010-05-13      v0.003
  - Now, $linker->uri({foo => 'bar'}) returns a uri with foo=bar in there someplace.
  - Upgrade recommended.

2010-04-01      v.0.002
  - Added vars() method.
  - Updated docs.
  - Removed AUTOLOAD behavior from Widget and Linker.
  - Added $widget->get( $attr ) and $widget->set( $attr => $value )
  - Added $widget->on_change( $attr => sub { ... } )
  - Added several tests.

2010-04-01      v0.001
  - Initial release.
  - No joke!

lib/ASP4x/Linker.pm  view on Meta::CPAN

  my $linker = ASP4x::Linker->new();
  -or be more specific-
  my $linker = ASP4x::Linker->new( base_href => "/whatever.html" );
  
  # Add a widget:
  $linker->add_widget(
    name  => "widgetA",
    attrs => [qw( page_size page_number sort_col sort_dir )]
  );
  
  # If the page size is changed, go back to page 1:
  $linker->widget("widgetA")->on_change( page_size => sub {
    my ($s) = @_;
    $s->set( page_number => 1 );
  });
  
  # Add another widget:
  $linker->add_widget(
    name  => "widgetB",
    attrs => [qw( keywords tag start_date stop_date )]
  );
  

lib/ASP4x/Linker.pm  view on Meta::CPAN

widgets and then call C<< $linker->uri() >> to get the resultant uri to match.

  $linker->widget("widgetA")->set( page_number => 2 );
  $uri = $linker->uri;
  # $uri is now "/some-page.asp?widgetA.page_number=2"

=head1 DESCRIPTION

C<ASP4x::Linker> aims to solve the age-old problem of:

B<How do I change one widget on the page without losing my settings for all the other widgets on the page?>

OK - say you have one data grid on your web page that allows paging and sorting.  You can move forward and backward between
pages, change the sorting - life's great.  B<THEN> your boss says:

  We need to have two of those on the same page.  One for Albums and one for Genres.

Now you have 2 options.

=over 4

B<Option 1>: If a user pages "Albums" to page 4, then pages "Genres" to page 2, you forget that "Albums" was on page 4.

B<Option 2>: Use ASP4x::Linker.  Register 2 "widgets" (albums and genres) and let the linker know that they both have C<page_number>, C<page_size>, C<sort_col> and C<sort_dir> attributes.
When the user makes paging or sorting changes in Albums, the stuff for Genres will persist between requests without any extra effort.

=back

=head1 CONSTRUCTOR

=head2 new( [ base_href => $ENV{REQUEST_URI} ] )

Returns a new C<ASP4x::Linker> object using the supplied C<base_href> value as the "starting point"
for all links that will be generated.

lib/ASP4x/Linker/Widget.pm  view on Meta::CPAN

sub linker
{
  my $s = shift;
  @_ ? $s->{linker} = shift : $s->{linker};
}# end linker()


sub uri { shift->linker->uri }


sub on_change
{
  my ($s, $attr, $code) = @_;
  
  return unless exists( $s->{vars}->{$attr} );
  $s->{triggers}->{ $attr } ||= [ ];
  push @{ $s->{triggers}->{ $attr } }, $code;
}# end on_change()

sub DESTROY { my $s = shift; undef(%$s); }

1;# return true:

=pod

=head1 NAME

ASP4x::Linker::Widget - A single item that should be persisted via links.

lib/ASP4x/Linker/Widget.pm  view on Meta::CPAN

  my $widget = $linker->widget('albums');
  
  # Change some attributes:
  $widget->set( page_size   => 10 );
  $widget->set( page_number => 4 );
  
  # Get the value of some attributes:
  $widget->get( 'page_size' );    # 10
  $widget->get( 'page_number' );  # 4

  # Make page_number reset to 1 if the page_size is changed:
  $widget->on_change( page_size => sub {
    my $s = shift;
    $s->set( page_number => 1 );
  });
  
  $widget->set( page_size => 20 );
  print $widget->get( 'page_number' );  # 1
  
  # Set multiple values at once:
  $widget->set( %args );
  

lib/ASP4x/Linker/Widget.pm  view on Meta::CPAN

=head2 set( $attr => $value )

Changes the value of an attribute to a new value.

B<NOTE:> As of version , attempts to apply a value to a non-existant attribute will result in a runtime exception.

=head2 get( $attr )

Returns the current value of the attribute.

=head2 on_change( $attr => sub { ... } )

Adds a trigger to the widget that will be called when the given attribute's value is changed via C<set()>.

=head2 uri()

Just a wrapper around the widget's parent C<ASP4x::Linker> object.

=head1 SEE ALSO

L<ASP4x::Linker>

=head1 AUTHOR

t/010-basic/060-widget-triggers.t  view on Meta::CPAN

my $linker = ASP4x::Linker->new();

my $widget = $linker->add_widget(
  name  => 'artists',
  attrs => [qw( page_number page_size )]
);

ok( $widget, "Got widget" );

# Reset the page number to '1' when the page size is updated:
$widget->on_change( page_size => sub {
  my $s = shift;
  $s->set( page_number => 1 );
});

is( $linker->uri => '/?artists.page_number=4&artists.page_size=10' );
$widget->set( page_size => 20 );
is( $linker->uri => '/?artists.page_number=1&artists.page_size=20' );