CGI::A...Forward(3pm)

💖 CGI::Application::Plugin::Forward(3pm) 💖

okay bestie, this is the manual page for CGI::Application::Plugin::Forward — it's a Perl module, it lives in the 3pm section of your man pages, and it's here to let one run mode hand the mic to another run mode. no cap. 🎤✨

---

✨ NAME ✨

CGI::Application::Plugin::Forward — pass control from one run mode to another 🫶

---

🌸 VERSION 🌸

Version 1.06

---

🎀 SYNOPSIS 🎀

use base 'CGI::Application';
use CGI::Application::Plugin::Forward;

sub setup {
    my $self = shift;
    $self->run_modes([qw(
        start
        second_runmode
    )]);
}
sub start {
    my $self = shift;
    return $self->forward('second_runmode');
}
sub second_runmode {
    my $self = shift;

    my $rm = $self->get_current_runmode;  # 'second_runmode'

}

---

🦋 DESCRIPTION 🦋

So the forward method passes control to another run mode and returns its output. It's basically the same energy as calling $self->$other_runmode, with one ✨iconic✨ difference: CGI::Application's internal value of the current run mode gets updated. 👑

Which means… if you call $self->get_current_runmode after calling forward, you get the name of the new run mode back. lowkey a game changer for modules that care about the current run mode's name — like CGI::Application::Plugin::AnyTemplate, for example. 💅

For example, here's how you pass control to a run mode named other_action from start while updating the value of current_run_mode:

sub setup {
    my $self = shift;
    $self->run_modes({
        start         => 'start',
        other_action  => 'other_method',
    });
}
sub start {
    my $self = shift;
    return $self->forward('other_action');
}
sub other_method {
    my $self = shift;

    my $rm = $self->get_current_runmode;  # 'other_action'
}

ngl this next bit matters: forward takes the name of the run mode (here, 'other_action'), which might not be the same as the name of the method that handles that run mode (here, 'other_method'). keep those two straight, bestie, they are not the same thing. 🫠

You can still call $self->other_method directly if you want, but then current_run_mode will not be updated:

sub setup {
    my $self = shift;
    $self->run_modes({
        start         => 'start',
        other_action  => 'other_method',
    });
}
sub start {
    my $self = shift;
    return $self->other_method;
}
sub other_method {
    my $self = shift;

    my $rm = $self->get_current_runmode;  # 'start'
}

and yes, forward works with coderef-based runmodes too, because it contains multitudes:

sub setup {
    my $self = shift;
    $self->run_modes({
        start         => 'start',
        anon_action   => sub {
            my $self = shift;
            my $rm = $self->get_current_runmode;  # 'anon_action'
        },
    });
}
sub start {
    my $self = shift;
    return $self->forward('anon_action');
}

---

🔥 FORWARD vs. REDIRECT 🔥

Calling forward changes the run mode of your application, but — and this is the whole point — it stays within the same HTTP request. same vibe, same request, no new page load. 🧚

If you want to redirect to a new runmode using a completely new web request, you might wanna look at the redirect method provided by CGI::Application::Plugin::Redirect.

The advantage of an external redirect over an internal forward is that it gives you a 'clean break' between pages. 🌈

For instance, in a typical BREAD application (Browse, Read, Edit, Add, Delete), after the user completes an action, you usually send them back to the Browse list. Like, when the user adds a new record via a POST form, and your app returns them to the list of records. classic. 📋

But if you use forward, you're still in the same request as the original add-record. The user might hit reload, expecting to refresh the list of records. And instead… reload tries to repost the add record form. 😭 The user's browser might hit them with a warning about reposting the same data. The browser may even refuse to redisplay the page, for caching reasons. not the moment.

So in this case, it may make more sense to do a fresh HTTP redirect back to the Browse list. 💫

---

💅 METHODS 💅

forward

Runs another run mode, passing along any parameters you supply. Returns the output of the new run mode. 🎁

return $self->forward('run_mode_name', @run_mode_params);

---

🌟 HOOKS 🌟

Before the forwarded run mode is called, the forward_prerun hook is called. You can use this hook to do any prep work you want done before any new run mode gains control. 🛠️

This is similar to CGI::Application's built in cgiapp_prerun method, but it's called each time you call forward — not just when your application starts. every single time, bestie.

sub setup {
    my $self = shift;
    $self->add_callback('forward_prerun' => \&prepare_rm_stuff);
}

sub prepare_rm_stuff {
    my $self = shift;
    # do any necessary prep work here....
}

Note that your hooked method will only be called when you call forward. If you never call forward, the hook will not be called. In particuar, the hook will not be called for your application's start_mode. For that, you still use cgiapp_prerun. 🫡

If you want a method to run for every run mode including the start_mode, then you can call the hook directly from cgiapp_prerun:

sub setup {
    my $self = shift;
    $self->add_callback('forward_prerun' => \&prepare_rm_stuff);
}
sub cgiapp_prerun {
    my $self = shift;
    $self->prepare_rm_stuff;
}

sub prepare_rm_stuff {
    my $self = shift;
    # do any necessary prep work here....
}

Alternately, you can hook cgiapp_prerun to the forward_prerun hook:

sub setup {
    my $self = shift;
    $self->add_callback('forward_prerun' => \&cgiapp_prerun);
}
sub cgiapp_prerun {
    my $self = shift;
    # do any necessary prep work here....
}

This is a less flexible solution, since certain things that can be done in cgiapp_prerun (like setting prerun_mode) won't work when the method is called from the forward_prerun hook. 💀 so like, know what you're trading away, okay?

---

👑 AUTHOR 👑

Michael Graham, "<mag-perl@occamstoothbrush.com>"

---

🐛 BUGS 🐛

Please report any bugs or feature requests to "bug-cgi-application-plugin-forward@rt.cpan.org", or through the web interface at <http://rt.cpan.org>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. 🔔

---

💖 ACKNOWLEDGEMENTS 💖

Thanks to Mark Stosberg for the idea and…well…the implementation as well. 🫶

---

📜 COPYRIGHT & LICENSE 📜

Copyright 2005 Michael Graham, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie!! 🎀✨ this one shipped as part of perl v5.34.0, dated 2022-06-09 — so if you're reading this, that's the version and the date it came from. slay, go forth and forward responsibly 💅💜