/ 
ASP4x-Linker-1.000
River stage zero No dependents
/ ASP4x::Linker

NAME

ASP4x::Linker - In-page persistence of widget-specific variables.

SYNOPSIS

Setup

(Within /some-page.asp)

use ASP4x::Linker;

# Create our linker:
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 )]
);

Setting Variables

Since the $linker starts out with only the variables found in $ENV{REQUEST_URI} or in the base_href argument, calling $linker->uri() on a new linker object will return the same uri that you are currently on (eg: /some-page.asp

To generate links that contain specific attributes, set the attributes for those widgets and then call $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"

DESCRIPTION

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

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

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

    Option 2: Use ASP4x::Linker. Register 2 "widgets" (albums and genres) and let the linker know that they both have page_number, page_size, sort_col and 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.

CONSTRUCTOR

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

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

If no base_href is provided, the value of $ENV{REQUEST_URI} will be used instead.

PUBLIC READ-ONLY PROPERTIES

base_href

Returns the base_href value in use for the linker object.

widgets

Returns an array of ASP4x::Linker::Widget objects assigned to the linker.

PUBLIC METHODS

add_widget( name => $str, attrs => \@attrNames )

Adds a "widget" to the widgets collection.

widget( $name )

Returns an individual ASP4x::Linker::Widget object by that name.

Returns undef if no widget by that name is found.

uri( [$properties] )

Returns the uri for all widgets based on the intersect of:

  • The incoming form data from the original request

  • Individually-set values for each widget in the collection.

  • Any properties provided as an argument to uri().

hidden_fields( [$properties] )

Returns a string of XHTML hidden input fields (<input type="hidden" name="$name" value="$value" />).

Useful if your persistence logic involves repeated form submissions rather than hyperlinks.

The $properties argument is the same as in the uri() method.

vars( [$properties] )

Returns a hashref representing the intersect of all widgets' names and attributes.

Supposing you setup your linker like this:

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

$linker->add_widget(
  name  => 'albums',
  attrs => [qw( page sort )]
);

$linker->add_widget(
  name  => 'artists',
  attrs => [qw( page sort )]
);

After calling vars() you'd get:

$VAR1 = {
  'albums.page'  => undef,
  'albums.sort'  => undef,
  'artists.page' => undef,
  'artists.sort' => undef,
};

If you did this:

$linker->vars({
  albums  => {page => 2},
  artists => {sort => 'desc'}
});

Then you'd get this instead:

$VAR1 = {
  'albums.page'  => 2,
  'albums.sort'  => undef,
  'artists.page' => undef,
  'artists.sort' => 'desc',
};

You could also do this:

$linker->widget('albums')->page( 10 );
$linker->widget('artists')->sort( 'desc' );
$linker->vars();

And you would get the same thing:

$VAR1 = {
  'albums.page'  => 2,
  'albums.sort'  => undef,
  'artists.page' => undef,
  'artists.sort' => 'desc',
};

reset( )

Resets all widgets to their original values from the original request (as specified in the base_href value used by new()).

SEE ALSO

ASP4, ASP4x::Router, Router::Generic

AUTHOR

John Drago <jdrago_999@yahoo.com>

LICENSE

This software is Free software and may be used and redistributed under the same terms as Perl itself.