=pod

=head1 NAME

WWW::Mechanize::Firefox::Cookbook - Recipes for using WWW::Mechanize::Firefox

=head1 Introduction

Note that WWW::Mechanize::Firefox is quite similar in its API to L<WWW::Mechanize>,
so many of the recipes in L<WWW::Mechanize::Cookbook> apply to it as well.

=head1 Basics

=head2 Launch WWW::Mechanize::Firefox

  use WWW::Mechanize::Firefox;
  my $mech = WWW::Mechanize::Firefox->new();
  $mech->get('http://google.com');

=head2 Launch WWW::Mechanize::Firefox if Firefox is not running

  use WWW::Mechanize::Firefox;
  my $mech = WWW::Mechanize::Firefox->new(
      launch => '/path/to/firefox',
  );
  $mech->get('http://google.com');

=head2 Use an existing tab

  use WWW::Mechanize::Firefox;
  my $mech = WWW::Mechanize::Firefox->new(
      tab => qr/^Google/,
  );
  $mech->get('http://google.com');

=head2 Use the current tab

  use WWW::Mechanize::Firefox;
  my $mech = WWW::Mechanize::Firefox->new(
      tab => 'current',
  );
  $mech->get('http://google.com');

=head2 Use some other tab if you have it as object

    my $app = Firefox::Application->new();
    my @tabs =  map { $_->{tab} }
               grep { $magic eq $_->{title} }
               $app->openTabs($repl);

    my $synth_mech = WWW::Mechanize::Firefox->new(
        tab => $tabs[0],
        app => $app,
    );

=head2 Bring the tab to the foreground at start

  use WWW::Mechanize::Firefox;
  my $mech = WWW::Mechanize::Firefox->new(
      activate => 1,
  );
  $mech->get('http://google.com');

=head2 Bring the tab to the foreground later

  my $mech = WWW::Mechanize::Firefox->new(
  );
  ...
  $mech->activateTab();

=head2 Fetch a page to a file

  use WWW::Mechanize::Firefox;
  my $mech = WWW::Mechanize::Firefox->new(
      tab => 'current',
  );
  $mech->get('http://google.com',
      ':content_file' => 'google_com.html' );

=head2 Fetch a page to a file with all images

  use WWW::Mechanize::Firefox;
  my $mech = WWW::Mechanize::Firefox->new(
      tab => 'current',
  );
  $mech->get('http://google.com');
  $mech->save_content('google_com.html', 'google_com files');

=head1 Advanced HTML interaction

=head2 Wait until an element appears

Some sites generate content after the C<DOMContentLoaded>
event has fired. To wait until an element becomes available,
use the following code:

    # The submit button is generated after the page has loaded

    my $retries = 10;
    while ($retries-- and ! $mech->is_visible( xpath => '//*[@id="submit"]' )) {
          sleep 1;
    };
    die "Timeout" if 0 > $retries;
    
    # Now the element exists
    $mech->click({xpath => '//*[@id="submit"]'});

=head2 Wait until an element disappears

Some sites display an hourglass or some other indicator to
tell you to wait. 
To wait until such an element becomes invisible,
use the following code:

    my $retries = 10;
    while ($retries-- and $mech->is_visible( xpath => '//*[@id="hourglass"]' )) {
          sleep 1;
    };
    die "Timeout while waiting for application" if 0 > $retries;
    
    # Now the hourglass is not visible anymore

=head1 UI interaction

=head2 Keep the tab open after your program quits

In the case that you want to navigate the user to a specific place and
then take over manually, you can prevent the automatic closing of the browser
tab. Either create your C<$mech> object like this:

  my $mech = WWW::Mechanize::Firefox->new(
      autoclose => 0,
  );

or decide at runtime whether to close the tab:

  $mech->autoclose_tab(0);

This does currently not work.

=head2 Get notified when the current tab changes

    my $browser = $mech->repl->expr('window.getBrowser()');

    my $eventlistener = progress_listener(
        $browser,
        onLocationChange => \&onLocationChange,
    );

    while (1) {
        $mech->repl->poll();
        sleep 1;
    };

=head1 Images

=head2 Save the current page as PNG

This will take a "screenshot" which also includes plugins like Flash.

  my $png = $mech->content_as_png();
  open my $fh, '>', 'page.png'
      or die "Couldn't save to 'page.png': $!";
  binmode $fh;
  print {$fh} $png;
  close $fh;

Also see the file C<screenshot.pl> included and installed through the
distribution.

=head3 Save top left corner of the current page as PNG

  my $rect = {
    left  =>    0,
    top   =>    0,
    width  => 200,
    height => 200,
  };
  my $png = $mech->content_as_png(undef, $rect);
  open my $fh, '>', 'page.png'
      or die "Couldn't save to 'page.png': $!";
  binmode $fh;
  print {$fh} $png;
  close $fh;

=head3 Save a page element of the current page as PNG

  my $shiny = $mech->selector('#shiny', single => 1);
  my $png = $mech->element_as_png($shiny);
  open my $fh, '>', 'page.png'
      or die "Couldn't save to 'page.png': $!";
  binmode $fh;
  print {$fh} $png;
  close $fh;

=head1 HTTP Interaction

=head2 Send a different hostname to the server

If you are testing a new application deployment, it may
become necessary to lie to the server about the name of
the webserver you're requesting. You can easily
switch the name around at the HTTP level by adding a
custom C<< Host: >> header:

  $mech->add_header(
      Host => 'http://example.com/',
  );
  $mech->get('http://1.2.3.4');
  # Ask the machine at 1.2.3.4 for the pages of example.com

=head1 Javascript

=head2 Check that your Page has no Javascript compile errors

  $mech->get('mypage');
  my @errors = map {$_->{message}} $mech->js_errors();
  if (@errors) {
      die "Found errors on page: @errors";
  };

=head3 Override the Javascript C<alert()> function

  $mech->eval_in_page('alert("Hello");',
      { alert => sub { print "Captured alert: '@_'\n" } }
  );

=head3 Set a value without triggering Javascript events

Just pass empty lists for the lists of events to invoke

  $mech->field( 'myfield', 'myvalue', [], [] );

=head3 Get the text of an C<onclick> handler (or other attributes)

When developing a web page, you may want to use WWW::Mechanize::Firefox
to check the text value of the C<onclick> attribute instead of treating
it as an opaque function. To get at the text attribute, you will
need the DOM function C<< ->getAttribute() >>.

    #!perl -w
    use strict;
    use WWW::Mechanize::Firefox;

    my $mech = WWW::Mechanize::Firefox->new();
    $mech->update_html(<<HTML);
    <html>
    <h1>Test</h1>
    <a href="http://google.de">Google</a>
    <a href="asdf.html" onclick="javascript:alert('hello');">Say Hello</a>
    </html>
    HTML

    my @links = $mech->find_all_links_dom(url_regex => 'asdf.html');
    foreach my $link (@links) {
        print $link->getAttribute('onclick');
    };

=head1 Not working yet

=head2 Upload a file to an C<ftp> server

B< Not implemented > - this requires instantiating and passing
a C< nsIURI > object instead of a C< nsILocalFile >.

You can use C<< ->save_url >> to I<transfer> files. C<$localname>
can be a local filename, a C<file://> URL or any other URL that allows
uploads, like C<ftp://>.

  $mech->save_url('file://path/to/my/file.txt'
      => 'ftp://myserver.example/my/file.txt');

=head1 AUTHOR

Max Maischein C<corion@cpan.org>

Contributed examples contain the original author's name.

=head1 COPYRIGHT

Copyright 2009-2012 by Max Maischein C<corion@cpan.org>.

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

=cut