Flow of Control

When a "WWW::Mechanize::Pluggable" object is instantiated, its "new" method calls each of the plugins' "init" method. Typically, "init()" exports methods back into the caller's namespace, and also calls "pre_hook" and "post_hook" to wrap any of "WWW::Mechanize"'s methods it desires.

When a "WWW::Mechanize" method is called, "WWW::Mechanize::Pluggable"'s "AUTOLOAD" takes control. It calls any pre-hooks that have been installed for the method; if any of them return a true value, the actual method call is skipped. "WW::Mechanize::Pluggable" then calls the method (if it should) using the same context in which the method was originally callled, saving the return value. The post-hooks are then called, and the return value from the method is returned to the original caller.

What you can do

• alter the parameter list
• process the call yourself
• conditionally get involved, or not
• post-process the results after the call

import

This routine is optional; it is called when your plugin is loaded by "WWW::Mechanize::Pluggable". You can use this to parameterize your plugin via arguments on the "use" statement.

It's recommended that you supply arguments as key-value pairs; this will make it possible for "WWW::Mechanize::Pluggable" to remove the "used-up" parameters from the c<use> line by returning the keys you want to have removed.

Here's a sample "import" method:

  sub import {
    my($class, %args) = @_;
    if defined(my $value = $args{'mine'}) {
      if (_is_appropriate($value)) {
        # do whatever ,,,
      }
    }
    return ("mine");
  }

This looks for the "mine" parameter on the "use". It processes it as appropriate and returns the key so that "WWW::Mechanize::Pluggable" will delete it.

init

The "init" method allows your plugin a chance to export subroutines and store information appropriate for its proper functioning in the parent "WWW::Mechanize::Pluggable" object. It also can be used to set up pre-hooks and post-hooks for methods.

Because other plugins will be doing the same thing, it's important to choose unique method names and field names. It's proabably a good idea to prefix field names with the name of your plugin, like "_MyPlugin_data".

It's possible that we may change the interface in a future release of "WWW::Mechanize::Pluggable" to support "inside-out" objects (see http://www.windley.com/archives/2005/08/best_practices.shtml for an example).

Sample init function:

  sub init {
    my($parent_object, %args) = @_;
    $parent_object->{_myplugin_foo} = "my data";
    *{caller() . '::myplugin_method'} = \&my_implementation;
    $parent_object->pre_hook('get', sub { &my_prehook(@_) } );
    $parent_object->post_hook('get', sub { &my_prehook(@_) } );
    my @removed;
    if ($args{'my_arg'}) {
       # process my_arg
       push @removes, 'my_arg';
    }
    @removed;
  }

The anonymous subroutine wrapping the hook setup currently is necessary to prevent the hook from being called during its installation; this needs to be fixed. The anonymous subroutine works for the moment, and will work in future releases, so go head and use it for now.

Also note that we have the same kind of interface that we do in "import"; you can parameterize a particular plugin by putting the parameters (key=>value-style) on the "new" and then processing them in "init", and deleting them after processing by returning the list of names.

pre_hook

Installs the referenced subroutine as a pre-hook for the named method. Currently, only "WWW::Mechanize" methods can be hooked; future releases may allow methods supplied by plugins to be hooked as well.

post_hook

Installs the referenced subroutine as a post-hook for the named method. Currently, only "WWW::Mechanize" methods can be hooked; future releases may allow methods supplied by plugins to be hooked as well.

Prehooks and posthooks

This is the subroutine that you passed a reference to in the call to either "pre_hook" or "post_hook". It can do anything you like; it has access to both the \"WWW::Mechanize::Pluggable" object and to the internal "WWW::Mechanize" object, as well as to the parameters with which the method was called.

If your code is a pre-hook, it can cause "WWW::Mechanize::Pluggable" to skip the method call altogether by returning a true value.

Sample pre-hook:

  sub my_prehook {
    my($pluggable, $mech, @args) = @_;
    
    # We'll assume that this is a hook for 'get'.
    if ($args[0] =~ /$selected_url/) {

      # alter the URL to what we want
      $args[0] =~ s/$what_we_dont_want/$what_we_do/;
    }
    # force another try with the altered URL.
    $pluggable->get(@args);

    # don't actually do the get with the old URL.
    return 'skip';
  }

We used this approach because the interface currently doesn't allow us to alter the parameter list; this is something we probably should do in the next release.

Adding a new acessor

  package WWW::Mechanize::Plugin::MyPlugin;
  use base qw(Class::Accessor::Fast);
  __PACKAGE__->mk_accessors(qw(foo bar baz));

You can now use the newly-created accessors any way you like; often you'll use them to store data for other methods that are exported to "WWW::Mechanize::Pluggable".

Adding a new method

  *{caller() . '::new_method'} = \&localsub;

This would call any subroutine or method call to new_method via the Mech::Pluggable object to be dispatched to localsub in this package.

Replacing a method

  sub init {
    pre_hook('desired_method', sub { \&substitute(@_) });

  sub substitute {
    my($pluggable, $mech, @_) = @_;
    # Do whatever you want;
    return "skip";
  }

Note the anonymous sub construct in the call to pre_hook. This is necessary because the construct "\&substitute" tries to call substitute() immediately, which we do not want.

We return "skip" as a mnemonic that a true value causes the real call to be skipped.

Retrying a method call

• take whatever action is needed to set up for the retry
• call back() on the Mech object
• repeat the last action again on the Mech object
• up the count of tries

The prehook is needed to keep the retry from going into an infinite loop.